> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a language to a project

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

```bash theme={null}
curl --request GET \
  --url https://api.phrase.com/v2/projects \
  --header 'Authorization: Bearer <JWT_TOKEN>'
```

## Prerequisites

1. Authentication set up. See the [Authentication guide](/en/api/platform/authentication).
2. A token with the write scope.
3. A project ID: the project's public code, from the Quickstart call above.
4. 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.

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

   ```bash theme={null}
   curl --request GET \
     --url https://api.phrase.com/v2/projects/<PROJECT_ID>/locales \
     --header 'Authorization: Bearer <JWT_TOKEN>'
   ```

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

   ```bash theme={null}
   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>"
     }'
   ```

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

   ```bash theme={null}
   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.

<Card title="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.
</Card>

<Card title="422: code not recognized">
  The code must be a language Phrase already supports. Use a standard code such as `de-AT`.
</Card>

<Card title="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.
</Card>

<Card title="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.
</Card>

<Card title="429: rate limited">
  A `429` means too many requests in a short time: wait for the window to reset, then retry.
</Card>

## Troubleshooting

<Card title="Status">
  Check the [Phrase status page](https://status.phrase.com) before assuming your own request is wrong.
</Card>

<Card title="Where to get help">
  If Phrase is healthy and the `errors` array does not explain the failure, [contact support](https://support.phrase.com/hc/requests/new).
</Card>

<Card title="Help center">
  [Support articles and answers](https://support.phrase.com) to common Phrase questions.
</Card>

## Next steps

1. [List locales](/en/api/strings/locales/list-locales) to confirm the new language is on the project.
2. [Create a locale reference](/en/api/strings/locales/create-a-locale) to see every optional field.

*Last updated: September 18, 2026. Track documentation changes in the [changelog](/en/changelog).*