Main menu

Loco Developer API

Our API makes localizing your software with Loco even more powerful.

If you have any problems or requests, just shout.

API Reference Examples File Formats API Explorer

What can I do with it?

The main thing you'll probably want to do with the Loco API is pull translation files into whatever you're building.
Check out the Export API for how to do that.

If you'd like to automate your Loco workflow further, the API allows you to programmatically add assets, manage locales and make translations. Check out some examples or browse all the available methods.

Authentication

No OAuth dance required. Working with a Loco project requires just a simple API key sent over SSL. See authentication reference

You can generate API keys from your Loco project dashboard, see here for full details.

API Resources

Loco API resources are grouped into endpoints for working with assets, locales and translations, as well as importing and exporting translation files.

See the full endpoint reference for details of every API method, or explore them in the test console below.

Rate limits

The REST API is not currently rate-limited, and we're hoping to keep it that way for as long as possible. See here for full details.

Libraries

Currently the only official Loco API client is for PHP. Get it from Github or Packagist.

We'll gladly list third party libraries here if you let us know about them.

Examples

Here's a typical workflow. We've got a brand new project, so we'll add some assets and locales and make some translations. These examples use command line cURL. Responses in green are simplified.

Add a new translatable asset

Here we post the word 'Apple' to the assets collection. The response should be 201 Created with an asset object containing an auto-generated asset ID. The default English translation is created automatically, so the translated field will be 1.

$ curl -F 'name=Apple' 'https://localise.biz/api/assets' -u <your_key>:
...
{ "id":"apple", "name":"Apple", "translated":1, "untranslated":0, ... }

Add a new project locale

Our project is only in English at the moment, so here we add French by posting to the locales collection. The response should be 201 Created with an object containing useful locale metadata.

$ curl -F 'code=fr' 'https://localise.biz/api/locales' -u <your_key>:
...
{ "code":"fr_FR", "name":"French", "plurals": { "length":2, "equation":"n > 1", "forms":["one","other"] } }

Make a translation

Now we have an asset to translate and a target locale in our project, we can create our first translation. Here we post the translated text to the desired translation endpoint. Note that the translation is posted as the raw request body in this example. We should get a 200 OK.

$ curl --data 'Pomme' 'https://localise.biz/api/translations/apple/fr' -u <your_key>:
...
{ "id":"apple", "type":"text\/plain", "translated":true, "translation":"Pomme", "revision":1, ... }

Export translations to a language pack

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

$ curl 'https://localise.biz/api/export/locale/fr.po' -u <your_key>:
...
msgid "Apple"
msgstr "Pomme"

Plurals

Loco handles plural forms as assets in their own right, but there are specific endpoints for working with them.

Here we create a plural form of an existing, singular asset by posting to its plurals collection.

$ curl -F 'name=Apples' 'https://localise.biz/api/assets/apple/plurals' -u <your_key>:
...
{ "id":"apples", "name":"Apples", "translated":1, "untranslated":1, ... }

– then we translate it as usual

$ curl --data 'Pommes' 'https://localise.biz/api/translations/apples/fr' -u <your_key>:
...
{ "id":"apples", "translated":true, "translation":"Pommes", "revision":1, ... }

Tags

Loco assets can be tagged to keep your dashboard organised and to support segmentation of your translations.

Here we tag our asset with something useful by posting to its tags collection.

$ curl -F 'name=Fruit' 'https://localise.biz/api/assets/apple/tags' -u <your_key>:
...
{"id":"apple", "name:"Apple", tags:["Fruit"], ... }

Export formats

The Export API offers more than just JSON responses. You can output your translations to a wealth of file types and language pack formats.

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
  • .tmx Translation Memory eXchange
  • .xlf .xliff Localisation Interchange File Format
  • .csv Comma separated values
  • .sql MySQL INSERT statements
  • .resx ResX for .NET framework
  • .html HTML table
  • .strings iOS Localizable strings
  • .stringsdict iOS plural rules
  • .plist .bplist Apple property list XML and binary formats
  • .properties Java properties file
  • .ts TS, an XML format for Qt Framework

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

Alternative styles

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

JSON and JavaScript formats

In addition to the default JSON format, you can specify Chrome or i18next language pack formats as follows

https://localise.biz/api/export/locale/{locale}.json?format=chrome
https://localise.biz/api/export/locale/{locale}.json?format=i18next

In addition to the default JavaScript function you can specify output for gettext.js or Angular Gettext.

https://localise.biz/api/export/locale/{locale}.js?format=gettext
https://localise.biz/api/export/locale/{locale}.js?format=ng-gettext

YAML formats

Several YAML formats are available - simple, nested and rails. The simple format is flat and only exports a single locale. The nested format supports multiple locales and contains a top-level namespace.

The rails format is specifically for Ruby on Rails and follows the conventions of the i18n module.

https://localise.biz/api/export/locale/{locale}.yml?format=rails
https://localise.biz/api/export/locale/{locale}.yml?format=nested

XML formats

In addition to the default Android format, specify java to produce Java properties XML and tizen to produce Tizen formatted XML.

https://localise.biz/api/export/locale/{locale}.xml?format=java
https://localise.biz/api/export/locale/{locale}.xml?format=tizen

Other XML formats have their own specific file extensions, such as .tmx .xlf .resx .plist .ts

iOS Localization files

In addition to the strings and stringsdict extensions, you can export an iOS-specific XLIFF file suitable for XCode's "Import Localizations" feature:

https://localise.biz/api/export/locale/{locale}.xliff?format=xcode

PHP language packs

In addition to the default Zend format, you can specify Symfony or Code Igniter or output simple constant definitions.

https://localise.biz/api/export/locale/{locale}.phps?format=symfony
https://localise.biz/api/export/locale/{locale}.phps?format=codeigniter
https://localise.biz/api/export/locale/{locale}.phps?format=constants

Note that the .phps extension is used to indicate source code output, but you can use .php if you prefer.

Import formats

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

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 Localisation Interchange File Format
  • .resx ResX for .NET framework
  • .plist .blist Apple property list and binary plist
  • .strings iOS Localizable strings
  • .properties Java properties file

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 Code Igniter language packs
  • .json any key/value pairings, with specific support for Chrome and i18next language packs.

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:

https://localise.biz/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:

https://localise.biz/api/import/{ext}?index=text&locale=fr

Note that specifying index=text implies that native language translations will be created. 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 to any non-empty value will tell Loco to run the import 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.

https://localise.biz/api/import/pot?async=1

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

https://localise.biz/api/import/progress/{id}

API Explorer

You can try the Loco API directly from this page without writing any code, but you'll need an API key for the endpoints requiring authentication.

Version 1.0.15. The Loco API is discoverable here in Swagger format.

Need help?

Try our help centre, or ask us a question

Contact us Developer support