Localized content

The following REST API fields accept localized content:

Resource	Fields	Content format
Elements	title, content	Rich text HTML
Connections	label	Rich text HTML
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

Add the languages to the project before writing translations. In the editor, open Localization > Manage languages and add each 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

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}:

{
  "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".

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}:

{
  "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}:

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

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}:

{
  "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

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:

{
  "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.