diff --git a/.github/workflows/check-admin-i18n.yml b/.github/workflows/check-admin-i18n.yml new file mode 100644 index 00000000..01a11cdb --- /dev/null +++ b/.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 diff --git a/.github/workflows/check-template-i18n.yml b/.github/workflows/check-template-i18n.yml new file mode 100644 index 00000000..78a860cf --- /dev/null +++ b/.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 diff --git a/.github/workflows/check-template-locales.yml b/.github/workflows/check-template-locales.yml new file mode 100644 index 00000000..b9024dc4 --- /dev/null +++ b/.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 diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md new file mode 100644 index 00000000..f002699b --- /dev/null +++ b/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//`. +- 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//` 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 `.json` or directory `/*.json`). +3. **Admin Frontend Serving**: + - `admin_ui.json` dictionaries are automatically exposed at `/vw_static/locales//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`. diff --git a/docs/i18n.md b/docs/i18n.md new file mode 100644 index 00000000..3f9e7981 --- /dev/null +++ b/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//*.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. diff --git a/tools/check_admin_i18n_keys.py b/tools/check_admin_i18n_keys.py new file mode 100644 index 00000000..160e5d43 --- /dev/null +++ b/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//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//") + 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()) diff --git a/tools/check_template_i18n_keys.py b/tools/check_template_i18n_keys.py new file mode 100644 index 00000000..e1d9ca6c --- /dev/null +++ b/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//*.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//*.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()) diff --git a/tools/check_template_locale_duplicates.py b/tools/check_template_locale_duplicates.py new file mode 100644 index 00000000..b9555ca9 --- /dev/null +++ b/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())