Loco Developer API
Our API makes localizing your software with Loco even more powerful.
If you have any problems or requests, just ask.
Our API makes localizing your software with Loco even more powerful.
If you have any problems or requests, just ask.
The main thing you'll want to do with the Loco API is pull translation files into whatever you're building. Check out the Export API methods and the example below.
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.
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.
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.
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.
Currently the only official Loco API client is for PHP. Get it from Github or Packagist.
See our list of community libraries in other languages.
Here are some workflow examples. 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.
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.
$ curl --data-binary @messages.pot 'https://localise.biz/api/import/pot' -u <your_key>:
HTTP/1.1 200 Ok
{ "message": "100 translations imported, 100 new assets" ... }
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.
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.
$ curl -F'id=hello' -F'text=Hello World' 'https://localise.biz/api/assets' -u <your_key>:
HTTP/1.1 201 Created
...
{ "id":"hello", "type":"text", "progress":{"translated":1 ... }
progress
field shows that one translation exists.id=hello
a unique ID would have been automatically generated. You'll need this to reference the asset later.Our project is only in English at the moment, so here we add Spanish by posting to the locales collection.
$ curl -F 'code=es' 'https://localise.biz/api/locales' -u <your_key>:
HTTP/1.1 201 Created
...
{ "code":"es", "name":"Spanish", "plurals": { "length":2, "equation":"n != 1", "forms":["one","other"] } ... }
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.
$ curl --data-binary 'Hola Mundo' 'https://localise.biz/api/translations/hello/es' -u <your_key>:
...
{ "id":"hello", "translated":true, "translation":"Hola Mundo", "revision":1, ... }
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.
$ curl 'https://localise.biz/api/export/locale/es.po' -u <your_key>:
...
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:
$ curl 'https://localise.biz/api/export/locale/en.xml?format=android' -u <your_key>:
...
<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.
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.
$ curl -F'id=apple' -F'text=An Apple' 'https://localise.biz/api/assets' -u <your_key>:
...
{ "id":"apple", "type":"text", "progress":{"translated":1 ... }
$ curl -F'pid=apples' -F'text=%d apples' 'https://localise.biz/api/assets/apple/plurals' -u <your_key>:
...
{ "id":"apples", "type":"text", "progress":{"translated":1 ... }
pid
because the id
parameter is already bound to the singular form in the URI path.The Export API offers more than just JSON responses. You can output your translations to a wealth of file types and language pack formats.
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
Localization 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
An XML format for Qt Framework.res
.txt
ICU Resource Bundles (binary and source)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
The {format}
parameter can be used to export a more specific style of some of the formats above –
In addition to the default JSON format, you can specify ARB, Chrome, Jed and i18next language pack formats as follows:
https://localise.biz/api/export/locale/{locale}.arb
https://localise.biz/api/export/locale/{locale}.json?format=jed
https://localise.biz/api/export/locale/{locale}.json?format=chrome
https://localise.biz/api/export/locale/{locale}.json?format=i18next4
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
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
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
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.
The Import API can create assets and translations from existing language pack files of various types.
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
iOS 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 Code Igniter language packs.json
any key/value pairings, with specific support for ARB, Jed, Chrome and i18next language packs..csv
must follow a similar structure to Loco's CSV exports.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 default language "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.
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.
https://localise.biz/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:
https://localise.biz/api/import/progress/{id}
Once the operation is complete you will get a response like this:
{ "progress": 100, "success": "100 translations imported", "error": "" }
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.