3.6 KiB
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:
- Compile-time embedded base catalogs via
include_dir
- Source:
src/static/locales/<locale>/*.json - Loaded into static maps at startup through
LazyLock - No runtime disk reads for built-in catalogs
- Runtime overlays from
DATA_FOLDER/locales
- Supported layouts:
DATA_FOLDER/locales/<locale>.jsonDATA_FOLDER/locales/<locale>/*.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/<locale>/ are discovered automatically. Adding a language does not require Rust source changes.
Resolution order:
- User locale preference
Accept-Languagefirst token- Server default locale
Lookup fallback chain:
- Full normalized locale (for example
pt-br) - Normalized base language (for example
pt) 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:
- Admin interface (
/admintemplates and messages) - Handlebars template keys (
tpl.*, including email templates) - 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/<locale>/admin.jsonsrc/static/locales/<locale>/admin_ui.jsonsrc/static/locales/<locale>/templates.jsonsrc/static/locales/<locale>/auth.jsonsrc/static/locales/<locale>/api.json- additional domain files (
accounts.json,org.json,two_factor.json,ciphers.json, and others)
Separation of concerns:
- Backend/template catalogs
- consumed by Rust i18n lookups and Handlebars helper
- Admin frontend catalog
admin_ui.jsonis served at/vw_static/locales/<locale>/admin_ui.json- consumed by Admin UI scripts
Adding a New Language
- Create
src/static/locales/<lang>/ - Copy English files from
src/static/locales/en/ - Keep key sets identical
- Translate values while preserving placeholders (
{},{{...}},%s, and token names) - Run validators:
python3 tools/check_template_locale_duplicates.pypython3 tools/check_template_i18n_keys.pypython3 tools/check_admin_i18n_keys.py
- 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.