Introduction

Lokalise API operations are performed using HTTPS GET or POST requests passing data as request parameters for GET and URL form-encoded for POST. The endpoinds for requests are listed below.

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

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

Request parameters in the docs below that are specified in bold are required.

API version: 1.0.9.3
Status: active

Authentication

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

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.
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.
hidden 0/1 Enable to hide newly added keys from contributors.
tags json Tag list for newly added keys.
replace_breaks 0/1 Enable to replace \n with line break.
# 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 "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.
langs json List of languages to be exported. Don't specify to export all languages.
use_original 0/1 Enable to use original filenames/formats (bundle_structure parameter is ignored then).
filter string Narrow export data range. Allowed values are translated, nonfuzzy, nonhidden.
bundle_structure string Bundle folder structure. You can use placeholders %LANG_ISO%, %LANG_NAME%, %FORMAT% and %PROJECT_NAME%).

Example: locale/%LANG_ISO%.%FORMAT%
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.
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 Other projects ID's, which keys should be included with this export.
tags json Narrow export range to tags specified.
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.
# 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 "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"
		},
	"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.
# 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":"1"
			}
		],
	"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 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"
		}
}

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 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.

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 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, for example 5 would be 1+2 = iOS and Android.
keys json List of keys to include.
# 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 Keys/transations data to update. See example below. 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.

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

# 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 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"
		}
}

Error codes

A request may return an error code.

200 - OK

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