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.

API version: 1.0.9.2
Status: active

Authentication

All requests to the API must contain the parameter api_token. You can get this key from your Lokalise account. You'll find it in Account tab.

Please take care of your token.

If you think the key has been compromised, you can reset it from Account by clicking the Generate button.

List projects

ACTION:
- returns the list of projects owned by user

METHOD:
GET

URL:
- https://lokalise.co/api/project/list

ARGUMENTS:
- api_token (required)

The Project Object

id:
string Unique project ID
name:
string Project name
desc:
string Project description
created:
string Project creation date and time
owner:
string 1 if user is project owner, otherwise 0
# Request example
curl -X GET https://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

ACTION:
- adds a new project
- returns the id of the project (if successful)

METHOD:
POST

URL:
- https://lokalise.co/api/project/add

ARGUMENTS:
- api_token (required)
- name - the name of the project (required)
- description - the description of the project
- base_lang - set base language of the project (ISO code)

# Request example
curl -X POST https://lokalise.co/api/project/add \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "name=Wonderful"
     -d "description=Wonderful%20project"
     -d "base_lang=en_US"

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

Remove project

ACTION:
- removes a project

METHOD:
POST

URL:
- https://lokalise.co/api/project/remove

ARGUMENTS:
- api_token (required)
- id - project id (required)

# Request example
curl -X POST https://lokalise.co/api/project/remove \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"

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

Export project data

ACTION:
- generates bundle file and executes web hooks returning relative file location.
- returns filename, add https://s3-eu-west-1.amazonaws.com/lokalise-assets/ in front and download the zip directly.

METHOD:
POST

URL:
- https://lokalise.co/api/project/export

ARGUMENTS:
- api_token (required)
- id - project id (required)
- type - file format (po, xls, strings, xliff, xml, json, php, yml, properties, ini) (required)
- langs - list of languages to be exported. If omitted, all languages are exported
- use_original - use original filenames/formats (bundle_structure parameter is ignored then)
- filter - filter results by 'translated', 'nonfuzzy', 'nonhidden' fields
- bundle_structure - zip bundle structure (you can use %LANG_ISO%, %LANG_NAME%, %FORMAT%, %PROJECT_NAME% placeholders)
- webhook_url - sends POST['file'] to this URL if specified
- export_all - include all platform keys
- ota_plugin_bundle - generate plugin for OTA iOS plugin
- export_empty - how to export empty strings (empty, base, skip)
- include_comments - include comments in exported file
- include_pids - other projects id's, which keys to include in this export
- tags - filter keys by tags (json)
- yaml_include_root - include language ISO code as root key in YAML export
- export_sort - one of first_added, last_added, last_updated, a_z, z_a

Example setting of filters and langs

filter=translated
filter=["translated"]
filter=["translated", "nonfuzzy"]
langs=["en_US", "ru_RU", "he", "fr_FR"]
tags=["supertag"]
include_pids=["5234678454e5eedbef6c68.1922d217", "8b23d12454e5eecbe36c68.127135231"]
# Request example
curl -X POST https://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

ACTION:
- creates project snapshot, that can be restored in project settings

METHOD:
POST

URL:
- https://lokalise.co/api/project/snapshot

ARGUMENTS:
- api_token (required)
- id - project id (required)

# Request example
curl -X POST https://lokalise.co/api/project/snapshot \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"

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

Empty project

ACTION:
- deletes all keys and translations from the project

METHOD:
POST

URL:
- https://lokalise.co/api/project/empty

ARGUMENTS:
- api_token (required)
- id - project id (required)

# Request example
curl -X POST https://lokalise.co/api/project/empty \
     -d "api_token=f4d3f29bf893dc3583e9970735e08de094e82b0" \
     -d "id=2178052454e5eecbe36c68.09719217"

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

List project languages

ACTION:
- lists project languages

METHOD:
GET

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

ARGUMENTS:
- api_token (required)
- id - project id (required)

The Language Object

iso:
string Language ISO code
name:
string Language name
words:
string Word count
rtl:
string Right-to-left
is_default:
string Base language of the project
# Request example
curl -X GET https://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"
		}
}

# Request example
curl -X POST https://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 from project

ACTION:
- removes language to a project

METHOD:
POST

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

ARGUMENTS:
- api_token (required)
- id - project id (required)
- iso - language ISO codes (required)

# Request example
curl -X POST https://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 system languages

ACTION:
- lists languages supported by Lokalise

METHOD:
GET

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

ARGUMENTS:
- api_token (required)

# Request example
curl -X GET https://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 pairs by language

limited to one request per 5 seconds

ACTION:
- returns project's keys and translations by language.
- if langs is not set, returns all language strings.

METHOD:
POST

URL:
- https://lokalise.co/api/string/list

ARGUMENTS:
- api_token (required)
- id - project id (required)
- langs - language iso codes (empty for all)
- platform_mask - platform bitmask
- keys - list of keys to include

Platform bitmask values are:
- iOS = 1
- Android = 2
- Web = 4
- Other = 16

# Request example
curl -X POST https://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",
        "modified_at": "2015-02-05 23:21:20",
        "fuzzy": "0",
        "references": null,
        "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",
        "modified_at": "2015-02-05 23:17:27",
        "fuzzy": "0",
        "references": null,
        "context": null,
        "is_archived": "0"
      },
    ]
  },
  "response": {
    "status": "success",
    "code": "200",
    "message": "OK"
  }
}

Add or update keys and translations

limited to one request per 30 seconds

ACTION:
- adds or updates keys/translations in project

METHOD:
POST

URL:
- https://lokalise.co/api/string/set

ARGUMENTS:
- api_token (required)
- id - project id (required)
- data - JSON (required)

[
   {
      "key": "app.slogan",
      "platform_mask": 1,
      "context": "",
      "filename": "en.po",
      "hidden": 1,
      "references": ["/main", "/project"],
      "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 bitmask values are:
- iOS = 1
- Android = 2
- Web = 4
- Other = 16

# Request example
curl -X POST https://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

ACTION:
- removes keys with translations from project

METHOD:
POST

URL:
- https://lokalise.co/api/string/remove

ARGUMENTS:
- api_token (required)
- id - project id (required)
- keys - list of keys to remove (required)

# Request example
curl -X POST https://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.

Attributes

code:
string Code of the error
message:
string A complete message with details about the error to show users.
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