Add a language to a project - Phrase Developer Hub

Add a supported target language to an existing project as a configuration change. One API call, no code change, no redeploy. Trying to add a language Phrase does not support yet? That is a platform-level change handled separately. Contact Phrase support instead.

Quickstart

curl --request GET \
  --url https://api.phrase.com/v2/projects \
  --header 'Authorization: Bearer <JWT_TOKEN>'

Prerequisites

Authentication set up. See the Authentication guide.
A token with the write scope.
A project ID: the project’s public code, from the Quickstart call above.
A supported locale code for the language you are adding, for example de-AT.

Add to a project, not to the platform

This guide adds a language from the set Phrase already supports. If a code is rejected when you create the locale, that code is not in the supported set yet. Requesting support for a new code is a separate request to Phrase.

Create the language

Add the new language to the project. name and code are the only required fields. The optional source language sets what translators translate from.

Get the ID of the language you will translate from. Copy the id of your source language from the response.

curl --request GET \
  --url https://api.phrase.com/v2/projects/<PROJECT_ID>/locales \
  --header 'Authorization: Bearer <JWT_TOKEN>'

Create the language. Send name and code, plus source_locale_id from step 1. A 201 returns the new locale with its id. It is live on the project immediately, no redeploy.

curl --request POST \
  --url https://api.phrase.com/v2/projects/<PROJECT_ID>/locales \
  --header 'Authorization: Bearer <JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "de-AT",
    "code": "de-AT",
    "source_locale_id": "<SOURCE_LOCALE_ID>"
  }'

Optional: add autotranslate true to machine-translate the new language on creation. This runs only if the account includes the Autopilot feature. Without it the field is ignored and the language is created empty.

curl --request POST \
  --url https://api.phrase.com/v2/projects/<PROJECT_ID>/locales \
  --header 'Authorization: Bearer <JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "de-AT",
    "code": "de-AT",
    "source_locale_id": "<SOURCE_LOCALE_ID>",
    "autotranslate": true
  }'

When it breaks: common errors

The 422 response names the exact field in its errors array. Read that first.

422: name format

The name is a short handle, not a display label. Use only letters, numbers, hyphens, and underscores, so de-AT works but German (Austria) does not.

422: code not recognized

The code must be a language Phrase already supports. Use a standard code such as de-AT.

404: source or fallback not found

source_locale_id and fallback_locale_id must already exist in this project. Copy a real id from step 1, or add that language first.

403: forbidden

Either the token is missing the write scope, or a field needs a plan feature. main true needs Verification System; the unverify options need Advanced Workflows. Use a write-scoped token, or drop the field.

429: rate limited

A 429 means too many requests in a short time: wait for the window to reset, then retry.

Troubleshooting

Status

Check the Phrase status page before assuming your own request is wrong.

Where to get help

If Phrase is healthy and the errors array does not explain the failure, contact support.

Help center

Support articles and answers to common Phrase questions.

Next steps

List locales to confirm the new language is on the project.
Create a locale reference to see every optional field.

Last updated: September 18, 2026. Track documentation changes in the changelog.

​Quickstart

​Prerequisites

​Add to a project, not to the platform

​Create the language

​When it breaks: common errors