Import formats

The Import API can create assets and translations from existing language pack files of various types.

For help with specific translation file formats, see the general help section for your platform.

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
.tbx — TBX TermBase eXchange
.xlf .xliff — Localization Interchange File Format
.resx — ResX for .NET framework
.plist .bplist — 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
.tsv — tab-delimited equivalent of CSV exports
.ini — INI file (Symfony-style, same as the PHP INI export)

Format hint

In some cases a file extension isn't sufficient 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.

/api/import/json?format=multi
/api/import/yaml?format=rails

The format parameter here is analogous to that of the Export API, but is only required when the file itself is unable to self-declare its schema.

Indexing

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:

/api/import/{ext}?index=id&locale=en

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

/api/import/{ext}?index=text&locale=fr

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.

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:

/api/import/pot?async

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

/api/import/progress/{id}

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

{ "progress": 100, "success": "100 translations imported", "error": "" }