Skip to main content
Atoti translates discoverable content, including captions, descriptions, level members, and formatted measure values, for the locale of the requesting user. Without an explicit configuration, no translation is applied.

​
Lexicons

A lexicon is a locale-scoped map of keys to translated values. A translation file is made up of several named lexicons, each covering a different category of content. _GENERAL_ is the fallback consulted whenever a type-specific lexicon does not contain a key.

​
Translation file format

Each locale requires one JSON file, named after its locale code (for example, i18n/fr-FR, i18n/zh-CN, i18n/ja-JP). The top-level keys are lexicon names; the nested objects hold the translation maps. A level-specific formatter can be created using a dedicated lexicon for the level, then referenced from the _FORMATTERS_ lexicon by the level’s MDX unique name.

​
How to target hierarchies and levels that share a name

By default, a key in _HIERARCHIES_ or _LEVELS_ is a plain name that applies to every element with that name across the cube. When two hierarchies or levels share the same name, a fully qualified key makes it possible to target one specific element. Two fully qualified forms are accepted and will resolve to the same element: The MDX form uses the same bracket syntax already used in the _FORMATTERS_ lexicon, so projects that write MDX unique names there can use the same style here. Escaping (@ form): if a name legitimately contains @, replace each @ with /@@ in the key. For example, a level named foo@bar is written as foo/@@bar. A literal / does not need to be escaped. Escaping (MDX form): if a name contains a literal ], double it to ]]. A literal [ does not need to be escaped. The following example shows two hierarchies inside an Organization dimension that both have levels named Level 1 and Level 2. The fully qualified keys rename only BookHierarchy’s levels, while LegalEntityHierarchy’s levels keep their original names. Both fully qualified forms appear together to show that they can coexist in the same file.

​
How to install a translation

​
Step 1: Place the translation file

Place the locale file in the i18n/ directory of the application’s classpath (for example, src/main/resources/i18n/fr-FR) or in the i18n/ directory of the Content Service. The file name is the locale code. At startup, Atoti registers one ICubeFormatterFactory per file it finds, keyed on the file name.

​
Step 2: Bind a role to a locale

Translation is opt-in. A role must explicitly select a locale via its MDX context. Configure this on the entitlements builder for the role:
The string passed to withCubeFormatter is the plugin key under which the factory was registered in step 1, that is, the locale code from the file name. Without this binding, the role’s queries return untranslated content.

​
Custom translation source

If translations come from a source other than the standard i18n/ directory (for example, a database, a remote service, or a different file format), implement ICubeFormatterFactory directly and register it with the Atoti Registry under a chosen plugin key. That key is then referenced from a role’s MDX context using withCubeFormatter(key), exactly as in step 2 above.