Suggest Edits

Authentication

 

Localize exposes much of its functionality the Localize API to make it is easier for you to automate your workflow and integrate Localize with your existing tools.

Localize API calls are REST compliant and make use of the most common HTTP methods such as GET, POST, PUT and DELETE.

Authentication

Localize only allows authenticated requests to the API over HTTPS.

HTTPS requests only

Calls made over plain HTTP will fail.

API requests without authentication will also fail. Authenticate your account when using the API by including your API key in the request. Your API keys carry many privileges, so be sure to keep them secret. Don’t share them with other users or store them in insecure places. Provide your API key as the basic auth username value.

To authenticate with the API, provide your Public Key as the bearer value in the authentication header. Please treat both your Public and Private keys as secrets. Do not share these keys, and do not store either key in insecure locations.

curl https://api.localizejs.com/v2.0/projects
-H 'Authorization: Bearer sdjfh4G58cJ89234Lfj123ndfbknG'
-H 'Content-Type: application/json'

Obtaining an API token

To get an API token, complete the following steps.

  1. Log into to your Localize account.
  2. Navigate to the developer API keys section of settings.
  3. Generate an API token
  4. Use the Public Key as the Bearer value.

API Public Key Warning

The Public Key should be treated as a secret and not shared publicly

Schema

All data is sent and received as JSON, and requests sent to the API as JSON must have the correct content type header: Content-Type: application/json.

Blank or empty fields are included as null instead of being omitted. All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Endpoint

The Localize API is a restful http service. All requests to Localize must be made using https against the following URL:

https://api.localizejs.com/v2.0/

Errors

Localize uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a translation failed, etc.), and codes in the 5xx range indicate an error with Localize's servers.

Example

"meta": {
  "status": 400,
  "success": false,
  "error": {
    "message": "[type] The type is required"
  }
}
 
Suggest Edits

Import content

 
posthttps://api.localizejs.com/v2.0/projects/projectKey/resources

Path Params

projectKey
string
required

Localize project key

Body Params

language
string
required

The target language of the resource

format
string
required

The format of the resource.
Valid Formats : YAML, CSV, YML, XLIFF, XML, PO, JSON, STRINGS, RESX

content
file
required

Local file

type
string

Can be phrase or glossary

 
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/resources' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-F 'language=fr' \
-F 'format=yaml' \
-F 'content=@/path/to/the/file/resource.yaml' \
-H 'Content-Type: multipart/form-data'
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 201,
  "success": true
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "[type] The type is required and must be static or website"
  }
}
 
Suggest Edits

Export content

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/resources

Path Params

projectKey
string
required

Query Params

language
string
required

The target language of the resource

format
string
required

The format of the resource.
Valid Formats : YAML, CSV, YML, XLIFF, XML, PO, JSON, STRINGS, RESX

filter
string

Optional filters for content. Possible values are 'needs-translations', 'machine-translations'

type
string

What type of content. Either 'phrase' or 'glossary'

context
string

Context for phrases

 
curl 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/resources' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-d '{"language":"fr", "format": "csv"}' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 200,
  "success": true
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "[format] The format is required"
  }
}
 
Suggest Edits

Get projects

Returns projects accessible by the api key

 
gethttps://api.localizejs.com/v2.0/projects
 
curl -XGET 'https://api.localizejs.com/v2.0/projects' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json' \
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 200,
  "success": true
},
"data": [{
    "name": "test",
    "description": null,
    "type": "website",
    "tone": null,
    "purpose" null,
    "url": null,
    "key": "lCVLPUdEr0bbv",
    "sourceLanguage": "fr",
    "created": 
    "widget": {
      "position": null
    },
    "created": "2016-01-01T12:22:53-0800"
 }]
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "Error message",
    "code" "validation_failure"
  }
}
 
Suggest Edits

Create project

Creates a new project in an organization

 
posthttps://api.localizejs.com/v2.0/projects

Body Params

name
string
required

The name of the project to create.

sourceLanguage
string
required

The source language for your project. Must be a valid language code.

description
string

An optional description for your project.

url
string

If your project is a website, the URL or domain where the Localize library will be installed.

type is deprecated

The "type" field is deprecated and has been removed from the Project schema in the database.

curl -XPOST 'https://api.localizejs.com/v2.0/projects' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-d '{"name":"test", "sourceLanguage": "fr"}' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 201,
  "success": true
},
"data": {
  "name": "test",
  "description": null,
	"tone": null,
	"purpose": null,
  "url": null,
  "key": "lCVLPUdEr0bbv",
  "sourceLanguage": "fr",
  "widget": {
    "position": null
  },
  "created": "2016-01-01T12:22:53-0800"
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "[sourceLanguage] The sourceLanguage is required and must be a valid language code"
  }
}
 
Suggest Edits

Get a project

Get a single project based on the project key or the Id

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/

Path Params

projectKey
string
required

Can be the project key or the id

 
curl -XGET 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json' \
A binary file was returned

You couldn't be authenticated

{
  "meta": {
    "status": 200,
    "success": true
  },
  "data": {
    "project": {
      "id": "5909fc404893eb8eeadc632b",
      "name": "My awesome project",
      "description": null,
      "url": null,
      "tone": "Informal",
      "purpose": "Mobile app",
      "key": "g4YKVVNVCO0XG",
      "sourceLanguage": "en",
      "languages": [
        "fr"
      ],
      "enabledLanguages": [
        "en",
        "fr"
      ],
      "created": "2017-05-03T15:50:24.470Z",
      "widget": {
        "theme": "dark",
        "position": "right",
        "header": "#1e6aa0",
        "border": "#000",
        "font": "#999",
        "css": null
      }
    }
  }
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "Error message",
    "code" "validation_failure"
  }
}
 
Suggest Edits

Get phrases

Get a collection of phrases

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/phrases

Path Params

projectKey
string
required

The project key

Query Params

limit
int32

The number of phrases to return. The max is 5000. Default is 1000.

skip
int32

Skip a certain number of phrases.

state
string

Optional filter for the phrase state. Possible values are "active", "pending", "inactive", and "blocked"

state
array of strings

Can be a an array of states to query, for example ['active', 'pending']

labels
array of strings

Optional filter for phrase labels

context
string

Optional filter for phrase context

 
curl 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/phrases' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "meta": {
    "status": 200,
    "success": true
  },
  "data": {
    "phrases": [
      {
        "id": "5761ce8416543f5a742b5458",
        "state": "active",
        "phrase": "Website Localization",
        "type": null,
        "phraseKey": null,
        "context": null,
        "translations": [
          {
            "id": "5762eb122cfa1cd430f4f4da",
            "state": "active",
            "phrase": "Website Localization",
            "value": "Localisation de sites Web",
            "language": "fr",
            "translator": "google",
            "phraseKey": null,
            "updatedAt": "2016-06-16T18:08:18.692Z"
          }
        ]
      }
    ]
  }
}
 
Suggest Edits

Get a phrase

Get a specific phrase

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/phrases/id

Path Params

id
string
required

The phrase ID. This can also be the hash of the phrase.

Query Params

projectKey
string

The project key

Calculating a Hash

You can retrieve a phrase either by the resource ID or by its checksum

Node

crypto.createHash('md5').update(phrase, 'utf8').digest('hex')

PHP

md5(utf8_encode($phrase));
curl 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/phrases/5761ce8416543f5a74265458' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "meta": {
    "status": 200,
    "success": true
  },
  "data": {
    "phrase": {
      "id": "5761ce8416543f5a742b5458",
      "state": "active",
      "phrase": "Website Localization",
      "type": "phrase",
      "phraseKey": null,
      "context": null,
      "translations": [
        {
          "id": "5762eb122cfa1cd430f4f4da",
          "state": "active",
          "phrase": "Website Localization",
          "value": "Localisation de sites Web",
          "language": "fr",
          "translator": "google",
          "phraseKey": null,
          "updatedAt": "2016-06-16T18:08:18.692Z"
        }
      ]
    }
  }
}
 
Suggest Edits

Create a phrase

Create phrases for a project

 
posthttps://api.localizejs.com/v2.0/projects/projectKey/phrases

Path Params

projectKey
string
required

The project key

Body Params

phrases
array of mixed types

An array of the phrase values. This can be an array of strings or an array of objects with additional data. See the example cURL requests above, they include example data bodies for both types.

 
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/phrases' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
--data '{"phrases":["my phrase to create"]}'
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/phrases' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
--data '{"phrases":[{ "phrase": "My new phrase", "context":"this phrase has context"}]}'
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 200,
  "success": true
}
 
Suggest Edits

Delete a phrase

Delete a phrase

 
deletehttps://api.localizejs.com/v2.0/projects/projectKey

Path Params

projectKey
string
required

The project key

Body Params

id
string

The phrase Id

 
curl -XDELETE 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/phrases/5761ce8416543f5a742b5458' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 200,
  "success": true
}
 
Suggest Edits

Get translations

Get a collection of translations

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/translations

Path Params

projectKey
string
required

The Localize project key

Query Params

language
string

The language code

 
curl 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/phrases/5761ce8416543f5a74265458' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

{
"meta": {
  "status": 200,
  "success": true
},
"data": {
  "translations": [
    {
      "id": "5762eb122cfa1cd430f4f4da",
      "state": "active",
      "phrase": "#Website Localization",
      "value": "Localisation de sites Web",
      "language": "fr",
      "translator": "google",
      "phraseKey": null,
      "updatedAt": "2016-06-16T18:08:18.692Z"
    },
    {
      "id": "5762e94f7b121b102eaff9fb",
      "state": "active",
      "phrase": "#tags",
      "value": "Mots cl\u00e9s",
      "language": "fr",
      "translator": "google",
      "phraseKey": null,
      "updatedAt": "2016-06-16T18:00:47.997Z"
    },
    {
      "id": "5761e11bfc75dd8e1135ea75",
      "state": "active",
      "phrase": "#\u2192Vintage t\u00f8j\u2190 Online webshop og butik - Vintage Divine",
      "value": "\u2192 TOJ Vintage \u2190 webshop en ligne og butik - Divine Vintage",
      "language": "fr",
      "translator": "google",
      "phraseKey": null,
      "updatedAt": "2016-06-15T23:13:31.024Z"
    }
  ]
}
 
Suggest Edits

Get a translation

Retrieve a translation for a phrase

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/translations/translationId?language=language

Path Params

projectKey
string
required

The project key

translationId
string
required

The translation id related to the project

Query Params

language
string

The language code

 
curl 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/translations/5761e11bfc75dd8e1135ea75?language=fr' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

{
"meta": {
  "status": 200,
  "success": true
},
"data": {
  "id": "5761e11bfc75dd8e1135ea75",
  "state": "active",
  "phrase": "#\u2192Vintage t\u00f8j\u2190 Online webshop og butik - Vintage Divine",
  "value": "\u2192 TOJ Vintage \u2190 webshop en ligne og butik - Divine Vintage",
  "language": "fr",
  "translator": "google",
  "phraseKey": null,
  "updatedAt": "2016-06-15T23:13:31.024Z"
}
 
Suggest Edits

Create a translation

Create a translation for a phrase

 
posthttps://api.localizejs.com/v2.0/projects/projectKey/translations

Path Params

projectKey
string
required

The project key

Body Params

phrase
string
required

The phrase ID to attach the translation to

value
string
required

The content of the translation

state
string
required

Valid options include: active, inactive, rejected, blocked

language
string
required

The translation language

comment
string

An optional description for your project.

 
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/translations' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-d '{"value":"phrase de test", "language": "fr", "state":"active", "phrase": "57c8c5515c8971a8426c9a04"}' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 201,
  "success": true
},
"data": { 
  id: '57c9e2ebd06239485ab69f95',
  state: 'pending',
  phrase: null,
  value: 'phrase de test',
  comment: 'new',
  language: 'fr',
  translator: 'api',
  phraseKey: '#test phrase',
  updatedAt: '2016-09-02T20:36:59.121Z' 
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "[type] The type is required and must be static or website"
  }
}
 
Suggest Edits

Update a translation

Update a translation

 
puthttps://api.localizejs.com/v2.0/projects/projectKey/translations/translationId

Path Params

translationId
string
required

The ID of the translation

projectKey
string
required

Localize project key or id

Body Params

value
string

The content of the translation

state
string

Valid options include: active, inactive, rejected, blocked

comment
string

An optional description for your translation

 
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/translations/57c9e2ebd06239485ab69f95' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-d '{"state":"active"}' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 200,
  "success": true
},
"data": { 
  id: '57c9e2ebd06239485ab69f95',
  state: 'active',
  phrase: null,
  value: 'The new value',
  comment: 'new',
  language: 'en',
  translator: 'web',
  phraseKey: null,
  updatedAt: '2016-09-02T20:36:59.121Z' 
}
"meta": {
  "status": 400,
  "success": false,
  "error": {
    "msg": "[translationId] is not valid"
  }
}
 
Suggest Edits

Delete a translation

Delete a translation from a phrase

 
deletehttps://api.localizejs.com/v2.0/projects/projectKey/translation/translationId

Path Params

projectKey
string
required

The project key

translationId
string
required

The translation ID

 
curl -XDELETE 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/translations/5761ce8416543f5a742b5458' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
A binary file was returned

You couldn't be authenticated

"meta": {
  "status": 200,
  "success": true
}
 
Suggest Edits

Get languages

Get a list of supported languages and locales

 
gethttps://api.localizejs.com/v2.0/languages

Query Params

code
string

Get a language information for a specific language code (e.g. "en"). Will return a status code of 400 for an invalid code. Load the list first to check what is available.

 
curl 'https://api.localizejs.com/v2.0/languages' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "meta": {
    "status": 200,
    "success": true
  },
  "data": {
    "locales": [
      {
        "code": "af",
        "name": "Afrikaans",
        "locales": []
      },
      {
        "code": "am",
        "name": "Amharic",
        "locales": []
      },
      {
        "code": "sq",
        "name": "Albanian",
        "locales": []
      },
      ...
    ]
  }
}
 
Suggest Edits

Get team members

Get a list of team members on your project

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/team-members

Path Params

projectKey
string
required

Get a list of team members in your project

 
curl 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/team-members' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

{  
   "meta":{  
      "status":200,
      "success":true
   },
   "data":{  
      "team":[  
         {  
            type:'owner',
            createProject:true,
            manageBilling:true,
            user:{  
               name:'Admin',
               email:'admin2@fake.com'
            },
            projectRoles:[],
            allProjectRoles:{  },
            invitePending:false
         },
         {  
            type:'member',
            createProject:true,
            manageBilling:true,
            user:{  
               name:'Admin',
               email:'member@fake.com'
            },
            projectRoles:[],
            allProjectRoles:{},
            invitePending:false
         },
         ...
      ]
   }
}
{ error: 'Invalid project key' }
 
Suggest Edits

Translate phrase

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/machine-translations/translate?phrase=phrase&target=targetLanguage&source=sourceLanguage

Path Params

projectKey
string
required

The Project Key

Query Params

phrase
string
required
targetLanguage
string
required

A target language to translate a phrase

sourceLanguage
string

A source language to translate a phrase from, the server will detect if not provided

 
curl 'https://api.localizejs.com/v2.0/projects/aCbLPaaee0bbv/machine-translations/translate?phrase=test&target=ru&source=en' \
-H 'Authorization: Bearer EzEXaGeP4eeuITeaaaS33vgVTsJymlaS'
A binary file was returned

You couldn't be authenticated

{
  phrase: 'phrase',
  source: 'en',
  target: 'ru',
  translation: 'фраза'
}
 
Suggest Edits

Detect language

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/machine-translations/detect?phrase=phrase

Path Params

projectKey
string
required

The project key

Query Params

phrase
string
required
 
curl 'https://api.localizejs.com/v2.0/projects/lCVwPaaar0bbv/machine-translations/detect?phrase=test%phrase' \
-H 'Authorization: Bearer EzEXaaeaP4mJuITevOxS33vgVTsJymlaS'
A binary file was returned

You couldn't be authenticated

{
  phrase: 'test phrase',
  language: 'en'
}
 
Suggest Edits

Supported languages list

Returns a list of languages into which the source language can be translated.

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/machine-translations/languages&target=target

Path Params

projectKey
string
required

The Project Key

Query Params

target
string

If specified, response will include the human readable name(s) of the supported language(s), localized to the given target language

 
curl 'https://api.localizejs.com/v2.0/projects/sf56gEGg6ev/machine-translations/languages?target=ru' \
-H 'Authorization: Bearer eAEXaGeP4mJuIdddOxS33vgVTsJymlaS'
curl 'https://api.localizejs.com/v2.0/projects/sf56gEGg6ev/machine-translations/languages' \
-H 'Authorization: Bearer eAEXaGeP4mJuIdddOxS33vgVTsJymlaS'
A binary file was returned

You couldn't be authenticated

{
  target: 'ru',
  languages:[
    {
    "language": "az",
    "name": "азербайджанский"
    },
    {
    "language": "sq",
    "name": "албанский"
    },
    {
    "language": "am",
    "name": "амхарский"
    },
    ....
  ]
}
error":{
"message": "Resource not found"
}
{
  "languages":
  	["af", "am", "ar", ...]
}