Documentation section

File Format - INI

Learn how to use Localazy CLI for app and software localization with translations in INI files.

INI files are supported and with Localazy, it’s possible to use also plurals and arrays for more comfortable and accurate translations.

Encoding 🔗

The default encoding is UTF-8. You can change it by including encoding={encoding} in the upload section. Available options are: utf8, utf16, utf16le, utf16be, ansi.

Multilingual INIs 🔗

Multilingual INIs allow defining more languages inside a single file. Localazy supports multilingual INIs with all the features described in this document.

The top-level elements must be locale codes, and the corresponding source language as set in the project must be included.

The multilingual support must be enabled by adding multilingual to features in the upload section.

[en]
key = in English

[cs]
key = in Czech

Locale codes can be defined using one of the supported methods:

  • LL_RR_Scrp
  • LL_Scrp_RR
  • LL_RR#Scrp
  • LL-RR-Scrp
  • LL-Scrp-RR
  • LL-RR#Scrp
  • LL+RR+Scrp
  • LL+Scrp+RR

Where LL is the language code (ISO 639-1), RR is the region code (ISO 3166-2), Scrp is the script code (ISO 15924). Parameters RR and Scrp can be omitted.

If the locale is not known to Localazy, it’s skipped during the processing of uploaded files.

Arrays 🔗

Arrays are good but beware of changing the number of items to prevent mismatching translations. If your files contain incomplete arrays, don’t use array features at all.

Using arrays in INI is not standard. However, Localazy can parse the suffixed variant shown below and present it to translators in a way that keeps items together and thus improves context and translation quality.

This feature can be enabled by adding array_br to features in the upload section.

[game]
difficulty[0]=easy
difficulty[4]=normal
difficulty[7]=hard
difficulty[9]=extreme

The code above will be processed as an array and additional metadata will be stored, so Localazy can restore the indexes correctly.

All valid indexes are processed where valid index is non-negative integer value.

Plurals 🔗

Beware that plurals may lead to different output for translated files due to how plurals are handled in different languages.

# English has only two plural forms:
items[one]=You have 1 item.
items[other]=You have %d items.
  
# Czech has three plural forms:
items[one]=Máte 1 položku.
items[few]=Máte %d položky.
items[other]=Máte %d položek.

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

Your app should be able to handle this. We are also working on SDK to help you with this task.

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

Suffixed with camelCase 🔗

This feature can be enabled by adding plural_postfix_cc to features in the upload section.

Example:

usersOne=There is one user.
usersOther=There are $number users.

Suffixed with brackets 🔗

This feature can be enabled by adding plural_postfix_br to features in the upload section.

Example:

users[one]=There is one user.
users[other]=There are $number users.

Defined using ICU 🔗

This feature can enabled by adding plural_icu to features in the upload section.

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 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.

Filtering untranslated strings 🔗

By default, when the output file is generated, Localazy uses texts from the source languages when the translation in the exported language is missing.

This approach is safeguarding you from missing keys that can lead to crashes in some solutions/frameworks.

This feature can be disable by adding filter_untranslated to features in the upload section and reuploading your source language file.

Forced escaping 🔗

By default, the output file doesn’t use escaping sequences if not required. By adding force_escaping to features in the upload section, you can force more aggressive escaping for better compatibility.