Browse Source

docs(i18n): add architecture guide and upstream pr description

Add maintainer-focused i18n architecture documentation and a ready-to-use PR body. Include stdlib-only validation scripts and CI workflows for template/admin key parity and duplicate template guards.
pull/7913/head
Oneill26 2 weeks ago
parent
commit
41bf067e96
  1. 41
      .github/workflows/check-admin-i18n.yml
  2. 39
      .github/workflows/check-template-i18n.yml
  3. 39
      .github/workflows/check-template-locales.yml
  4. 47
      PR_DESCRIPTION.md
  5. 114
      docs/i18n.md
  6. 119
      tools/check_admin_i18n_keys.py
  7. 93
      tools/check_template_i18n_keys.py
  8. 88
      tools/check_template_locale_duplicates.py

41
.github/workflows/check-admin-i18n.yml

@ -0,0 +1,41 @@
name: Check admin i18n
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
on:
push:
paths:
- ".github/workflows/check-admin-i18n.yml"
- "src/static/scripts/admin*.js"
- "src/static/templates/admin/**/base.hbs"
- "src/static/locales/**/admin_ui.json"
- "tools/check_admin_i18n_keys.py"
pull_request:
paths:
- ".github/workflows/check-admin-i18n.yml"
- "src/static/scripts/admin*.js"
- "src/static/templates/admin/**/base.hbs"
- "src/static/locales/**/admin_ui.json"
- "tools/check_admin_i18n_keys.py"
defaults:
run:
shell: bash
jobs:
admin-i18n:
name: Validate admin i18n coverage
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- name: "Checkout"
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Run admin i18n key coverage check
run: python3 tools/check_admin_i18n_keys.py

39
.github/workflows/check-template-i18n.yml

@ -0,0 +1,39 @@
name: Check template i18n
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
on:
push:
paths:
- ".github/workflows/check-template-i18n.yml"
- "src/static/templates/**/*.hbs"
- "src/static/locales/**/*.json"
- "tools/check_template_i18n_keys.py"
pull_request:
paths:
- ".github/workflows/check-template-i18n.yml"
- "src/static/templates/**/*.hbs"
- "src/static/locales/**/*.json"
- "tools/check_template_i18n_keys.py"
defaults:
run:
shell: bash
jobs:
template-i18n:
name: Validate template i18n key coverage
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- name: "Checkout"
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Run template i18n key coverage check
run: python3 tools/check_template_i18n_keys.py

39
.github/workflows/check-template-locales.yml

@ -0,0 +1,39 @@
name: Check template locales
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
on:
push:
paths:
- ".github/workflows/check-template-locales.yml"
- "src/static/templates/**/*.hbs"
- "src/config.rs"
- "tools/check_template_locale_duplicates.py"
pull_request:
paths:
- ".github/workflows/check-template-locales.yml"
- "src/static/templates/**/*.hbs"
- "src/config.rs"
- "tools/check_template_locale_duplicates.py"
defaults:
run:
shell: bash
jobs:
template-locales:
name: Validate no locale-duplicated templates
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- name: "Checkout"
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Run template locale duplication check
run: python3 tools/check_template_locale_duplicates.py

47
PR_DESCRIPTION.md

@ -0,0 +1,47 @@
### Title: feat: Add extensible i18n architecture for admin interface and templates
## Summary
This PR introduces an extensible i18n architecture for server-rendered templates, backend notifications, and Admin UI strings. The core design keeps default behavior deterministic and zero-cost with compile-time embedded catalogs, while enabling runtime locale overrides for self-hosters.
## Motivation
Vaultwarden has historically lacked localized coverage in the `/admin` interface and template-driven surfaces. This PR:
- Centralizes locale dictionaries under `src/static/locales/<locale>/`.
- Removes hardcoded locale lists by leveraging directory auto-discovery at compile time.
- Enforces strict translation coverage and schema parity using lightweight CI quality gates.
## Key Features
1. **Extensible Compile-Time Locale Discovery**:
- Base catalogs are embedded via `include_dir`.
- New languages added under `src/static/locales/<locale>/` are picked up automatically without modifying Rust source files.
2. **Runtime Override Support**:
- Self-hosters can supply custom translations via `DATA_FOLDER/locales` (single-file `<locale>.json` or directory `<locale>/*.json`).
3. **Admin Frontend Serving**:
- `admin_ui.json` dictionaries are automatically exposed at `/vw_static/locales/<locale>/admin_ui.json` and consumed by the admin client script.
4. **Fallback & Graceful Degradation**:
- Robust fallback chain (`full-locale` -> `base-lang` -> `en`).
- Missing keys render the key identifier safely instead of failing the render.
5. **Zero-Dependency CI Guards**:
- Standalone Python standard-library scripts prevent missing keys, duplicate registrations, and inline dictionary regressions.
## Compatibility & Breaking Changes
- **Fully backward compatible**: Existing deployments, database backends, and environment configurations behave identically.
- **API integrity preserved**: Client-facing API payloads and error formats for official Bitwarden apps remain intact.
## Testing Performed
- **Validation Scripts (Python stdlib)**:
- `python3 tools/check_template_locale_duplicates.py` (Passed)
- `python3 tools/check_template_i18n_keys.py` (Passed)
- `python3 tools/check_admin_i18n_keys.py` (Passed)
- **Engine Database Feature Matrix**:
- `cargo check --features sqlite` (Passed)
- `cargo check --features postgresql` (Passed)
- `cargo check --features mysql` (Passed)
- **Formatting & Lints**:
- `cargo fmt --all --check` (Passed)
- `cargo clippy --all-targets -- -D warnings` (Passed)
- **Runtime Verification**:
- Tested `/admin` localization with various `Accept-Language` headers (`ru`, `en-US`, unsupported fallbacks).
- Verified static dictionary delivery under `/vw_static/locales/`.
## Documentation
A full architectural overview and contributor guide is provided in `docs/i18n.md`.

114
docs/i18n.md

@ -0,0 +1,114 @@
# 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
2. 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
2. 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.

119
tools/check_admin_i18n_keys.py

@ -0,0 +1,119 @@
#!/usr/bin/env python3
"""Validate Admin UI translation key coverage.
This script extracts i18n keys referenced by ``src/static/scripts/admin*.js``
and verifies they exist in every discovered
``src/static/locales/<locale>/admin_ui.json`` dictionary.
It also ensures inline fallback dictionaries are not reintroduced into admin
templates.
Exit status:
- 0: all checks passed
- 1: missing keys, missing required locales, or inline dictionary violations
"""
from __future__ import annotations
import json
import re
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
SCRIPTS_DIR = ROOT / "src" / "static" / "scripts"
LOCALES_DIR = ROOT / "src" / "static" / "locales"
REQUIRED_LOCALES = {"en", "ru"}
TEMPLATE_FILES = [
*sorted((ROOT / "src" / "static" / "templates" / "admin").glob("**/base.hbs")),
]
KEY_PATTERN = re.compile(r't(?:Admin|Users|Orgs|Settings|Diag)\("([a-z0-9_]+)"\)')
INLINE_DICT_MARKER = "window.VW_ADMIN_I18N = {"
def read_admin_js_keys() -> set[str]:
keys: set[str] = set()
for script_path in sorted(SCRIPTS_DIR.glob("admin*.js")):
content = script_path.read_text(encoding="utf-8")
keys.update(KEY_PATTERN.findall(content))
return keys
def read_locale_keys(locale_path: Path) -> set[str]:
with locale_path.open("r", encoding="utf-8") as f:
payload = json.load(f)
if not isinstance(payload, dict):
raise ValueError(f"Locale file must contain JSON object: {locale_path}")
return set(payload.keys())
def discover_locale_files() -> dict[str, Path]:
locales: dict[str, Path] = {}
for locale_dir in sorted(LOCALES_DIR.iterdir()):
if not locale_dir.is_dir():
continue
locale_file = locale_dir / "admin_ui.json"
if locale_file.exists():
locales[locale_dir.name] = locale_file
return locales
def check_no_inline_dicts() -> list[str]:
violations: list[str] = []
for template_path in TEMPLATE_FILES:
if not template_path.exists():
continue
content = template_path.read_text(encoding="utf-8")
if INLINE_DICT_MARKER in content:
violations.append(str(template_path.relative_to(ROOT)))
return violations
def main() -> int:
js_keys = read_admin_js_keys()
if not js_keys:
print("ERROR: No admin i18n keys found in src/static/scripts/admin*.js")
return 1
failed = False
locale_files = discover_locale_files()
if not locale_files:
print("ERROR: No admin_ui.json locale files found in src/static/locales/<locale>/")
failed = True
missing_required_locales = sorted(REQUIRED_LOCALES - set(locale_files.keys()))
if missing_required_locales:
failed = True
print("ERROR: Missing required locale dictionaries:")
for locale in missing_required_locales:
print(f" - src/static/locales/{locale}/admin_ui.json")
for locale, locale_path in locale_files.items():
locale_keys = read_locale_keys(locale_path)
missing = sorted(js_keys - locale_keys)
if missing:
failed = True
print(f"ERROR: Missing keys in {locale_path.relative_to(ROOT)}:")
for key in missing:
print(f" - {key}")
else:
print(f"OK: {locale} locale covers all {len(js_keys)} admin JS keys")
inline_violations = check_no_inline_dicts()
if inline_violations:
failed = True
print("ERROR: Inline admin dictionaries are not allowed in templates:")
for file_path in inline_violations:
print(f" - {file_path}")
else:
print("OK: No inline admin dictionaries in admin base templates")
return 1 if failed else 0
if __name__ == "__main__":
sys.exit(main())

93
tools/check_template_i18n_keys.py

@ -0,0 +1,93 @@
#!/usr/bin/env python3
"""Validate template translation key coverage.
This script collects keys used by the Handlebars helper ``{{t "..."}}``
in ``src/static/templates`` and verifies that every discovered locale catalog
under ``src/static/locales/<locale>/*.json`` defines those keys.
Exit status:
- 0: all checks passed
- 1: at least one key is missing or required locales are absent
"""
from __future__ import annotations
import json
import re
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
TEMPLATES_DIR = ROOT / "src" / "static" / "templates"
LOCALES_DIR = ROOT / "src" / "static" / "locales"
REQUIRED_LOCALES = {"en", "ru"}
# Supports: {{t "key"}}, {{ t "key" locale=lang }}
KEY_PATTERN = re.compile(r"\{\{\s*t\s+\"([a-z0-9_.-]+)\"")
def discover_locale_catalogs() -> dict[str, dict[str, str]]:
catalogs: dict[str, dict[str, str]] = {}
for locale_dir in sorted(LOCALES_DIR.iterdir()):
if not locale_dir.is_dir():
continue
merged: dict[str, str] = {}
json_files = sorted(p for p in locale_dir.glob("*.json") if p.is_file())
for file_path in json_files:
with file_path.open("r", encoding="utf-8") as f:
payload = json.load(f)
if not isinstance(payload, dict):
raise ValueError(f"Locale file must contain JSON object: {file_path.relative_to(ROOT)}")
for key, value in payload.items():
if isinstance(key, str) and isinstance(value, str):
merged[key] = value
if merged:
catalogs[locale_dir.name] = merged
return catalogs
def collect_template_keys() -> set[str]:
keys: set[str] = set()
for template_path in sorted(TEMPLATES_DIR.rglob("*.hbs")):
content = template_path.read_text(encoding="utf-8")
keys.update(KEY_PATTERN.findall(content))
return keys
def main() -> int:
template_keys = collect_template_keys()
if not template_keys:
print("OK: No template i18n helper keys found")
return 0
catalogs = discover_locale_catalogs()
failed = False
missing_required = sorted(REQUIRED_LOCALES - set(catalogs.keys()))
if missing_required:
failed = True
print("ERROR: Missing required locale catalogs under src/static/locales/<locale>/*.json:")
for locale in missing_required:
print(f" - {locale}")
for locale, catalog in sorted(catalogs.items()):
locale_keys = set(catalog.keys())
missing = sorted(template_keys - locale_keys)
if missing:
failed = True
print(f"ERROR: Missing template i18n keys in locale '{locale}':")
for key in missing:
print(f" - {key}")
else:
print(f"OK: locale '{locale}' covers all {len(template_keys)} template i18n keys")
return 1 if failed else 0
if __name__ == "__main__":
sys.exit(main())

88
tools/check_template_locale_duplicates.py

@ -0,0 +1,88 @@
#!/usr/bin/env python3
"""Prevent locale-specific Handlebars template duplication.
This script enforces the shared-template + dictionary-based i18n model by
failing when locale-specific template files (for example ``templates/ru/...``)
or locale-specific template registrations are found.
Exit status:
- 0: no forbidden locale template files or registrations
- 1: forbidden locale template files or registrations found
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
TEMPLATES_DIR = ROOT / "src" / "static" / "templates"
CONFIG_RS = ROOT / "src" / "config.rs"
LOCALE_DIR_PATTERN = re.compile(r"^[a-z]{2}(?:-[A-Za-z]{2})?$")
def collect_forbidden_template_files() -> list[Path]:
forbidden: list[Path] = []
for template_path in sorted(TEMPLATES_DIR.rglob("*.hbs")):
rel = template_path.relative_to(TEMPLATES_DIR)
parent_parts = rel.parts[:-1]
if not parent_parts:
continue
# Forbid locale directories at template root: templates/ru/*.hbs
if LOCALE_DIR_PATTERN.match(parent_parts[0]):
forbidden.append(template_path)
continue
# Forbid locale directories under a template namespace: templates/email/ru/*.hbs
if len(parent_parts) >= 2 and LOCALE_DIR_PATTERN.match(parent_parts[1]):
forbidden.append(template_path)
return forbidden
def collect_forbidden_template_registrations() -> list[str]:
if not CONFIG_RS.exists():
return []
content = CONFIG_RS.read_text(encoding="utf-8")
# Matches entries like: reg!("email/ru/verify_email", ".html");
pattern = re.compile(r'reg!\(\s*"[^"/]+/([a-z]{2}(?:-[A-Za-z]{2})?)/[^"]+"')
matches = []
for match in pattern.finditer(content):
locale = match.group(1)
if LOCALE_DIR_PATTERN.match(locale):
matches.append(match.group(0))
return sorted(set(matches))
def main() -> int:
failed = False
forbidden_files = collect_forbidden_template_files()
if forbidden_files:
failed = True
print("ERROR: Found forbidden locale-specific templates (use shared templates + i18n dictionaries):")
for file_path in forbidden_files:
print(f" - {file_path.relative_to(ROOT)}")
forbidden_regs = collect_forbidden_template_registrations()
if forbidden_regs:
failed = True
print("ERROR: Found forbidden locale-specific template registrations in src/config.rs:")
for reg in forbidden_regs:
print(f" - {reg}")
if failed:
return 1
print("OK: No locale-specific template files or registrations found")
return 0
if __name__ == "__main__":
sys.exit(main())
Loading…
Cancel
Save