Documentation section

File Format - Microsoft Excel

Learn how to use Localazy CLI for app and software localization with translations in Microsoft Excel (XLS, XLSX) files.

With Localazy, you easily use Microsoft Excel files (both XLS and XLSX) to localize your mobile, web, or desktop apps as well as marketing materials, tags, social posts, documentation, etc.

Input format 🔗

Localazy automatically detects file type for old XLS (Microsoft Excel 2003 and below) and new XLSX (Microsoft Excel 2007+) and parses it accordingly. No extra configuration is necessary. The output file is generated in the same format as the input.

The expected format is as shown below. See Columns for details on how to configure multilingual support and the column order.

Key Translation Comment
Key 1 Translation Comment for translator
Key 2 Translation
Key 3 Translation

Localazy extracts localizable assets but doesn’t store information about formatting, number format, etc. It also doesn’t calculate formulas - they are parsed as text only. Therefore, the output format (as described below) can be slightly different.

Only the first sheet is used. Other sheets are ignored.

By default, Localazy expects the first row to be a header. If your file doesn’t have the header, you can notify Localazy that it shouldn’t skip the first line by adding no_header to features in the upload section.

The header is always required for multilingual files (see below) as it’s used for determining the language.

Columns 🔗

Multilingual files 🔗

Add multilingual to features in the upload section to enable support for multilingual files. In multilingual files, instead of having one file per language, each language has its own column.

Defining columns 🔗

You can define how to read the file - which column is the key, which one is the comment for the translator, and where to look for translations.

To define the configuration, add columns=key,content to the features in the upload section. These types can be used for defining the configuration:

Type Description
key Mark the column from which to read the key. Must be defined and can be used only once.
comment Mark the column from which to read the comment for the translator. Optional and can be used only once if defined.
- Mark the column to skip. Optional, can be used multiple times.
content Mark the column (for single-language files) or more columns (for multilingual files) from which to read translations. Must be defined and can be used only once.

The default configuration is columns=key,content.

For single-language files, the columns are defined from left to right. For multilingual files, the columns are also defined from the left to right, but content is spread across as many columns as possible.

Single-language file example

Let’s suppose that the input file has this format:

key comment line english czech
Key 1 Comment for Key 1 105 English for Key 1 Czech for Key 1

With configuration columns=key,comment,-,content, the first column is used as the key, the second one as a comment for the translator, the third one is skipped, the fourth is the actual translation and the rest of the file is ignored.

The language for the translation is determined from the configuration in CLI and not from what is in the header!

Multilingual file example

Let’s suppose that the input file has this format:

key line en cs fr comment reference
Key 1 105 Text EN Text CS Text FR Comment 1 ref #1

To read this file correctly, it’s necessary to use configuration columns=key,-,content,comment,-.

The first column is used as the key, the second one is skipped. The last column is skipped and the sixth column is used as the comment for the translator. All columns in between are processed as translations in English, Czech, and French.

The language for the translation is determined from the file header and not from the configuration of CLI!

Using key as the source translation 🔗

If the key is also the source language translation, it’s possible to enable support for this format by adding source_is_key to features in the upload section.

Example file:

en cs
Hello world Ahoj světe

With source_is_key and configuration columns=key,content, the first column en is parsed both as key and as the source language translation.

Arrays 🔗

Add array_br to features in the upload section to enable parsing of the following format as an array.

key translation
key[0] Item 1
key[1] Item 2
key[2] Item 3

Plurals 🔗

Beware that plurals may lead to different output for translated files due to how plurals are handled in different languages (see below in output format).

Localazy knows the rules for different languages and adapts its interface to assist translators to correctly translate all mandatory forms.

Allowed plurals types are: zero, one, two, few, many, other.

Defined by suffix 🔗

Several variants are available, and you can enable any of them and even combine them together. Localazy remembers how the plurals are formatted in the input file and keeps the same format for the translated files.

Add desired variants below to features in the upload section:

  • plural_postfix_sd for single dot variant.
  • plural_postfix_dd for colon variant.
  • plural_postfix_us for underscore variant.
  • plural_postfix_cc for camelCase variant.
  • plural_postfix_br for [brackets] variant.


Key Translation
single_dot[one] There is one user.
single_dot[other] There are $number users.
colon:one There is one user.
colon:other There are $number users.
underscore_one There is one user.
underscore_other There are $number users.
camelCaseOne There is one user.
camelCaseOther There are $number users.
brackets[one] There is one user.
brackets[other] There are $number users.

Defined using ICU 🔗

Enabled by plural_icu in features in the upload section.

Key Translation
users There are {COUNT, plural, one {one user} other {# users}}.

Only one ICU plural can be used in the string as otherwise, it wouldn’t be possible to convert it to a specific Localazy plural structure. If more than two ICU plurals are contained, the string is kept in the original form.

Allowed plurals types are: zero (=0), one (=1), two (=2), few, many, other.

Other ICU types like gender, number, etc. can be used but will not be converted and will be kept in string in the original form.

Output format 🔗

As Localazy extracts the localizable assets from the file without additional data such as formatting, column order, etc., the output file is always generated in the following format:

Single-language files 🔗

key xx
Key1 translation in XX
Key2 translation in XX

The header row is omitted if the input format didn’t contain the header.

Multilingual files 🔗

key en fr pl
Row1 EN translation FR translation PL translation
Row2 EN translation FR translation PL translation

Locale format 🔗

You can change the locale format in the header by adding lang_format=xx to features in the upload section where xx is one of:

  • ll-rr#scrp
  • ll-rr-scrp
  • ll-scrp-rr
  • ll-scrp_rr
  • ll_rr_scrp
  • ll_scrp_rr
  • ll+rr+scrp
  • ll+scrp+rr
  • locale_name
  • bcp
  • android_noscript
  • android

For example, if you add lang_format=locale_name, the output file will be like:

key English French Polish
Row1 EN translation FR translation PL translation
Row2 EN translation FR translation PL translation

Plurals 🔗

Plural forms for languages that don’t support them are kept empty like in the example below.

key English Czech
row[one] One user Jeden uživatel
row[few] {count} uživatelé
row[other] {count} users {count} uživatelů