// OPENBOX DOCS

Localization

OpenBox ships in 5 languages. How the i18n system works, and how to add more.

Localization

OpenBox ships locale catalogs for English, Spanish, German, French, and Portuguese. The locale selector is in Settings > Interface language; switching re-translates the keyed UI surfaces without a page reload. Some operational and browser fallback labels remain English.

How it works

The i18n system uses three layers:

  1. Locale files: JSON files in locales/{en,es,de,fr,pt}.json with a nested key structure (e.g. nav.library, sidebar.search, settings.title).
  2. HTML translation: data-i18n="key" attributes on translatable elements; data-i18n-placeholder, data-i18n-title, and data-i18n-aria-label for attribute translation.
  3. JS translation: t(key, params) from static/i18n.js with {placeholder} interpolation and automatic English fallback for missing keys.

The locale is loaded via fetch('/locales/{locale}.json') on page load, with en.json as the canonical fallback. The available locales are exposed in public_settings as available_locales.

Gate enforcement

scripts/check_i18n.py runs on every make check and verifies:

  • All 5 locale files have 100% key coverage (no missing keys in any locale).
  • All data-i18n and t() references in the codebase have corresponding keys in en.json.
  • No locale file carries extra keys outside en.json: an extra key fails the gate the same way a missing key does.

A locale file with missing keys will fail CI. This prevents shipping partial translations. The gate verifies key and placeholder parity, not translation quality.

1.18.0 copy still in English

In es, de, fr, and pt, the 1.18.0 additions are present with the same keys and placeholders but are still English strings in this release: the renamed and newly added Tools entries (including the four group headings and their 17 hints), the Add games menu, the new top-bar labels, and the new setup, help, onboarding, and Jump back in copy. That is 52 of the 55 renamed or new tools.* and nav.* keys per locale, plus the new setup, help, onboarding, and Add games copy. Untouched entries keep their existing translations, and a native-copy translation pass follows.

Adding a new language

  1. Create locales/{code}.json with the same key structure as locales/en.json.
  2. Add the locale code to SUPPORTED_LOCALES in static/i18n.js.
  3. Add the locale to the public GET list in crates/openbox-http/src/middleware.rs and SUPPORTED_LOCALES in static/i18n.js.
  4. Add the locale to PUBLIC_GET_PATHS in routes.py.
  5. Add the locale to available_locales in crates/openbox-http/src/handlers/projection.rs.
  6. Run python3 scripts/check_i18n.py to verify 100% key coverage.
  7. Run make check to verify the full gate passes.

Each entry in available_locales carries both a plain name and a native name, but the picker renders only the native one — the option label is the native name, falling back to the plain name and then the code. So the shipped list shows English, Español, Deutsch, Français, and Português; the plain names (English, Spanish, German, French, Portuguese) exist in the payload but are never displayed. Add a native name to a new locale or its picker entry will fall back to the plain name.