# i18n Architecture Guide This document describes the localization architecture used by Vaultwarden for templates and Admin UI while preserving client-facing API compatibility. ## Dual-Layer Architecture Vaultwarden uses two catalog layers: 1. Compile-time embedded base catalogs via `include_dir` - Source: `src/static/locales//*.json` - Loaded into static maps at startup through `LazyLock` - No runtime disk reads for built-in catalogs 2. Runtime overlays from `DATA_FOLDER/locales` - Supported layouts: - `DATA_FOLDER/locales/.json` - `DATA_FOLDER/locales//*.json` - Runtime values merge over built-ins - Changes require process restart because catalogs are loaded once ## Locale Discovery and Resolution Locale directories under `src/static/locales//` are discovered automatically. Adding a language does not require Rust source changes. Resolution order: 1. User locale preference 2. `Accept-Language` first token 3. Server default locale Lookup fallback chain: 1. Full normalized locale (for example `pt-br`) 2. Normalized base language (for example `pt`) 3. `en` Normalization rules: - `_` is converted to `-` - locale identifiers are stored in lowercase - client culture formatting uses uppercase region (for example `pt-BR`) ## Localization Scope and API Compatibility Localization is intentionally scoped to user-facing surfaces: 1. Admin interface (`/admin` templates and messages) 2. Handlebars template keys (`tpl.*`, including email templates) 3. Admin frontend dictionaries (`admin_ui.json`) Client-facing API/auth/vault error strings remain in English format for compatibility with official Bitwarden clients that may rely on strict message patterns. ## Handlebars Integration Template helper usage: - `{{t "namespace.key"}}` - optional locale argument: `{{t "namespace.key" locale=lang}}` The helper resolves locale from arguments/context (`locale` or `lang`) and performs dictionary lookup. Missing key behavior is fail-safe: - `out.write(key)` This avoids render-time failures during incremental migrations. ## Directory Structure Each locale directory can contain domain catalogs such as: - `src/static/locales//admin.json` - `src/static/locales//admin_ui.json` - `src/static/locales//templates.json` - `src/static/locales//auth.json` - `src/static/locales//api.json` - additional domain files (`accounts.json`, `org.json`, `two_factor.json`, `ciphers.json`, and others) Separation of concerns: 1. Backend/template catalogs - consumed by Rust i18n lookups and Handlebars helper 2. Admin frontend catalog - `admin_ui.json` is served at `/vw_static/locales//admin_ui.json` - consumed by Admin UI scripts ## Adding a New Language 1. Create `src/static/locales//` 2. Copy English files from `src/static/locales/en/` 3. Keep key sets identical 4. Translate values while preserving placeholders (`{}`, `{{...}}`, `%s`, and token names) 5. Run validators: - `python3 tools/check_template_locale_duplicates.py` - `python3 tools/check_template_i18n_keys.py` - `python3 tools/check_admin_i18n_keys.py` 6. Run build checks: - `cargo check --features sqlite` If checks pass, the language is available automatically. ## Quality Gates `tools/check_template_locale_duplicates.py` - blocks reintroduction of locale-specific template file copies/registrations `tools/check_template_i18n_keys.py` - validates `{{t "..."}}` keys are present in locale catalogs `tools/check_admin_i18n_keys.py` - validates admin script keys exist in `admin_ui.json` - blocks inline fallback dictionaries in admin templates All three scripts use only Python standard library modules.