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

For an added layer of security, you may use your Private Key to generate a signature which can be attached to any request. Please contact support for instructions.

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 section of settings.
  3. Generate an API token
  4. Use the Public Key as the Bearer value. (NOTE: 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
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"
  }
}

Body Params

language
string
required

The target language of the resource

format
string
required

The format of the resource

content
file
required

Local file

 
Suggest Edits

Export content

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/resources
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"
  }
}

Path Params

projectKey
string
required

Query Params

language
string
required

The target language of the resource

format
string
required

The format of the resource

filter
string

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

 
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 project in an organization

 
posthttps://api.localizejs.com/v2.0/projects
curl -XPOST 'https://api.localizejs.com/v2.0/projects' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-d '{"name":"test", "sourceLanguage": "fr", "type":"website"}' \
-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,
  "type": "website",
	"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": "[type] The type is required and must be static or website"
  }
}

Body Params

name
string
required

The name of project to create.

type
string
required

What type of project. Either 'static' or 'website'.

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.

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

Path Params

key
string
required

Can be the project key or the id

 
Suggest Edits

Get phrases

Get a collection of phrases

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/phrases
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"
          }
        ]
      }
    ]
  }
}

Path Params

projectKey
string
required

The project key

Query Params

limit
int32
required

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

skip
int32
required

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

 
Suggest Edits

Get a phrase

Get a specific phrase

 
gethttps://api.localizejs.com/v2.0/projects/:projectKey/phrases/id
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"
        }
      ]
    }
  }
}

Path Params

id
string
required

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

Query Params

projectId
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));
Suggest Edits

Create a phrase

Create phrases for a project

 
posthttps://api.localizejs.com/v2.0/projects/projectKey/phrases
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
}

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.

 
Suggest Edits

Delete a phrase

Delete a phrase

 
deletehttps://api.localizejs.com/v2.0/projects/projectKey
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
}

Path Params

projectKey
string
required

The project key

Body Params

id
string

The phrase Id

 
Suggest Edits

Get translations

Get a collection of translations

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/translations
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"
    }
  ]
}

Path Params

projectKey
string
required

The Localize project key

Query Params

language
string

The language code

 
Suggest Edits

Get a translation

Retrieve a translation for a phrase

 
gethttps://api.localizejs.com/v2.0/projects/projectKey/translations/:id
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"
    }
  ]
}

Path Params

projectKey
string
required

The project key

Query Params

language
string

The language code

 
Suggest Edits

Create a translation

Create a translation for a phrase

 
posthttps://api.localizejs.com/v2.0/projects/projectKey/translations
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/translations' \
-H 'Authorization: Bearer EzEXaGeP4mJuITevOxS33vgVTsJymlaS' \
-d '{"value":"test", "anguage": "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: 'inactive',
  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": "[type] The type is required and must be static or website"
  }
}

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

Can be active, inactive, rejected, blocked.

language
string
required

The translation language

comment
string

An optional description for your project.

 
Suggest Edits

Update a translation

Update a translation

 
puthttps://api.localizejs.com/v2.0/projects/:projectKey/translations/id
curl -XPOST 'https://api.localizejs.com/v2.0/projects/lCVLPUdEr0bbv/translations' \
-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": "[type] The type is required and must be static or website"
  }
}

Path Params

id
string
required

The ID of the translation

Body Params

value
string

The content of the translation

state
string

Can be active, inactive, rejected, blocked.

comment
string

An optional description for your project.

 
Suggest Edits

Delete a translation

Delete a translation from a phrase

 
deletehttps://api.localizejs.com/v2.0/projects/projectKey/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
}

Path Params

projectKey
string
required

The project key

id
string
required

The translation ID

 
Suggest Edits

Get languages

Get a list of supported languages and locales

 
gethttps://api.localizejs.com/v2.0/languages
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": []
      },
      ...
    ]
  }
}

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.

 
Suggest Edits

Get stats

Get pageview and translation statistics for project

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

Path Params

projectKey
string
required

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.

 
Suggest Edits

Translate phrase

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

You couldn't be authenticated

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

Path Params

projectKey
string
required

The Project Key

Query Params

phrase
string
required
target
string
required

A target language to translate a phrase

source
string

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

 
Suggest Edits

Detect language

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

You couldn't be authenticated

{
  phrase: 'phrase',
  language: 'en'
}

Path Params

projectKey
string
required

The project key

Query Params

phrase
string
required
 
Suggest Edits

Supported languages list

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

You couldn't be authenticated

{
  target: 'ru',
  languages: ['af', 'am', 'ar', 'az', 'be', 'bg', 'bn', 'bs', 'ca', 'ceb', 'co', 'cs', 'cy', 'da', 'de', 'el', 'en', ....]
}

Path Params

projectKey
string
required

The Project Key

Query Params

target
string

If provided the server will return supported languages list related to it