Localization
Stellarr supports English (en, default) and Polish (pl) across the web client, Stellarr Cockpit, and the ASP.NET Core API, plus optional offline in-browser chat translation powered by Bergamot WASM.
Locale resolution and STELLARR_LANGUAGE
Interface language and chat message translation are configured independently:
- Interface language (
locale): Controls UI text andIntldate/time/number formatting. - Chat translation: Optional client-side translation of messages into a target language (
enorpl); never modifies stored message content.
Setting STELLARR_LANGUAGE=pl (or en) configures the instance default across all three components:
Web client (
web/src/stellarr/): Because the static client bundle is identical across deployments, container startup writesSTELLARR_LANGUAGEto/stellarr-instance.js(infra/entrypoint.sh). A blocking script (web/src/stellarr/i18n/localeScript.ts) applies the first match onto<html lang>anddata-localebefore first paint:- User preference saved in
localStorage(stellarr_language_settings.locale, written only once the user explicitly picks a language in Settings) - Instance default from
/stellarr-instance.js en
(Browsers cache
/stellarr-instance.jsfor up to 1 hour in production; dev/preview servers revalidate it on every load.)- User preference saved in
Cockpit (
web/src/cockpit/): Uses the locale saved in its own Settings page (localStoragekeystellarr.cockpit.locale), defaulting toen. It ignores both browser preferences and the web client's locale, and does not load/stellarr-instance.js.API (
server/Stellarr.Api/): ReadsStellarr:Language(STELLARR_LANGUAGE) at startup (LanguageOptions) for API problem details, validation errors, system join notices, default server/role/channel names, audit entries, and emails.
NOTE
Changing STELLARR_LANGUAGE applies to API responses, emails, and new records going forward. Records already written to SQLite retain their original language.
Message catalogs
- Web client (
web/src/stellarr/i18n/):messages/pl.tsdefinesMessageKey, andmessages/en.tschecks parity viasatisfies Record<keyof typeof pl, string>atnpm run typecheck.t(key, values)interpolates{name}placeholders as plain text.LanguageProviderpersistsstellarr_language_settingsinlocalStorage. - Cockpit (
web/src/cockpit/i18n/):en.tsandpl.tsenforce matching key sets and{name}interpolation. - Backend API (
server/Stellarr.Api/Localization/):MessageKey.csenumerates server message keys;Messages.en.csandMessages.pl.csimplement exhaustive switch expressions overMessageKey.
Client-side chat translation
TIP
Chat translation runs locally inside the user's browser using WebAssembly and a Web Worker. Message text never leaves the browser, and downloaded models are cached in IndexedDB across sessions.
- Registry check: Enabling translation checks the required
model,lex, andvocabfiles for the pair (plenorenpl) inweb/public/bergamot-models/registry.json. - Same-origin download: Missing model files download from
/bergamot-models/<pair>/<file>on your Stellarr instance, never from an external host. Prebuilt assets live inartifacts/files/and are staged intoweb/public/byartifacts/assemble.mjs. - IndexedDB caching: Completed downloads are stored in IndexedDB (
bergamot-models, storefiles) and verified against sizes and SHA-256 hashes shared withartifacts/manifest.json. - Worker execution: A Web Worker runs the Bergamot WASM runtime (
/codecs/bergamot/) off the main thread. - Language detection (
web/src/stellarr/lib/chatTranslation/detectLanguage.ts): Runs on the main thread with zero extra downloads using character-trigram profiles (web/scripts/derive-language-profiles.mjs), function-word counts, and character/diacritic checks. Messages already in the target language are skipped; ambiguous short strings translate from the opposite language. - Translation cache: Results are cached in memory (up to 1,000 entries) and IndexedDB (
stellarr-chat-translations, up to 5,000 entries, LRU-evicted), with request deduplication and viewport prioritization.
Asset integrity and cache policy: artifacts/manifest.json tracks the exact origin, size, SHA-256, and SPDX license for every prebuilt browser file (artifacts/NOTICES ships beside it at /usr/share/doc/stellarr/artifacts/). artifacts/assemble.mjs verifies every file before builds and replaces copies atomically. Because worklets, WASM, and models keep stable URLs across releases, Nginx serves them with Cache-Control: no-cache so browsers always revalidate matching versions together.
Adding a new language
- Web client:
- Add the code to
SUPPORTED_LOCALESinweb/src/stellarr/i18n/index.ts, createweb/src/stellarr/i18n/messages/<code>.ts, and addlanguage.name.<code>across all catalogs. - Register the chunk in
LOADERS(web/src/stellarr/i18n/index.ts),CATALOGS(web/src/stellarr/i18n/localeScript.ts),CATALOG_MODULES/preloadPlan(web/documents.ts),CATALOG_UNAVAILABLE(web/src/stellarr/i18n/messages/unavailable.ts), andweb/vitest.setup.ts(npm run typecheckchecks these). - Add the code to
write_instance_languageininfra/entrypoint.sh(checked byweb/documents.test.ts). - Add the native label to
NATIVE_NAMESinweb/src/stellarr/components/account/panes/LanguagePane.tsxand the BCP 47 tag toLOCALE_TAGinweb/src/stellarr/lib/format/format.ts(and verifypluralForm). - For chat translation support, update
TranslationTargetLanguage(i18n/index.ts),primaryPair(lib/chatTranslation/modelStatus.ts),artifacts/manifest.json,artifacts/NOTICES, andweb/public/bergamot-models/registry.json, placing model files underartifacts/files/bergamot-models/<pair>/.
- Add the code to
- Cockpit:
- Add
web/src/cockpit/i18n/<code>.tsand register the locale inweb/src/cockpit/i18n/index.ts.
- Add
- Backend API:
- Add the code to
LanguageOptions.cs, createMessages.<code>.cs, and wire it intoMessages.cs.
- Add the code to
Verification
Install dependencies once from the repository root with npm ci (web/ and packages/ share the root workspace lockfile):
# Web client and Cockpit
cd web
npm test
npm run typecheck
npm run lint
npm run test:translation-runtime
# Cockpit tests alone
npx vitest run --project cockpit
# Server localization tests
cd ..
dotnet test server/Stellarr.Api.Tests --filter LocalizationTestsnpm run test:translation-runtime stages assets from artifacts/manifest.json and runs headless Chromium (/usr/bin/chromium or STELLARR_CHROMIUM) offline against the real Bergamot worker and models, verifying both live translation and IndexedDB cache hits on reload.