# Localized content

> For the complete documentation index, see [llms.txt](https://docs.arcweave.com/llms.txt). All pages are also available in one file, [llms-full.txt](https://docs.arcweave.com/llms-full.txt).

Source: https://docs.arcweave.com/rest-api/localization
Section: REST API
Description: Locale setup, request formats, and merge behavior for localized REST API writes

The following REST API fields accept localized content:

| Resource                             | Fields             | Content format                                                   |
| ------------------------------------ | ------------------ | ---------------------------------------------------------------- |
| [Elements](https://docs.arcweave.com/rest-api/elements)       | `title`, `content` | [Rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html) |
| [Connections](https://docs.arcweave.com/rest-api/connections) | `label`            | [Rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html) |
| [Components](https://docs.arcweave.com/rest-api/components)   | `name`             | Text                                                             |

Create endpoints accept strings, `null`, and locale maps. Update endpoints also accept path-style fields. The examples below assume the project has `en` as its main language and already includes `fr` and `de`.

## Set up project languages

Context: Arcweave docs > REST API > Localized content > Set up project languages

Add the languages to the project before writing translations. In the editor, open **Localization > Manage languages** and [add each language](https://docs.arcweave.com/project-tools/localization#add-language). Use the exact ISO codes configured there, including their letter case: `en` and `EN` are different codes.

The REST API has no endpoint for adding, renaming, or removing project locales. Sending a locale key in a content request does not create that locale.

The project's **default locale** is its **Main** language. Passing a field as a string or `null` writes to that language, regardless of which language someone currently has selected in the editor.

## Write the main language

Context: Arcweave docs > REST API > Localized content > Write the main language

A string value updates only the main language. A `null` value clears only that field's main-language text. Other translations remain unchanged.

For example, send this body to `PATCH /api/v1/{hash}/element/{elementID}`:

```json
{
  "title": null,
  "content": "<p>You enter the room.</p>"
}
```

With `en` as the main language, this clears the English title and replaces the English content. It leaves the French and German title and content unchanged. On update, omitting a field leaves all of that field's translations unchanged.

The same rule applies when you pass a connection `label` or component `name` as a string or `null`. To clear text, send JSON `null`; do not use the string `"null"`. For element titles and content and connection labels, an empty string `""` is treated the same as `null`, including in locale maps and path-style fields. Blank component names follow the [component naming rules](https://docs.arcweave.com/rest-api/components#create-component-or-folder).

## Write specific languages

Context: Arcweave docs > REST API > Localized content > Write specific languages

A locale map updates only its supplied languages. It does not replace the whole translation map or remove languages that are omitted.

For example, send this body to `PATCH /api/v1/{hash}/element/{elementID}`:

```json
{
  "content": {
    "fr": {
      "text": "<p>Vous entrez dans la pièce.</p>"
    },
    "de": {
      "text": null
    }
  }
}
```

This replaces the French content, clears the German content, and keeps the English content and all titles unchanged. Clearing text does not remove the language from the project. Play Mode may display fallback content when a translation is empty.

Each map value may be a string, `null`, or an object containing only `text` with a string or `null` value. For example, `"fr": "<p>Bonjour.</p>"` is shorthand for `"fr": { "text": "<p>Bonjour.</p>" }`.

Use the same map structure for labels and component names. For example, this body updates only the French name through `PATCH /api/v1/{hash}/component/{componentID}`:

```json
{
  "name": {
    "fr": {
      "text": "Garde"
    }
  }
}
```

## Update one translated field

Context: Arcweave docs > REST API > Localized content > Update one translated field

Update endpoints also accept a flat JSON key naming the field and locale, separated by `/` or `.`. An optional final `text` segment is supported. The value must be a string or `null`.

For example, send this body to `PATCH /api/v1/{hash}/element/{elementID}`:

```json
{
  "content/fr/text": "<p>Vous entrez dans la pièce.</p>",
  "title.de": null
}
```

This changes only the French content and German title. `content/fr`, `content.fr`, and `content.fr.text` also address the French content. For connections, use keys such as `label/fr/text`; for component names, use `name/fr/text`.

## Unknown locale errors

Context: Arcweave docs > REST API > Localized content > Unknown locale errors

Writing a locale that is not defined in the project returns `409 Conflict` with `type: "integrity_conflict"` and `conflictType: "unknown_locale"`. The request is rejected without applying its content changes.

For example, if `it` has not been added, a request containing `"title": { "it": "<p>Ingresso</p>" }` returns:

```json
{
  "title": "Integrity error: Unknown locale in API payload",
  "status": 409,
  "detail": "The payload contains localized content for a locale that is not defined in this project.",
  "errors": {
    "title.it": "Locale it is not defined in this project."
  },
  "errorCode": 0,
  "type": "integrity_conflict",
  "conflictType": "unknown_locale"
}
```

Check the code against the project's configured languages. Correct the request or add the language in the editor before retrying. Malformed locale maps or unsupported rich-text markup instead return `400 Bad Request`.