Languages & translations (i18n)

The Ilum UI ships in English, Persian (فارسی), Arabic (العربية), Portuguese (Português), Spanish (Español), Chinese (中文), and Hindi (हिन्दी), and you can fix any wording or add an entirely new language without rebuilding the UI or touching source code. Everything a translator needs is a set of plain JSON files served by the running application, and everything an operator needs is one Kubernetes ConfigMap plus one Helm value.

Ilum Enterprise

Ilum Enterprise ships with professionally maintained translations for all supported languages, so the manual steps on this page are not required on Enterprise deployments. To request an additional language or a fully localized Enterprise build, contact the Ilum team at [email protected].

This page is written for two audiences:

End users who just want to switch the interface language.
Operators / translators who want to correct existing translations or add a new language on a deployed instance.

For end users: switching language

Open Settings → Language and pick a language from the dropdown. The choice is saved in your browser (local storage) and applied immediately. Right-to-left languages (such as Persian and Arabic) automatically flip the whole interface to RTL. Text direction always follows the selected language.

How translations are stored

All user-facing text lives in JSON translation catalogs, one file per feature area ("namespace"), served by the UI at:

/locales/<language-code>/<namespace>.json

For example, on a running instance the English catalog for the shared chrome is at https://<your-ilum-host>/locales/en/common.json.

English (en) is the source of truth. Other languages mirror the same keys.

A catalog is nested JSON of key: "text" pairs, for example in common.json:

{
  "settings": {
    "title": "Settings",
    "language": { "label": "Interface Language" }
  }
}

Any key a language does not define automatically falls back to English. This means a partial translation is perfectly fine: you can translate just the strings you care about and the rest stay in English.

Two things you must preserve when editing a value

Placeholders like {{name}}, {{count}}, {{role}} are filled in at runtime. Keep them exactly (you may move them within the sentence).
Tags like <b>...</b>, <strong>...</strong>, <0>...</0> mark embedded formatting or links. Keep the tags and their order; translate only the text between them.

The namespaces

Each language directory contains the same set of files. The current namespaces are:

common          analytics       dataCatalogs    documentation   fileExplorer
history         home            k8sPods         lineage         login
modules         notifications   resources       security        sql
tableExplorer   workloads

common holds the shared chrome (navigation, buttons, dialogs, ownership, etc.); the rest map to feature views. You only need to provide the files (and keys) you want to translate.

Get the current English files to use as a template

You do not need the source code. Download the live catalogs straight from your running UI and use them as the starting point for a translation:

HOST="https://your-ilum-host"      # your Ilum UI URL
mkdir -p de                         # target language folder (German example)
for ns in common analytics dataCatalogs documentation fileExplorer history home \
          k8sPods lineage login modules notifications resources security sql \
          tableExplorer workloads; do
  curl -fsS "$HOST/locales/en/$ns.json" -o "de/$ns.json"
done

Now edit the values in de/*.json (leave the keys, placeholders, and tags intact).

Plurals

Some keys have plural variants, distinguished by a suffix: key_one, key_other. Arabic uses the full CLDR set: key_zero, key_one, key_two, key_few, key_many, key_other. When you translate a pluralized key, provide the forms your language needs.

Testing translations locally with the container

A translator can correct and preview translations using only the Ilum UI container image and Docker, without Helm, Kubernetes, or a running backend. This is intended for verifying that an edited catalog renders correctly before the change is handed over for deployment. Substitute the image tag provided to you (for example ilum/ui:i18n-V2) in the commands below.

Run the UI container on its own

Start the container with NODE_ENV=development. This makes the startup step use the configuration defaults baked into the image, so none of the usual ILUM_* settings have to be supplied:

docker run --rm -p 8080:8080 -e NODE_ENV=development ilum/ui:i18n-V2

Open http://localhost:8080. The login screen and the application chrome render in the default language (English); switch language from Settings → Language. A backend is not required to preview how translated text appears.

note

NODE_ENV=development is only needed for this standalone, configuration-free local run: it tells the startup step to use the defaults baked into the image instead of expecting the ILUM_* settings. On a real Kubernetes deployment the ilum-ui ConfigMap already supplies those settings (via envFrom), so the flag is unnecessary and must not be used there. It only affects the startup step; the served application is always the production build. To change translations on an existing deployment, see On an existing Kubernetes deployment.

Get the catalog files to edit

The translation files are inside the container at /usr/share/nginx/html/locales/<language>/<namespace>.json. Copy them out of the image to edit them locally:

id=$(docker create ilum/ui:i18n-V2)
docker cp "$id:/usr/share/nginx/html/locales" ./locales
docker rm "$id"

A single file can also be downloaded over HTTP while the container is running, as shown in Get the current English files.

Edit and preview

Edit the relevant file, for example ./locales/fa/common.json (keep valid JSON, preserve the keys and every {{placeholder}}, and leave product and technology names such as Spark, Airflow, Kubernetes, and SQL untranslated). Then mount the corrected file, or the whole locales directory, over the path baked into the image and reload:

# override a single catalog file
docker run --rm -p 8080:8080 -e NODE_ENV=development \
  -v "$(pwd)/locales/fa/common.json:/usr/share/nginx/html/locales/fa/common.json:ro" \
  ilum/ui:i18n-V2

# or override the whole locales tree
docker run --rm -p 8080:8080 -e NODE_ENV=development \
  -v "$(pwd)/locales:/usr/share/nginx/html/locales:ro" \
  ilum/ui:i18n-V2

Reload http://localhost:8080, switch to the edited language, and confirm the wording. Repeat edit-and-reload to iterate; force a browser refresh if a previously loaded catalog is cached.

Hand over the result

Once the wording is correct, share the edited catalog file(s). They are applied to a real deployment by mounting them over the same path, either through the Helm values described below or, against an existing deployment that predates those values, by mounting a ConfigMap of the edited directory onto the ilum-ui container at /usr/share/nginx/html/locales/<language>.

Fixing existing translations (no rebuild)

To correct the wording of a language that already ships (for example, improve the Persian fa translations), you override that language's catalog directory at runtime with a Kubernetes ConfigMap. The mount shadows the files baked into the image.

Download and edit the files (see above), for example into a fa/ folder.

Create a ConfigMap from that folder. Each file becomes a key in the ConfigMap:

kubectl create configmap ilum-ui-locale-fa \
  --from-file=fa/ \
  -n <your-namespace>

Mount it over the language's locale directory by setting a Helm value and upgrading (see Wiring it with Helm).

ConfigMap size limit

A single ConfigMap is limited to ~1 MB and cannot contain sub-directories. One ConfigMap maps to exactly one language directory, with each namespace JSON as a key. If a language's catalogs are very large, use a mounted volume (PVC / CSI) at the same path instead.

On an existing Kubernetes deployment (no Helm changes)

If the deployment predates the i18n Helm values (for example it runs the master chart), a corrected catalog can be applied directly with kubectl, without upgrading the chart.

Use the i18n-capable image. Point the ilum-ui deployment at the UI image that includes internationalization. The language selector (English, Persian, Arabic) appears automatically: the image carries the language defaults and the existing ilum-ui ConfigMap (loaded via envFrom) supplies the rest, so no environment or ConfigMap change is required for the languages themselves.
```
kubectl set image deployment/ilum-ui ilum-ui=<registry>/ilum/ui:<tag> -n <your-namespace>
```

Create a ConfigMap from the corrected file. Read the current file out of the running container, edit it locally, then store it:

kubectl exec deploy/ilum-ui -n <your-namespace> \
  -- cat /usr/share/nginx/html/locales/fa/common.json > common.json
# edit common.json, then:
kubectl create configmap ilum-ui-locale-fa-common --from-file=common.json \
  -n <your-namespace> --dry-run=client -o yaml | kubectl apply -f -

Mount it over the single file with a subPath mount, which shadows only that file and leaves the other catalogs in place. The patch triggers a rollout:

kubectl patch deployment ilum-ui -n <your-namespace> --type=json -p '[
  {"op":"add","path":"/spec/template/spec/volumes/-",
   "value":{"name":"locale-fa-common","configMap":{"name":"ilum-ui-locale-fa-common"}}},
  {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-",
   "value":{"name":"locale-fa-common","mountPath":"/usr/share/nginx/html/locales/fa/common.json","subPath":"common.json","readOnly":true}}
]'

To replace an entire language rather than one file, create the ConfigMap from the whole language folder and mount it without subPath at /usr/share/nginx/html/locales/<language>; that mount shadows the whole directory, so include every namespace file for that language.

Adding a new language (no rebuild)

note

Ilum Enterprise already includes all supported languages. To obtain a ready-made language pack rather than translating manually, contact [email protected].

Translate the catalogs. Download the English files as a template and translate them into a new folder named with the language code, for example de/ for German. You can translate as few or as many namespaces/keys as you like; untranslated keys fall back to English.

Create a ConfigMap for the new language directory:

kubectl create configmap ilum-ui-locale-de \
  --from-file=de/ \
  -n <your-namespace>

Register the language and mount the catalog via Helm (next section), then helm upgrade. The new language appears in Settings → Language automatically.

Wiring it with Helm

The set of languages offered in the selector is driven by a single value, runtimeVars.availableLanguages, and runtime catalog mounts by i18n.extraLocaleConfigMaps.

In the all-in-one chart these live under the ilum-ui: key:

ilum-ui:
  runtimeVars:
    # Default language used on first visit and as the fallback for missing keys.
    defaultLanguage: "en"
    # Every entry here shows up in the Settings language selector.
    availableLanguages:
      - { code: "en", label: "English",  dir: "ltr" }
      - { code: "fa", label: "فارسی",    dir: "rtl", font: "IRANSans" }
      - { code: "ar", label: "العربية",  dir: "rtl", font: "Vazirmatn" }
      - { code: "de", label: "Deutsch",  dir: "ltr" }   # <-- new language

  # Mount additional / overriding catalogs at runtime (no image rebuild).
  # Each entry maps one ConfigMap to /usr/share/nginx/html/locales/<lang>/.
  i18n:
    extraLocaleConfigMaps:
      - lang: "de"
        configMap: "ilum-ui-locale-de"
      # To FIX an existing language instead, mount over it:
      # - lang: "fa"
      #   configMap: "ilum-ui-locale-fa"

In the standalone helm_ui chart, the same keys are top-level (runtimeVars.* and i18n.extraLocaleConfigMaps, without the ilum-ui: prefix).

Apply with:

helm upgrade ilum ilum/ilum -f your-values.yaml

Each language entry accepts:

Field	Required	Meaning
`code`	yes	Language code used for the catalog folder and `<html lang>` (e.g. `de`).
`label`	yes	Text shown in the language selector (write it in its own script).
`dir`	yes	`ltr` or `rtl`. `rtl` flips the entire UI to right-to-left.
`font`	no	Optional font family applied for this language (see below).

Fonts and right-to-left languages

Setting dir: "rtl" mirrors the whole interface automatically. The font field selects the typeface for a language so non-Latin scripts get the right glyph coverage:

Persian (fa), Arabic (ar), Chinese (zh), and Hindi (hi) ship with a matching webfont, so their scripts render correctly out of the box. Digits always render correctly regardless of the font in use.
Latin-script languages (English, Portuguese, Spanish) use the default interface font.

To use a different webfont for any language, host it and set the matching font value.

What cannot be changed through translation files

A few things are intentionally not in the catalogs:

Product and brand names (Spark, Jupyter, SQL, Kyuubi, MinIO, etc.) are kept in their original form on purpose.
Messages returned by the backend (server-side errors and generated analytics insight text) are shown as live data and are not part of the UI catalogs; localizing those would require backend changes.
Status / type labels are translatable, but only their displayed text. For example a job state is stored internally as FINISHED; you translate the label under workloads.json → details.job.states.FINISHED, not the underlying value.

Verify your changes

After helm upgrade, hard-refresh the UI and switch to your language in Settings → Language. You can also confirm the catalog is being served:

curl -fsS "https://<your-ilum-host>/locales/de/common.json" | head

If a string still appears in English, it simply means that key was not provided in your catalog (it fell back to the default language). Add the key to the relevant namespace file, update the ConfigMap (kubectl create configmap ... --dry-run=client -o yaml | kubectl apply -f -), and restart the UI pod so the new mount is picked up.

For end users: switching language​

How translations are stored​

The namespaces​

Get the current English files to use as a template​

Testing translations locally with the container​

Run the UI container on its own​

Get the catalog files to edit​

Edit and preview​

Hand over the result​

Fixing existing translations (no rebuild)​

On an existing Kubernetes deployment (no Helm changes)​

Adding a new language (no rebuild)​

Wiring it with Helm​

What cannot be changed through translation files​

Verify your changes​