Importing an existing file

The most common starting point for using Loco is to get an existing batch of source strings into your dashboard. This example imports a Gettext POT file into a fresh project which need only contain our default language for now.

HTTP/1.1 200 Ok
{ "message": "100 translations imported, 100 new assets" ... }

• The summary message shows that 100 new assets were added, each with a translation in our source locale.
• See the import endpoint documentation for the complete format of the response data.
• See below for the complete list of supported file formats.

This is the quickest way to get started, but the API provides more fine-grained control than simply importing and exporting whole files. See below for some more specific actions you could automate.

Add a new translatable asset

Most operations in Loco revolve around assets. Importing them from an existing file is the quickest route, but the API also lets you add them individually. Here we post the string "Hello World" to the assets collection to create a new translatable item.

HTTP/1.1 201 Created
...
{ "id":"hello", "type":"text", "progress":{"translated":1 ... }

• A default translation is created automatically, so the progress field shows that one translation exists.
• If we hadn't specified id=hello a unique ID would have been automatically generated. You'll need this to reference the asset later.

Add a new project locale

Our project is only in English at the moment, so here we add Spanish by posting to the locales collection.

HTTP/1.1 201 Created
...
{ "code":"es", "name":"Spanish", "plurals": { "length":2, "equation":"n != 1", "forms":["one","other"] } ... }

• The response is a locale object containing useful metadata including plural forms.

Make a translation

Now that we have an asset to translate and something to translate it into, we can create our first translation. Here we post the translated text to the translation endpoint. Note that the translation is posted as the raw request body.

...
{ "id":"hello", "translated":true, "translation":"Hola Mundo", "revision":1, ... }

• Note the revision number is "1" because it's the first Spanish translation of this asset.
• Repeated calls to this method will simply update the translation and increment the revision number.

Export translations

Finally we want to export all our translations to the file format we're using in our software. Here we use the Export API to pull our Spanish translations into a Gettext PO file. See the full list of export formats below.

...
msgid "Hello World"
msgstr "Hola Mondo"

You'll notice that the PO file hasn't used use our unique "hello" ID. This is the nature of PO files - the source text is used instead of a language-agnostic key. Compare that with what an Android XML file would look like for our English translations:

...
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <string name="hello">Hello World</string>
</resources>

Loco can work with or without language-agnostic keys. The import and export APIs provide you full control over this, so you can manage the same set of translations over multiple platforms.

Plurals

Loco handles plural forms as assets in their own right, but there are specific endpoints for binding them together. Here we create a singular asset and then link a plural form by posting to its plurals collection.

...
{ "id":"apple", "type":"text", "progress":{"translated":1 ... }

...
{ "id":"apples", "type":"text", "progress":{"translated":1 ... }

• Note that when binding the plural form we specify pid because the id parameter is already bound to the singular form in the URI path.

File extensions

The following language pack formats can be exported by specifying the relevant file extension:

• .pot .po .mo Gettext PO, POT and binary MO
• .xlf .xliff Localization Interchange File Format
• .tmx Translation Memory eXchange
• .csv Comma separated values
• .html HTML table
• .strings .xcstrings iOS/Xcode Localizable strings
• .stringsdict iOS/Xcode plural rules
• .plist .bplist Apple property list XML and binary formats
• .properties Java properties file
• .ts An XML format for Qt Framework
• .res .txt ICU Resource Bundles (binary and source)
• .resx ResX for .NET framework
• .sql MySQL INSERT statements

The following extensions are used for mutiple formats, but have a default:

• .json Defaults to simple JSON structure, see alternative JSON formats
• .xml Defaults to Android string resources, see alternative XML formats
• .yml Defaults to Symfony-style flat structure, see alternative YAML formats
• .php Defaults to Zend-style array, see alternative PHP formats

Alternative styles

The {format} parameter can be used to export a more specific style of some of the formats above –

File extensions

The following language pack formats can be imported by specifying the relevant file extension:

• .po .pot .mo Gettext PO, POT and binary MO
• .ts TS for Qt Framework
• .tmx Translation Memory eXchange
• .xlf Localization Interchange File Format
• .resx ResX for .NET framework
• .plist .blist Apple property list and binary plist
• .strings .xcstrings iOS/Xcode Localizable strings
• .properties Java properties file
• .res .txt ICU Resource Bundles (binary and source)

The following file formats can differ in structure, so Loco will attempt to parse numerous variations:

• .yml flat and nested structures for Symfony and Ruby on Rails
• .xml Android, Java and Tizen XML structures
• .php any PHP source code, with specific support for Symfony, Zend and CodeIgniter language packs
• .json any key/value pairs, with specific support for ARB, Jed, Chrome and i18next language packs.
• .csv must follow a similar structure to Loco's CSV exports.

Disambiguating

If you're importing a generic format such as JSON, Loco gives you some control over what's imported.

Consider a structure like {"foo":"Bar"}. This could be an asset with ID "foo" mapped to the English translation "Bar", or it could be an English word "foo" mapped to the French translation "Bar".

The {index} parameter specifies whether the translations in your file are indexed by asset IDs or source texts. In combination with the {locale} parameter, the ambiguous example above can be handled however it was intended.

The following form tells Loco that the file is indexed by asset IDs and the texts should be imported as English translations:

The following form tells Loco that the file is indexed by source language texts and you also want to import the translations as French:

Note that specifying index=text implies that default "translations" (i.e. source texts) will be created if they don't exist already. When specifying index=id you must set the {locale} parameter so Loco knows what language the file contains.

Format hint

In some cases a file extension isn't sufficent to convey the precise schema of the file. Loco will try to auto-detect schemas when possible, but it's a good idea to specify. The following will help Loco parse generic file types as expected.

Asynchronous import

If you're importing a large file, it's recommended to specify the {async} parameter. Setting this tells Loco to run the import operation in the background. This will avoid connection timeouts if the import takes more than a few seconds.

The following example imports a POT file asynchronously.

The Location header obtained from the response can be used to check the progress of the import. That URL takes the following form:

Once the operation is complete you will get a response like this: