You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

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:

  1. 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
  1. Runtime overlays from DATA_FOLDER/locales
  • Supported layouts:
    • DATA_FOLDER/locales/<locale>.json
    • DATA_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:

  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/<locale>/admin.json
  • src/static/locales/<locale>/admin_ui.json
  • src/static/locales/<locale>/templates.json
  • src/static/locales/<locale>/auth.json
  • src/static/locales/<locale>/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
  1. Admin frontend catalog
  • admin_ui.json is served at /vw_static/locales/<locale>/admin_ui.json
  • consumed by Admin UI scripts

Adding a New Language

  1. Create src/static/locales/<lang>/
  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.