Exporting for Xcode

How to export strings from Loco for updating your Xcode project

This is an overview of the various Xcode-compatible file formats you can export from Loco.

XLIFF

The recommended workflow is to export template XLIFF files from Xcode using "Export Localizations" (from the Product menu). Then import them into Loco, and work on the translations. Once you're ready to import your translations back into Xcode, you can either download the completed XLIFF files from the Loco UI, or use the Export API.

Specifying .xliff as the file extension and appending ?format=xcode will export a version of XLIFF 1.2 targeting Xcode, as follows:

curl -u <your_key>: https://localise.biz/api/export/locale/fr.xliff?format=xcode \
 > 'MyLocalizations/fr.xcloc/Localized Contents/fr.xliff'

The above command saves the XLIFF back over the version exported previously inside the .xcloc package. Once on disk, you can use Xcode's "Import Localizations" function (from the Product menu) to update your project.

For detailed XLIFF examples, see the Xcode section of Exporting XLIFF files from Loco.

String Catalogs

Xcode manages String Catalogs via .xcstrings files in the project's Localizations directory. These files are constantly updated by Xcode, so external management isn't recommended unless you're managing custom strings tables manually.

String Catalogs are multi-language files. Here's how to export your whole Loco project into your Xcode project:

curl -u <your_key>: https://localise.biz/api/export/all.xcstrings \
 > MyProject/Localizations/Custom.xcstrings

All entries in String Catalogs exported from Loco have "extractionState":"manual". This means Xcode won't remove the keys when they aren't found in your code, but it also means they won't be synchronized by Xcode if they are referenced in your code.

We recommend exporting XLIFF files from Loco and letting Xcode manage their extraction states from your code. However we offer .xcstrings exports in case you find it useful.

Binary Strings and Stringsdict files

Xcode compiles string tables into separate .strings and .stringsdict files when you build your project, but these are not source files:

This .strings file is not the same as the legacy Strings format. It's a property list, but in the binary format.
This .stringsdict file is a binary version of the legacy Stringsdict format, which was always a property list.

Loco can export .bplist files for any flat structure of key/values pairs, so - if desirable - you can export a whole strings table directly into your build directory from Loco as follows:

curl -u <your_key>: https://localise.biz/api/export/locale/en.bplist \
 > MyProject.app/en.lproj/Custom.strings -

If you have plurals (or other string variations) in your project, you can build the binary .stringdict from the legacy property list format using plutil, as follows:

curl -u <your_key>: https://localise.biz/api/export/locale/en.stringsdict \
  | /usr/bin/plutil -convert binary1 -o MyProject.app/en.lproj/Custom.stringsdict -

Strings and Stringsdict (Legacy) source files

Loco has supported the old .strings file format since day one, and that support hasn't changed since the introduction of .xcstrings.

For historical reasons these are UTF-16 encoded files, but you can request UTF-8 as shown:

curl -u <your_key>: -H 'Accept-Charset: utf8' https://localise.biz/api/export/locale/en.strings \
 > MyProject/Localizations/en.lproj/Legacy.strings

Note that this legacy format is a source file, and not the property list file that Xcode builds. It looks like this:

/* Sample greeting */
"message" = "Hello World";

If your project uses plurals, you can also export a .stringdict file, which is actually a property list XML file. Although Loco supports .plist exports, it's necessary to specify the extension as .stringsdict to produce the nested structure:

curl -u <your_key>: https://localise.biz/api/export/locale/en.stringsdict \
 > MyProject/Localizations/en.lproj/Legacy.stringsdict

This exports only plural rules from your project, for example:

<plist version="1.0">
  <dict>
    <key>new-messages</key>
    <dict>
      <key>NSStringLocalizedFormatKey</key>
      <string>%#@value@</string>
      <key>value</key>
      <dict>
        <key>NSStringFormatSpecTypeKey</key>
        <string>NSStringPluralRuleType</string>
        <key>NSStringFormatValueTypeKey</key>
        <string>d</string>
        <key>one</key>
        <string>You have a new message</string>
        <key>other</key>
        <string>You have %lld new messages</string>
      </dict>
    </dict>
  </dict>
</plist>

Please note that Loco can't yet manage device variations, or plural substitutions introduced in Xcode 15. These features will be added to .xliff, .xcstrings and .stringsdict file exports soon.