Main menu

API Documentation

Quick start guide

  1. Create a project — Sign in and create a new project from the dashboard.
    You might want to add some data manually before your first API test.

  2. Get an API key — See API keys for how to do this.
    You can check it works from the API reference without writing any code, or see the authentication guide.

  3. Try it out — If you've added some data already, try exporting your source strings as follows:

    curl -u $API_KEY: 'https://localise.biz/api/export/template.pot'

  4. Start building — Browse the API reference or walk through the workflow examples.
    There may already be a client library for your platform, but let us know if you build your own!

Core APIs

The most commonly used APIs are those that move translation data in an out of Loco.

Other resource APIs

APIs exist for working with most other entities in a translation project.

  • Assets API
    For creating, updating and deleting translatable assets.
  • Locales API
    For creating, updating and deleting locales.
  • Tags API
    For creating, renaming and deleting project tags.
  • Translations API
    For translating your assets individually.

See the full API reference for all endpoints.

Authentication

Working with a Loco project via the API requires just a simple key, sent either as a request header or in the query string:

Authorization header

The preferred method of authentication is to send your key in the Authorization request header as shown in the raw HTTP request below:

GET /api/auth/verify HTTP/1.1
Host: localise.biz
Authorization: Loco $API_KEY

Basic authorization is also supported. This can be useful when testing via command line curl as shown below. Note the trailing colon indicating a blank password - this avoids a password prompt in your scripts.

$ curl -u $API_KEY: https://localise.biz/api/auth/verify

Query string key parameter

You can also send your key by appending endpoints with the key parameter as shown in the URI below:

https://localise.biz/api/auth/verify?key=$API_KEY

The query string method is convenient when you're not able to set request headers, such as sending somebody a download link or testing in a browser. Note that this method will show your key in our server logs, so is the least secure method. Headers are never logged.

We recommend you only use the query string for export keys, and always use the header for full access keys.

RESTfulness

CRUD operations are mapped to HTTP methods as follows: POST (Create), GET (Read), PATCH (Update) and DELETE (erm.. Delete).

If your client doesn't support fancy HTTP verbs then you may send the method you want as a POST field: e.g. REQUEST_METHOD=DELETE or REQUEST_METHOD=PATCH

Usage limits

The Loco API is not currently rate limited, but there are measures in place to prevent abuse. In lieu of enforced usage caps, please observe our fair usage policy. Stricter rate limiting is likely to be introduced in future. Any such changes will be communicated to all API users before they are rolled out.

Versioning

The current major version of the API is "1", and has remained largely backward-compatible since it was launched. See the changelog for the latest version number and what has changed in each release.

Breaking changes are rare, but to protect yourself from future changes you can request a specific version by appending the "v" parameter to endpoint URIs. e.g. ?v=1.0. Without this parameter you'll get the bleeding edge version of each endpoint. Alternatively you can send the required version in the X-Api-Version header.

The version number (major.minor.patch) will be incremented from time to time as follows:

  • patch: Discreet improvements including new optional parameters. Fully backward-compatible with existing client code.
  • minor: When parameters are deprecated or removed. Client code that doesn't request a specific version may need updating.
  • major: When a new version of the API is totally incompatible with the previous.

Client libraries

We'll gladly list third party libraries if you tell us about them. So far we know about the following projects:

PHP

JavaScript / Node

Java / Android

CLI

  • marten-cz/loco-cli – (in Python), provides push/pull functionality for syncing translations.
  • robrechtme/loco-cli - (in JavaScript), provides push/pull functionality for syncing translations.

Please note that these are not recommendations. They may be out of date, and we can't provide support for third party products.