--- title: "UI Localization" slug: "ui-localization" updated: 2026-03-30T16:23:21Z published: 2026-03-30T16:23:21Z --- > ## Documentation Index > Fetch the complete documentation index at: https://documentation.deltatre.com/llms.txt > Use this file to discover all available pages before exploring further. # UI Localization ## Introduction The Content Manager supports label localization in any Latin-based language. > [!NOTE] > What’s a label? > > Labels are the microcopy pieces of the UI that are localized. You configure the available UI languages through environment variables and by connecting the Content Manager to a localization provider that supplies localized labels. The English localization is included out of the box and requires no configuration. This guide walks you through the full process of adding a new localization. > [!NOTE] > Important > > - Right-to-left (RTL) languages are not supported > - All localization keys must be lowercase > - Localization labels are cached at application startup > - The localization can apply to a subset of labels. For not-localized labels, the default (English) applies. ## How to add a new localization ### Prerequisites Before you begin, ensure that: - You have access to the FORGE Back Office UI configuration - You can define environment variables - You have access to a localization provider (Vocabulary Tool or API) ### 1. Define the localization to add Choose the localization you want to add. Prepare the following: - Language-region code (for example: `it-it`). - Label displayed in the *User profile* page (for example: `Italiano`). - Whether it is the default localization. If no default language is configured, the UI falls back to English. ### 2. Configure the new localization in the environment variables In the FORGE Back Office UI configuration, add the localization to the *FORGE__UiTranslation__AvailableLanguages* variables . A triple of variables defines the new localization: - **Code** (required): Unique localization identifier. - **Label** (optional): Display name in UI. - **Default** (optional): Set to true to make it the default language. Example: ```bash FORGE__UiTranslation__AvailableLanguages__0__Code=it-it FORGE__UiTranslation__AvailableLanguages__0__Label=Italiano FORGE__UiTranslation__AvailableLanguages__0__Default=true ``` Each variable embeds a number within the name. E.g, Number `0` in `FORGE__UiTranslation__AvailableLanguages__0__Code`. This number groups together the triple of variables per language. In the example above, the number `0` groups together the three variables that define the Italian localization. ### 3. Choose a localization provider The localization provider supplies translated labels for a localization. There are two possible localization providers: - [**Vocabulary Tool**](/v1/docs/ui-localization#31-how-to-connect-to-the-vocabulary-tool-as-localization-provider): It’s the source that the FORGE ecosystem includes natively. It deals with creating a vocabulary with the translated labels. - [**Built-in**](/v1/docs/ui-localization#32-how-to-connect-to-a-builtin-provider): It’s an external API endpoint that returns a JSON payload with the translated labels. #### 3.1 Vocabulary Tool In the FORGE Back Office UI configuration, add the following environment variables: - **BaseUrl**: Base URL of the Vocabulary Tool instance. - **VocabularyCode:** Code of the [vocabulary](/v1/docs/manage-and-edit-terms) containing the labels’ translation. Example: ```bash FORGE__UiTranslation__VocabularyToolProviderOptions__BaseUrl=https://your-voc-url FORGE__UiTranslation__VocabularyToolProviderOptions__VocabularyCode=your-vocabulary-code ``` #### 3.2 Built-in provider In the FORGE Back Office UI configuration, add the following environment variables: - **BaseUrl**: Absolute URI of the endpoint returning the JSON with translated labels. - **VocabularyPath:** Relative path of the endpoint containing the language placeholder {lng}. Example: ```bash FORGE__UiTranslation__BuiltInProviderOptions__BaseUrl=https://www.my-provider.com/ FORGE__UiTranslation__BuiltInProviderOptions__VocabularyPath=my/path/{lng}/labels.json ``` ### 4. Label translation After configuring the provider, you must define label translations. Labels can be: - **Static**: They are labels around system features (e.g., the [administration panel](/v1/docs/administration-panel), [dashboards](/v1/docs/dashboards), and error messages), and the built-in entities (e.g., the story, album, and editorial list). - **Dynamic**: They are labels around [custom entities](/v1/docs/custom-entities), [extended fields](/v1/docs/entity-customization#extended-fields), and [reference fields](/v1/docs/administration-panel#reference-fields). The Vocabulary Tool and Built-in providers must return the translation for both kinds of labels. Example: **Static label example** ```json "dynamic.extended_fields.ef_story_creation_title": "Titolo" ``` **Dynamic label example** ```json "dynamic.system_language.en-us": "Inglese (Stati Uniti)" ``` #### Static labels Download the list of all the static labels from *Administration→Utilities→Download JSON*: ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/image(343).png) You’ll get a JSON file like in the example below: ```json {  "add": "Add",  "all_tags": "All Tags",  "all": "All",  "and": "And",  "and_description": "This option matches items having all the tags added below",  "any_tags": "Any tag",  ... } ``` If the Vocabulary Tool is the localization provider, there must be a [term](/v1/docs/create-vocabulary-terms) for each key in the JSON file. E.g., `and_description`. Then, for each term the translation for the new language must be set. If the Built-in is the localization provider, the API endpoint configured in [step 3.2](/v1/docs/ui-localization#32-how-to-connect-to-a-builtin-provider) must return a JSON payload with labels (keys) and their translation (value). #### Dynamic labels Download the list of all the dynamic labels from *Administration→Utilities→Download JSON for dynamic keys*: ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/image(344).png) You’ll get a JSON file like in the example below: ```json {  "dynamic.system_language.en-us": "English (United States)",  "dynamic.system_language.en-gb": "English (United Kingdom)",  "dynamic.system_language.fr-fr": "French (France)",  "dynamic.system_language.es-es": "Spanish (Spain)",  "dynamic.system_language.jgo-cm": "Ngomba (Cameroon)",  "dynamic.system_language.es-ea": "espanol (Ceuta & Melilla)",  "dynamic.system_language.en-pw": "posso cambiare questo",  "dynamic.system_language.ar-jo": "Arabic (Jordan)",  "dynamic.system_language.ko-kr": "Korean (South Korea)",  "dynamic.system_language.ar-001": "Arabic (world)",  "dynamic.extended_fields.ef_story_creation_title": "",  "dynamic.extended_fields.ef_story_contentdate_title": "",  "dynamic.extended_fields.ef_story_culture_title": "",  "dynamic.extended_fields.ef_story_featured_title": "",  ... } ``` Follow the naming convention below (replace the `<...>` parts in each key with the actual value) to add dynamic label translations either in a vocabulary — when connected to the Vocabulary Tool — or to the Built-in API endpoint JSON result: - System languages name - `dynamic.system_language.<language-code>` - System entity - Name: - Built-in entity: `dynamic.system_entity.<built-in-entity-code>_name` - Custom entity: `dynamic.system_entity.<custom-entity-code>_name` - Plural name: - Built-in entity: `dynamic.system_entity.<built-in-entity-code>_plural_name` - Custom entity: `dynamic.system_entity.<custom-entity-code>_plural_name` - Extended fields, contextual-fields (available for album items, selection items) - Title property (being `<field_id>` the identifier of the field): - Built-in entity: `.dynamic.extended_fields.ef_<built-in-entity-code>_<field_id>_title` - Custom entity: `.dynamic.extended_fields.ef_ce_<custom-entity-code>_<field_id>_title` - Description property (being `<field_id>` the identifier of the field): - Built-in entity: `dynamic.extended_fields.ef_<built-in-entity-code>_<field_id>_desc` - Custom entity: `dynamic.extended_fields.ef_ce_<custom-entity-code>_<field_id>_desc` - Story-part-properties (available only on stories) - title property (being `<field_id>` the identifier of the field): - Built-in entity: `dynamic.extended_fields.sp_<built-in-entity-code>_<field_id>_title` - Custom entity: `dynamic.extended_fields.sp_ce_<custom-entity-code>_<field_id>_title` - Description property (being `<field_id>` the identifier of the field): - Built-in entity: `dynamic.extended_fields.sp_<built-in-entity-code>_<field_id>_desc` - Custom entity: `dynamic.extended_fields.sp_ce_<custom-entity-code>_<field_id>_desc` - Reference fields label (being `<field_id>` the identifier of the field): - Built-in entity: `dynamic.reference_fields.<built-in-entity-code>_<field_id>_title` - Custom entity: `dynamic.reference_fields.ce_<custom-entity-code>_<field_id>_title` ### 5. Restart FORGE Ask DevOps to restart the Back office UI pods.