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 needs only to 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 the supported import formats for a complete list.

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.

...
msgid "Hello World"
msgstr "Hola Mundo"

You'll notice that the PO file hasn't used 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.