UI Localization

Introduction

The Content Manager supports label localization in any Latin-based language.

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.

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:

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: It’s the source that the FORGE ecosystem includes natively. It deals with creating a vocabulary with the translated labels.
Built-in: 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 containing the labels’ translation.

Example:

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:

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, dashboards, and error messages), and the built-in entities (e.g., the story, album, and editorial list).
Dynamic: They are labels around custom entities, extended fields, and reference fields.

The Vocabulary Tool and Built-in providers must return the translation for both kinds of labels.

Example:

Static label example

Dynamic label example

"dynamic.extended_fields.ef_story_creation_title": "Titolo"

"dynamic.system_language.en-us": "Inglese (Stati Uniti)"

Static labels

Download the list of all the static labels from Administration→Utilities→Download JSON:

You’ll get a JSON file like in the example below:

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

You’ll get a JSON file like in the example below:

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