This version of API is discontinued and is not being maintained. Use API 2.0 instead.

Introduction


This version of API is discontinued and is not being maintained. Use API 2.0 instead.

Authentication

All requests to the API must contain the parameter api_token. You can generate read-only or read-write tokens at at your personal profile. Remember to always use read-only tokens with Lokalise iOS and Android SDK.


Requests

Lokalise API operations are performed using HTTPS GET or POST requests passing data as a request parameters for GET and URL form-encoded for POST. Request parameters in the docs below that are specified in bold are required.


Responses

Responses are encoded as JSON objects. If the operation was unsuccessful, the JSON object will contain an error code and a message.


Use command-line tool

There is Lokalise CLI tool acting as a wrapper for import and export functions. You can download a precompiled binary for different platforms.

API version: 1.0.9.3
Status: active

List projects

Returns list of the projects accessible with supplied token

METHOD
GET

ENDPOINT
https://api.lokalise.co/api/project/list

PARAMETERS
api_token string Your API token.
# Request example
curl -X GET https://api.lokalise.co/api/project/list?api_token=f4d3f29bf893dc3583e9970735e08de094e82b0"

# Response example
{
	"projects":
		[
			{
				"id":"2178052454e5eecbe36c68.09719217",
				"name":"Sample Project",
				"desc":"Lokalise sample project.",
				"created":"2015-02-05 23:14:05",
				"owner":"0"
			},
			{
				"id":"1412623154e5ef27b06bb2.34713953",
				"name":"Demo Project",
				"desc":"",
				"created":"2015-02-19 16:11:51",
				"owner":"1"
			}
		],
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Add project

Adds new project, returns ID of the project created.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/add

PARAMETERS
api_token string Your API token.
name string Name of the project.
description string Description of the project.
base_lang string Base language ISO code. Listing all language ISO codes.
# Request example
curl -X POST https://api.lokalise.co/api/project/add \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "name=Lokalise SDK" \
     -d "description=Update strings over the air." \
     -d "base_lang=en_US"

# Response example
{
	"project":
		{
			"id":"2178052454e5eecbe36c68.09719217",
		},
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Remove project

Removes project with all project assets.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/remove

PARAMETERS
api_token string Your API token.
id string Project ID to be removed.
# Request example
curl -X POST https://api.lokalise.co/api/project/remove \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"

# Response example
{
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Import data to project

Imports keys and translations to project.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/import

PARAMETERS
api_token string Your API token.
id string Project ID to perform import on.
file string Path to a local file you are importing (must be file extension any of the file formats we support). Pay attention to -F file parameter of curl.
lang_iso string File translations ISO code. Listing all language ISO codes.
replace 0/1 Enable to replace existing translations of the keys imported.
convert_placeholders 0/1 Turn on to automatically convert placeholders to Lokalise universal placeholders. Default value is 1.
icu_plurals 0/1 Enable to automatically detect and parse ICU formatted plurals in your translations.
fill_empty 0/1 If values are empty, keys will be copied to values.
distinguish 0/1 Enable to distinguish similar keys in different files.
use_trans_mem 0/1 Enable to automatically fill 100% translation memory matches.
hidden 0/1 Enable to hide newly added keys from contributors.
tags json array Tag list for newly added keys.
filename string Override the filename. Useful to add path to a filename, e.g. admin/my.json.
replace_breaks 0/1 Enable to replace \n with line break.
cleanup_mode 0/1 Enable to delete keys that are not present in Lokalise in the file being uploaded.
# Request example
curl -X POST https://api.lokalise.co/api/project/import \
     -F "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -F "id=2178052454e5eecbe36c68.09719217" \
     -F file=@"pathtofile/filename.po" \
     -F "lang_iso=en_US" \
     -F "replace=0" \
     -F "icu_plurals=1" \
     -F "fill_empty=1" \
     -F "distinguish=0" \
     -F "hidden=0" \
     -F "tags=['main release', 'supertag']"

# Response example
{
	"result":
		{
			"skipped":12,
			"inserted":140,
			"updated":93
		},
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Export project data

Performs export routine and executes specified webhooks. Returns relative file location. Prepend https://s3-eu-west-1.amazonaws.com/lokalise-assets/ to the filename returned in order to download the bundle.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/export

PARAMETERS
api_token string Your API token.
id string Project ID to perform export on.
type string File format (e.g. json, strings, xml). Must be file extenstion of any of the file formats we support. May also be "ios_sdk" or "android_sdk" for respective OTA SDK bundles.
langs json array List of languages to be exported. Don't specify to export all languages.
use_original 0/1 Enable to use original filenames/formats.
filter json array Narrow export data range. Allowed values are translated, nonfuzzy, nonhidden.
bundle_structure string Bundle file structure (used when exporting all keys to a single file per language with use_original=0).

Allowed placeholders are %LANG_ISO%, %LANG_NAME%, %FORMAT% and %PROJECT_NAME%).

Example: locale/%LANG_ISO%.%FORMAT%.

This parameter is ignored if use_original is 1.
directory_prefix string Directory prefix in the bundle (used when exporting keys to previously assigned filenames with use_original=1). Allowed placeholders are %LANG_ISO% placeholder.

Example: %LANG_ISO%/.

This parameter is ignored if use_original is 0.
webhook_url string Once the export is complete, sends HTTP POST with file payload to the URL specified. You need to prepend https://s3-eu-west-1.amazonaws.com/lokalise-assets/ to the filename once you receive the webhook in order to download the bundle.
The full_file property is not available in webhook payload.
export_all 0/1 Enable to include all platform keys.
export_empty string Setup empty string export preference. Allowed values are empty, base, skip.
include_comments 0/1 Enable to include key comments in exported file (if supported by format).
include_pids json array Other projects ID's, which keys should be included with this export.
include_tags json array Narrow export range to tags specified.
exclude_tags json array Specify to exclude keys with these tags.
export_sort string Export key sort mode. Allowed value are first_added, last_added, last_updated, a_z, z_a.
replace_breaks 0/1 Enable to replace line breaks in exported translations with \n.
yaml_include_root 0/1 (YAML export only). Enable to include language ISO code as root key.
json_unescaped_slashes 0/1 (JSON export only). Enable to leave forward slashes unescaped.
java_properties_encoding string Encoding for .properties files. Allowed values are utf-8 and latin-1.
java_properties_separator string Separator for keys/values in .properties files. Allowed values are = and :.
no_language_folders 0/1 Don't use directory prefix. This is a legacy parameter, similar to specifying directory_prefix=''
triggers json array Trigger integration exports (must be enabled in project settings). Allowed values are amazons3, gcs, github.
plural_format string Override the default plural format for the file type. Allowed values are json_string, icu, array, generic, symfony, i18n. See Plurals and placeholders for more information.
icu_numeric 0/1 When enabled, plural forms "zero", "one" and "two" will be replaced with "=0", "=1" and "=2" respectively. Only works for icu plural format.
placeholder_format string Override the default placeholder format for the file type. Allowed values are printf, ios, icu, net, symfony). See Plurals and placeholders for more information. information.
escape_percent 0/1 When enabled, all universal percent placeholders "[%]" will be always exported as "%%". Only works for printf placeholder format.
indentation 1sp, 2sp, 3sp, 4sp, 5sp, 6sp, 7sp, 8sp, tab When provided, supported file formats will be reindented.

Supported file formats are strings, stringsdict, xliff, plist, xml, resx, json, js, react_native, symfony_xliff, xlf, yaml, ruby_yaml, ts.

Please note, that tab cannot be used with yaml or ruby_yaml.
# Request example
curl -X POST https://api.lokalise.co/api/project/export \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217" \
     -d "type=po" \
     -d "use_original=0" \
     -d "langs=['en_US']" \
     -d "include_tags=['supertag']" \
     -d "filter=['translated', 'nonfuzzy']" \
     -d "bundle_filename=%PROJECT_NAME%-Locale.zip" \
     -d "bundle_structure=%LANG_ISO%.lproj/Localizable.%FORMAT%"

# Response example
{
	"bundle":
		{
			"file":"\/export\/Sample_locale.zip",
			"full_file":"https:\/\/s3-eu-west-1.amazonaws.com\/lokalise-assets\/export\/Sample_locale.zip"
		},
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Upload screenshot

Uploads a screenshot to the project.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/screenshot

PARAMETERS
api_token string Your API token.
id string Project ID to upload screenshots to.
screenshot string The screenshot, base64 encoded. Supported file formats are JPG and PNG.
autotag 0/1 Perform OCR on the screenshots for automatic matching.
key_ids json array Link the screenshot to keys. Use /string/list method to find out key IDs.
# Request example
curl -X POST https://api.lokalise.co/api/project/screenshot \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217" \
     --data-urlencode "screenshot=data:image/png;base64,iVBORw0KGgoAAA...." \
     -d "key_ids=['7744137','7744138']"

# Response example
{
    "response":
        {
            "status":"success",
            "code":"200",
            "message":"OK"
        }
}

Create project snapshot

Creates project snapshot, that can be restored in project settings.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/snapshot

PARAMETERS
api_token string Your API token.
id string Project ID to be snapshot.
title string Optional snapshot title.
# Request example
curl -X POST https://api.lokalise.co/api/project/snapshot \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"

# Response example
{
    "response":
        {
            "status":"success",
            "code":"200",
            "message":"OK"
        }
}

Empty project

Deletes all keys and translations from the project.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/project/empty

PARAMETERS
api_token string Your API token.
id string Project ID to be emptied.
# Request example
curl -X POST https://api.lokalise.co/api/project/empty \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"

# Response example
{
    "response":
        {
            "status":"success",
            "code":"200",
            "message":"OK"
        }
}

List system languages

Lists languages supported by Lokalise.

METHOD
GET

ENDPOINT
- https://api.lokalise.co/api/language/listall

PARAMETERS
api_token string Your API token.
# Request example
curl -X GET https://api.lokalise.co/api/language/listall?api_token=f4d3f29bf893dc3583e9970735e08de094e82b0

# Response example
{
	"languages":
		[
			{
				"iso":"en",
				"name":"English",
				"rtl":"0"
			},
			{
				"iso":"en_US",
				"name":"English (United States)",
				"rtl":"0"
			}

			...

		],
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

List languages

Lists languages in the project.

METHOD
GET

ENDPOINT
- https://api.lokalise.co/api/language/list

PARAMETERS

api_token string Your API token.
id string Project ID to be list languages.

# Request example
curl -X GET https://api.lokalise.co/api/language/list?api_token=f4d3f29bf893dc3583e9970735e08de094e82b0&id=2178052454e5eecbe36c68.09719217"

# Response example
{
	"languages":
		[
			{
				"iso":"en_US",
				"name":"English (United States)",
				"words":"11203",
				"rtl":"0",
				"is_default":"1"
			},
			{
				"iso":"he",
				"name":"Hebrew",
				"words":"10909",
				"rtl":"1",
				"is_default":"0"
			}
		],
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Add languages

Adds language to a project.

METHOD
POST

ENDPOINT
- https://api.lokalise.co/api/language/add

PARAMETERS

api_token string Your API token.
id string Project ID to add languages to.
iso json array List of language ISO codes to add.

# Request example
curl -X POST https://api.lokalise.co/api/language/add \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "iso=['ru_RU', 'en_GB']"
     -d "id=2178052454e5eecbe36c68.09719217"

# Response example
{
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Set language properties

Set custom language code and/or name.

METHOD
POST

ENDPOINT
- https://api.lokalise.co/api/language/set

PARAMETERS

api_token string Your API token.
id string Project ID to add languages to.
original_iso string Original ISO code of the language you are modifying (e.g. custom_1).
custom_iso string Custom language code to assign for the language
custom_name string Custom language name for the language

# Request example
curl -X POST https://api.lokalise.co/api/language/set \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"
     -d "original_iso=ru"
     -d "custom_iso=ru-RUSSIA"
     -d "custom_name=Russki"

# Response example
{
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Remove languages

Removes language from the project.

METHOD
POST

ENDPOINT
- https://api.lokalise.co/api/language/remove

PARAMETERS

api_token string Your API token.
id string Project ID to add languages to.
iso json array List of language ISO codes to remove.

# Request example
curl -X POST https://api.lokalise.co/api/language/remove \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "iso=['lv_LV', 'ru']"
     -d "id=2178052454e5eecbe36c68.09719217"

# Response example
{
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

List pairs by language

Returns project keys and translations.

You do not need to invoke this call for every visitor of your web or app. Store the response locally (in a file or a database) and serve your visitors the local version.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/string/list

PARAMETERS
api_token string Your API token.
id string Project ID to list keys and values.
langs json array Narrow results by specified language ISO codes.
Leave empty to include all.
platform_mask int Narrow results by platform bitmask. 1 for iOS, 2 for Android, 4 for Web and 16 for Other. You can set multiple platforms by combining bitmasks (e.g. iOS and Android would be 1 + 2 = 3).
keys json array List of keys to include.
tags json array List of tags to include.
plural_format string Override the default plural format for the file type. Allowed values are json_string, icu, symfony. See Plurals and placeholders for more information.
icu_numeric 0/1 When enabled, plural forms "zero", "one" and "two" will be replaced with "=0", "=1" and "=2" respectively. Only works for icu plural format.
placeholder_format string Override the default placeholder format for the file type. Allowed values are printf, ios, icu, net, symfony). See Plurals and placeholders for more information. information.
# Request example
curl -X POST https://api.lokalise.co/api/string/list \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217" \
     -d "langs=['en', 'ru']"

# Response example
{
  "strings": {
    "en": [
      {
        "key": "appstore.app.title",
        "translation": "Lokalise",
        "plural_key": null,
        "platform_mask": 16,
        "is_hidden": "0",
        "created_at": "2015-02-05 23:14:58",
        "tags": [],
        "modified_at": "2015-02-05 23:21:20",
        "fuzzy": "0",
        "context": null,
        "is_archived": "0"
      },
      {
        "key": "index.welcome",
        "translation": "Joined string, for on iOS and Android",
        "plural_key": null,
        "platform_mask": "3",
        "is_hidden": "0",
        "created_at": "2015-02-05 23:17:27",
        "tags": [
          "tag 1",
          "tag 2",
          "tag 3"
        ],
        "modified_at": "2015-02-05 23:17:27",
        "fuzzy": "0",
        "context": null,
        "is_archived": "0"
      },
    ]
  },
  "response": {
    "status": "success",
    "code": "200",
    "message": "OK"
  }
}

Add or update keys and translations

Adds or updates keys and/or translations in the project.

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/string/set

PARAMETERS
api_token string Your API token.
id string Project ID to list keys and values.
data json array Keys/transations data to update. See example. Note, if you only need to update some specific attribute of the key (for example tags or hidden), only include key name and attribute in the data payload and omit the rest. When adding new key, platform_mask parameter is required. To set filename, use filename_ios and/or filename_android, filename_web or filename_other depending on platform.

Platform bitmasks are 1 for iOS, 2 for Android, Platform bitmasks are 1 for iOS, 2 for Android, 4 for Web and 16 for Other. You can set multiple platforms by combining bitmasks (e.g. iOS and Android would be 1 + 2 = 3).
# Request example
curl -X POST https://api.lokalise.co/api/string/set \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217" \
     --data-urlencode 'data=[ \
           { \
              "key": "app.slogan", \
              "platform_mask": 1, \
              "context": "", \
              "description": "This is our slogan", \
              "filename_web": "en.po", \
              "hidden": 1, \
              "tags": ["main", "whatsnew"], \
              "translations": { \
                 "en_US": "Localization made easy", \
                 "ru": "Локализация – это просто" \
              } \
           }, \
           { \
              "key": "app.user.online", \
              "platform_mask": 2, \
              "plural": 1, \
              "translations": { \
                 "en_US": { \
                    "one": "Just one user online", \
                    "other": "There are %d users online" \
                 } \
              } \
           }, \
           { \
              "key": "show.projects", \
              "platform_mask": 3 \
           } \
        ]'

# Response example
{
	"result":
		{
			"inserted":"12",
			"updated":"4"
		},
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Remove keys with translations

Removes keys with translations from project

METHOD
POST

ENDPOINT
https://api.lokalise.co/api/string/remove

PARAMETERS
api_token string Your API token.
id string Project ID to remove keys with translations from.
keys json array List of keys to remove.
# Request example
curl -X POST https://api.lokalise.co/api/string/remove \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217" \
     -d "keys=['app.name', 'app.slogan']"

# Response example
{
	"response":
		{
			"status":"success",
			"code":"200",
			"message":"OK"
		}
}

Plurals and placeholders

In most cases we will properly export plurals and placeholders to the file format of your choice, however it is possible to override the default universal placeholder conversion behaviour and plural format export options. Use the table below to specify with the export parameters.

File format  Compatible plural formats Compatible placeholder formats
android_sdk generic printf
ios_sdk generic ios
xml generic printf
strings generic ios
csv json_string, icu printf, ios, icu, net, i18n, raw
xlsx json_string, icu printf, ios, icu, net, i18n, raw
po generic printf, icu, raw
properties json_string, icu printf, icu
json json_string, icu, symfony, array, i18next printf, ios, icu, net, symfony, i18n, raw
xliff generic, json_string, icu printf, ios, icu, raw
plist json_string, icu printf, ios, icu
resx json_string, icu net
js json_string, icu, symfony, array, i18next printf, icu, symfony, i18n, raw
react_native json_string, icu, array printf, ios, icu, i18n, raw
symfony_xliff json_string, icu, symfony printf, icu, symfony, raw
xlf json_string, icu printf, icu, raw
php json_string, icu, symfony, array printf, icu, symfony, i18n, raw
ini json_string, icu printf, icu
ruby_yaml json_string, icu, array printf, icu
yaml json_string, icu, symfony, array printf, icu, symfony, i18n, raw
stf json_string, icu printf, icu
ts generic printf, icu

Plural format descriptions

generic Generic plural implementation of the selected file format
json_string {"one":"One user online","other":"%s users online"}
icu {index.hero.title, plural, one {One user online} other {%s users online}}
array Returns an array (if applicable in the format)
i18next {"key": "One apple", "key_plural": "Many apples"}
symfony One apple|Many apples

Placeholder format descriptions

Example string: My name is [%s:name]. I have [%.2f] dollars.

printf Printf-style placeholders - "My name is %s. I have %.2f dollars.".
ios iOS-style placeholders - "My name is %@. I have %.2f dollars."
icu ICU Message Format placeholders - "My name is {name}. I have {0} dollars."
net .NET placeholder format - "My name is {0}. I have {0:0.00} dollars."
symfony Symfony placeholder format - "My name is %name%. I have %placeholder_1% dollars."
i18n i18n placeholder format - "My name is {name}}. I have {{0}}."
raw No processing will be applied.

Error codes

A request may return an error code.

401 - Request missing API token

4011 - Invalid API Token

4012 - No data sent using POST method

403 - You don't have permission to access this resource

404 - Invalid API Call

4040 - Custom error message

4042 - Data should be JSON

4043 - Wrong language code

4044 - Project not containing specified language

4045 - No language specified

4046 - Invalid file

4047 - Invalid export type

4048 - Too many upload requests in a short period of time

4049 - Missing request parameter (the required one)

4050 - Language already in the project