Documentation section

File Format - iOS / macOS

Learn how to use Localazy CLI for localization of your iOS and macOS apps.

For iOS and macOS apps, Localazy supports .strings, .stringsdict, .plist and XLIFF files.

The XLIFF format is supported including the Apple’s extension for plurals and is described in its own article.

.strings and .stringsdict 🔗

Typical usage:

{

  // ... other parts omitted for brevity ...

  "upload": {    
    "features": ["parse_array", "parse_plurals"],
    "files": [
      {
        "type": "ios-strings",
        "pattern": "Base.lproj/Localizable.strings"
      },
      {
        "type": "ios-stringsdict",
        "pattern": "Base.lproj/Localizable.stringsdict"
      }
    ]
  },

  "download": {
    "files": "${iosLprojFolder}/${file}"
  }

}

Using the features, you can change the encoding, enable plurals and arrays.

Encoding of .strings files 🔗

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

Arrays in .strings 🔗

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.

It’s possible to enable support for arrays using the feature parse_array. The file below will be parsed as an array instead of separate strings:

"array[7]" = "Array 7";
"array[11]" = "Array 11";
"array[27]" = "Array 27";
"array[30]" = "Array 30";

Additional metadata is stored, so Localazy can restore the indexes correctly. All valid indexes are processed where the valid index is a non-negative integer value.

Plurals in .strings 🔗

It’s possible to enable support for plurals using the feature parse_plurals. The file below will be parsed as a plural string instead of separate strings:

"plural[one]" = "You have 1 item.";
"plural[other]" = "You have {count} items.";

When parsed as plural, the translated file may contain different quantities (eg. for the Czech language). Your app should be prepared for it.

"plural[one]" = "Máte 1 položku.";
"plural[few]" = "Máte {count} položky.";
"plural[other]" = "Máte {count} položek.";

.stringsdict 🔗

As .stringsdict format is based on .plist, it’s possible to use it for more than just plurals. Localazy can handle also other data and can be used for parsing structured translations (as described below in .plist chapter). You can disable this behavior by disabling the feature parse_others (use !parse_others for disabling).

Localazy can correctly parse and translate complex plurals such as:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>

<key>geese.landed.ct</key>
<dict>
  <key>NSStringLocalizedFormatKey</key>
  <string>%1$#@[email protected] landed on %2$#@[email protected]</string>
  <key>geese</key>
  <dict>
    <key>NSStringFormatSpecTypeKey</key>
    <string>NSStringPluralRuleType</string>
    <key>NSStringFormatValueTypeKey</key>
    <string>d</string>
    <key>one</key>
    <string>A goose</string>
    <key>other</key>
    <string>%d geese</string>
  </dict>
  <key>fields</key>
  <dict>
    <key>NSStringFormatSpecTypeKey</key>
    <string>NSStringPluralRuleType</string>
    <key>NSStringFormatValueTypeKey</key>
    <string>d</string>
    <key>one</key>
    <string>1 field</string>
    <key>other</key>
    <string>%d fields</string>
  </dict>
</dict>

</dict>
</plist>

.plist 🔗

Structured .plist files can be imported for translating. Elements <array> are parsed as arrays in Localazy. No extra configuration is necessary.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>

    <!-- Comment for the strings test_key_1. -->
    <key>test_key_1</key>
    <string>Test String 1</string>

    <!-- Comment for the strings test_key_2. -->
    <key>test_key_2</key>
    <string>Test String 2</string>

    <key>test_obj</key>
    <dict>

        <key>test_obj_key_1</key>
        <string>Test Obj Key 1</string>

        <key>test_obj_key_2</key>
        <string>Tet Obj key 2</string>

        <key>test_inner</key>
        <dict>
            <key>test_inner_key_1</key>
            <string>Test Inner Key 1</string>
        </dict>

    </dict>

    <key>test_array</key>
    <array>
        <string>Array Test 1</string>
        <string>Array Test 2</string>
        <string>Array Test 3</string>
    </array>

</dict>
</plist>

By default, the .plist parser process plurals that are in the format compatible with .stringsdict as plurals. You can disable this behavior by disabling feature parse_plurals (use !parse_plurals for disabling) or skip plurals completely by leaving parse_plurals and adding skip_plurals.

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.