Skip to content

fix: disable i18next key/ns separator splitting at runtime to match parser config - #29161

Open
BLACKTHOMAS wants to merge 1 commit into
open-webui:devfrom
BLACKTHOMAS:fix-i18n-separators
Open

fix: disable i18next key/ns separator splitting at runtime to match parser config#29161
BLACKTHOMAS wants to merge 1 commit into
open-webui:devfrom
BLACKTHOMAS:fix-i18n-separators

Conversation

@BLACKTHOMAS

@BLACKTHOMAS BLACKTHOMAS commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Pull Request Checklist

  • Linked Issue/Discussion: This PR references an existing, well-described Issue for a real bug — Closes i18n: keys containing ':' are mangled/blank at runtime — init() is missing the keySeparator:false / nsSeparator:false flags that i18next-parser already uses #29154.
  • First-time contributor policy: This is not my first contribution to Open WebUI (previously merged Polish translation PRs, e.g. the pending i18n: Polish translation update).
  • Target branch: The pull request targets the dev branch.
  • Description: A concise description of the changes is provided below.
  • Changelog: A changelog entry following Keep a Changelog format is included at the bottom.
  • Documentation: N/A — no user-facing configuration or feature changes; no documentation update required.
  • Dependencies: N/A — no dependency changes.
  • Testing: Manual and scripted end-to-end verification performed — see "How this was verified" below.
  • User-facing changes: Yes, but text-only: 3 previously blank/mangled labels now render correctly in every locale. No layout or behavior changes; screenshots N/A (previously the labels rendered blank — there is nothing to screenshot).
  • No Unchecked AI Code: AI-assisted, thoroughly human-reviewed AND verified with a scripted test matrix (results below).
  • Self-Review: Performed — single-file, 2-line config change matching the existing parser configuration.
  • Architecture: No new settings, no architectural change — runtime options aligned with what the shipped parser configuration already enforces.
  • Git Hygiene: Atomic single commit, rebased on current dev, no unrelated commits.
  • Title Prefix: fix.

Changelog Entry

Description

  • The shipped i18next-parser.config.ts generates fully flat catalogs (keySeparator: false, namespaceSeparator: false), but the runtime init() in src/lib/i18n/index.ts never disabled i18next's default separators. As a result, any key containing : is split by the default nsSeparator at runtime and never resolves, rendering blank or mangled in every locale, including English.
  • 2-line fix: pass keySeparator: false and nsSeparator: false to init(), restoring parity between runtime and parser configuration.

Changed

  • i18n: src/lib/i18n/index.ts — added keySeparator: false and nsSeparator: false to the runtime init() options (2 lines, no other changes).

Fixed

  • i18n: Warning: rendered as an empty string in the Functions and Tools editors; now renders the translated label (e.g. Uwaga:, Warnung:) in every locale.
  • i18n: the MinerU / local docling server URLs in admin Settings → Documents rendered mangled (//localhost.8000, //mineru.net/api/v4); now render the full, correct URLs.

How this was verified

The fix was verified against the real, shipped locale catalogs in an isolated environment, using the exact i18next version pinned by this repository's lockfile on the Node version used by this project's CI (Node 22).

  • Scope: all 64 locale catalogs loaded from the repository (3,092 keys in the en-US catalog; asserted 100% flat — zero nested objects — so disabling key splitting cannot affect any structure).
  • Runtime fidelity: two i18next instances were initialized with the exact init() options from initI18n() (same fallbacks, returnEmptyString: false, interpolation settings) — one without the fix (current dev behavior) and one with the fix — and compared call-by-call.
  • Full matrix: every en-US key × every locale = 197,888 t() invocations per run. After the fix, output matched the expected catalog/fallback value in 100% of calls (0 mismatches), including i18next's full language-resolution hierarchy (e.g. ar-BH → ar → en-US, and fr-CA → fr-FR via the existing fallbackLng configuration).
  • Behavioral delta: exactly 3 keys change behavior — all three contain : and are the broken ones from the linked issue. Zero behavior change on the other 3,089 keys, including all keys containing . and all keys with : protected by i18next's natural-language heuristic (57 keys).
  • Plurals: 14 plural bases × 8 count values × 64 locales (7,168 calls) — identical output before and after.
  • Interpolation: all 155 keys containing {{variables}} — identical output before and after.
  • Future-proofing: the entire matrix was re-run on i18next 25.10.10 and 26.4.0 with identical results, so the fix remains correct if the dependency is ever bumped.
  • Code audit: the repository contains no getFixedT, no additional createInstance calls, no array-key t() usage, and no per-call separator overrides — the application exclusively uses the single default instance with string keys and an options object, which is exactly the configuration exercised by the matrix above.
  • Totals: ~614,000 t() invocations across the three runs; all 45 assertions passed, 0 failures.

Additional Information

  • Root cause and per-key analysis are documented in the linked issue. Translations for the affected keys already exist in the shipped catalogs (e.g. Warning:Uwaga: in pl-PL) and become reachable again with this change.
  • Keys that are intentionally empty fall back to en-US at runtime (existing returnEmptyString: false behavior), so nothing new is introduced there.

Contributor License Agreement

@BLACKTHOMAS

Copy link
Copy Markdown
Contributor Author

Note on the failing Format & Build check: the failure is pre-existing on current dev and is not introduced by this PR.

  • The check runs npm run i18n:parse and then asserts a clean working tree. Running the parser on an unmodified dev checkout produces the same ~64-file locale diff shown in this run (added Accessibility Mode / Preview may differ from download., removed High Contrast Mode, zh-CN plural key normalization) — the recent High Contrast ModeAccessibility Mode rename on dev was not followed by a parser run, so dev itself is currently failing this same check (the last three Frontend Build runs on dev are red).
  • The diff in the failing log touches only src/lib/i18n/locales/*.json — none of the files changed by this PR (src/lib/i18n/index.ts only).
  • The locale sync that makes this check green is already submitted in PR i18n: complete Polish (pl-PL) translation + locale key sync #29155; once that sync (or a maintainer parser run) lands on dev, this check will pass here as well. Happy to include the sync in this PR instead if maintainers prefer.

@BLACKTHOMAS
BLACKTHOMAS marked this pull request as ready for review August 28, 2026 19:49
@BLACKTHOMAS BLACKTHOMAS reopened this Aug 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant