diff --git a/api/config.py b/api/config.py index 58afc932..fb09a823 100644 --- a/api/config.py +++ b/api/config.py @@ -11468,7 +11468,13 @@ _SETTINGS_DEFAULTS = { "hidden_tabs": [], # sidebar tab panel names hidden by user (e.g. ["tasks","kanban"]); chat and settings are always visible "tab_order": [], # user-defined sidebar/rail tab order for reorderable tabs; chat/settings stay fixed "composer_control_order": [], # user-defined composer footer control order; invalid/duplicate keys are ignored - "language": "en", # UI locale code; must match a key in static/i18n.js LOCALES + # #7622 (round 3): language is intentionally absent from the defaults so + # `load_settings()` reports `None` for a fresh install. This lets the + # client distinguish "no preference" from an explicit saved choice, + # so a user who genuinely picked English (and has `language: "en"` + # persisted on disk) is no longer overridden by the browser hint on + # their first hydration. When a user picks a locale in the Settings + # modal the value is written here and the field is set explicitly. "bot_name": os.getenv( "HERMES_WEBUI_BOT_NAME", "Hermes" ), # display name for the assistant @@ -11715,6 +11721,15 @@ _SETTINGS_ALLOWED_KEYS = set(_SETTINGS_DEFAULTS.keys()) - { "password_hash", "default_model", "simplified_tool_calling", +} | { + # #7622 (round 3): `language` is intentionally absent from + # `_SETTINGS_DEFAULTS` so a fresh install returns `None` for + # `settings["language"]` and the client can distinguish "no + # preference" from an explicit saved choice. But the user + # MUST still be able to pick a locale in the Settings modal, + # so we add it back to the explicit allow-list here. The + # existing BCP-47 validation at save-time still applies. + "language", } _SETTINGS_ENUM_VALUES = { "send_key": {"enter", "ctrl+enter", "shift+enter"}, diff --git a/static/boot.js b/static/boot.js index 6a33c45c..06c3888d 100644 --- a/static/boot.js +++ b/static/boot.js @@ -3431,24 +3431,18 @@ window._mirrorSpeechSettingsFromServer=_mirrorSpeechSettingsFromServer; localStorage.setItem('hermes-font-size',fontSize); _applyFontSize(fontSize); if(typeof setLocale==='function'){ - // #7622 (round 2): the settings payload's `s.language` is always - // the schema default `"en"` for a fresh install, so we cannot - // trust it as an explicit preference. Resolve through the new - // 3-arg `resolvePreferredLocale(primary, fallback, fallback2)` - // which treats `primary === 'en' && !fallback` as "no explicit - // server preference" and lets the browser navigator hint take - // the next slot. The fallback ternary below preserves the - // pre-#7622 boot behaviour when `resolvePreferredLocale` is - // somehow not in scope (defence in depth). - const _stored=localStorage.getItem('hermes-lang'); - const _browserHint=(typeof navigator!=='undefined') - ? (Array.isArray(navigator.languages)&&navigator.languages.length - ? navigator.languages[0] - : (typeof navigator.language==='string'?navigator.language:null)) - : null; + // #7622 (round 3): the settings payload's `s.language` is + // absent (None) for a fresh install, so an explicit non-empty + // value is the user's genuine saved choice. The browser + // navigator hint is now read via the guarded + // `_detectBrowserLanguageHint()` helper (round-3 finding 2) so + // a throwing `navigator` accessor in some embedded webviews + // can no longer abort this branch and reset loaded preferences. + // The fallback ternary preserves the pre-#7622 boot behaviour + // when neither helper is in scope (defence in depth). const _lang=typeof resolvePreferredLocale==='function' - ? resolvePreferredLocale(s.language, _stored, _browserHint) - : (s.language || _stored || _browserHint || 'en'); + ? resolvePreferredLocale(s.language, localStorage.getItem('hermes-lang'), _detectBrowserLanguageHint()) + : (s.language || localStorage.getItem('hermes-lang') || 'en'); setLocale(_lang); if(typeof applyLocaleToDOM==='function')applyLocaleToDOM(); } diff --git a/static/i18n.js b/static/i18n.js index eec507f0..269ffe43 100644 --- a/static/i18n.js +++ b/static/i18n.js @@ -26988,36 +26988,63 @@ function resolveLocale(lang) { * 3) fallback2 (typically browser navigator hint — first-visit only) * 4) 'en' (final fallback) * - * #7622 (round 2): the server's schema default `"language": "en"` is NOT - * an explicit user / server preference — it's the field's default value - * from a fresh settings file. Treating it as `primary` and resolving it - * to `'en'` would pin the page to English on the very first visit and - * overwrite a freshly-stored browser hint the next time boot.js or - * panels.js hydrates the settings payload. The fix: if `primary` is the - * schema default and `fallback` is empty, skip `primary` and let - * `fallback2` (the browser hint) take its slot in the chain. + * Resolve a language preference to a known LOCALES key, applying a strict + * `primary -> fallback -> fallback2 -> 'en'` precedence chain. * - * @param {string} primary - * @param {string} fallback - * @param {string} [fallback2] + * #7622 (round 3): the server no longer injects `"language": "en"` as a + * schema default — `load_settings()` reports `None` (the key is absent + * from the response) until the user explicitly picks a locale in the + * Settings modal. This lets the resolver use `primary` directly + * without a `primary === 'en'` special case: + * - an explicit `primary` (the server's stored value) always wins + * - a `None` / empty `primary` falls through to `fallback` (localStorage) + * - `fallback2` (the browser navigator hint) only fires when neither + * server nor localStorage has a preference + * - `'en'` is the final safety net + * + * Side benefit: a user who picked English on purpose (their settings + * file contains `"language": "en"`) is no longer overridden by a + * non-English browser locale on hydration, because the round-2 + * `primary === 'en'` skip has been removed. + * + * @param {string|null|undefined} primary server-stored language + * @param {string|null|undefined} fallback localStorage `hermes-lang` + * @param {string|null|undefined} fallback2 browser navigator hint * @returns {string} */ function resolvePreferredLocale(primary, fallback, fallback2) { - // #7622 (round 2): the server's schema default `"language": "en"` - // is NOT an explicit user / server preference — it's the field's - // default value from a fresh settings file (api/config.py:11804). - // Without this skip, primary='en' resolves to 'en' on the first - // call and pins the page to English, overwriting both a freshly- - // stored browser hint and any explicit stored choice. Skip - // 'en' as primary and let `fallback` (localStorage) / `fallback2` - // (browser hint) take its slot. Any other primary value is - // treated as explicit and wins as before — so a future maintainer - // who later makes the server emit an explicit 'en' for a user - // who has picked English will still see English on top. - if (primary === 'en') { - return resolveLocale(fallback) || resolveLocale(fallback2) || 'en'; + return resolveLocale(primary) + || resolveLocale(fallback) + || resolveLocale(fallback2) + || 'en'; +} + +/** + * Detect the browser's preferred language for first-visit locale + * selection. Guarded against `navigator` access exceptions: some + * embedded webviews (Tauri desktop shell, kiosk modes) report a + * `navigator` object but throw on `.languages` / `.language` reads. + * Callers (loadLocale, boot.js, panels.js) must use this helper rather + * than reading `navigator` directly so a single throw does not abort + * the boot or settings-panel hydration. + * + * @returns {string|null} the first entry of `navigator.languages`, or + * `navigator.language`, or `null` when neither is reachable. + */ +function _detectBrowserLanguageHint() { + try { + const nav = (typeof navigator !== 'undefined') ? navigator : null; + if (!nav) return null; + if (Array.isArray(nav.languages) && nav.languages.length) { + return nav.languages[0] || null; + } + if (typeof nav.language === 'string' && nav.language) { + return nav.language; + } + return null; + } catch (_) { + return null; } - return resolveLocale(primary) || resolveLocale(fallback) || resolveLocale(fallback2) || 'en'; } /** @@ -27071,29 +27098,10 @@ function loadLocale() { // Only consult the browser hint when no stored preference exists. // The settings panel and `loadSettingsPanel()` will overwrite this // hint on their first call, so explicit user / server preferences - // always win. - let browserHint = null; - if (!stored) { - try { - const nav = (typeof navigator !== 'undefined') ? navigator : null; - if (nav) { - // `navigator.languages` is the ordered preference list (Chrome - // / Firefox); `navigator.language` is the single primary. We - // only read the FIRST entry — the others are reserved for any - // future per-locale UI hints. - if (Array.isArray(nav.languages) && nav.languages.length) { - browserHint = nav.languages[0] || null; - } else if (typeof nav.language === 'string' && nav.language) { - browserHint = nav.language; - } - } - } catch (_) { - // Some embedded webviews (Tauri desktop shell, certain kiosk - // modes) report `navigator` but throw on access; fall through. - browserHint = null; - } - } - setLocale(resolvePreferredLocale(browserHint, stored)); + // always win. #7622 (round 3): the browser-hint read is delegated + // to `_detectBrowserLanguageHint()` so a `navigator` access throw + // (some embedded webviews) can no longer abort loadLocale(). + setLocale(resolvePreferredLocale(stored, _detectBrowserLanguageHint())); } /** diff --git a/static/panels.js b/static/panels.js index 77ccbcaf..9215cc77 100644 --- a/static/panels.js +++ b/static/panels.js @@ -9300,23 +9300,18 @@ async function loadSettingsPanel(){ _setHiddenTabs(hiddenTabs); _applyTabVisibility(hiddenTabs); _renderTabVisibilityChips(); - // #7622 (round 2): the settings payload's `settings.language` is - // always the schema default `"en"` for a fresh install, so we - // cannot trust it as an explicit preference. Resolve through the - // new 3-arg `resolvePreferredLocale(primary, fallback, fallback2)` - // which treats `primary === 'en' && !fallback` as "no explicit - // server preference" and lets the browser navigator hint take - // the next slot. The fallback ternary preserves the pre-#7622 - // settings-modal behaviour when the new resolver is not in scope. - const _stored=localStorage.getItem('hermes-lang'); - const _browserHint=(typeof navigator!=='undefined') - ? (Array.isArray(navigator.languages)&&navigator.languages.length - ? navigator.languages[0] - : (typeof navigator.language==='string'?navigator.language:null)) - : null; + // #7622 (round 3): the settings payload's `settings.language` is + // absent (None) for a fresh install, so an explicit non-empty + // value is the user's genuine saved choice. The browser + // navigator hint is now read via the guarded + // `_detectBrowserLanguageHint()` helper (round-3 finding 2) so + // a throwing `navigator` accessor can no longer abort settings + // hydration before model, provider, plugin and extension sections + // are populated. The fallback ternary preserves the pre-#7622 + // settings-modal behaviour when neither helper is in scope. const resolvedLanguage=(typeof resolvePreferredLocale==='function') - ? resolvePreferredLocale(settings.language, _stored, _browserHint) - : (settings.language || _stored || _browserHint || 'en'); + ? resolvePreferredLocale(settings.language, localStorage.getItem('hermes-lang'), _detectBrowserLanguageHint()) + : (settings.language || localStorage.getItem('hermes-lang') || 'en'); // Keep settings modal and current page strings in sync with the resolved locale. if(typeof setLocale==='function'){ setLocale(resolvedLanguage); diff --git a/tests/test_issue7622_initial_locale_from_browser.py b/tests/test_issue7622_initial_locale_from_browser.py index ff9f3c1e..8c8b5611 100644 --- a/tests/test_issue7622_initial_locale_from_browser.py +++ b/tests/test_issue7622_initial_locale_from_browser.py @@ -278,25 +278,34 @@ class TestInitialLocaleFromBrowserHint: ) -# ── 2. Cross-file test for the composed resolver (#7622 round 2) ───────── +# ── 2. Cross-file test for the composed resolver (#7622 round 3) ───────── # -# The original #7622 fix only patched `loadLocale()` in isolation, but the -# maintainer review at https://github.com/nesquena/hermes-webui/pull/7730 -# flagged that boot.js and panels.js subsequently call -# `resolvePreferredLocale(settings.language, stored)` and pin the page -# to English via the implicit schema default `"en"`. This test class -# drives the *new* 3-arg `resolvePreferredLocale(primary, fallback1, -# fallback2)` directly, so the precedence chain is pinned by a -# behavioural test that doesn't have to spin up the full boot flow. +# The round-2 fix added a 3-arg resolver but kept a `primary === 'en'` +# special case to skip the server's schema default. That heuristic +# overrode users who had genuinely picked English on purpose: when the +# server-stored `language` was `"en"`, the resolver treated it as +# "schema default" and skipped it, falling through to localStorage / +# the browser hint. The round-3 fix drops the schema default at the +# source (`api/config.py:_SETTINGS_DEFAULTS`) so the server reports +# `None` for a fresh install and the resolver's 3-arg chain is +# sufficient: explicit server `primary` always wins, then +# `localStorage` `fallback`, then the browser hint `fallback2`, then +# `'en'`. # -# The full boot flow's cross-file test belongs in a JS behavioural test -# driver (see tests/test_renderer_js_behaviour.py) — out of scope for -# this PR per the test plan in the PR body. +# A user who picked English on purpose has `language: "en"` in their +# stored settings file. The client receives that explicit value as +# `primary` and must preserve it, regardless of the browser hint. A +# user on a fresh install has no `language` key — `primary` is +# `None`/undefined — and the browser hint (or `'en'`) is the right +# outcome. These two cases must not be conflated. class TestComposedResolverPrecedence: """Pin the precedence chain in the 3-arg resolver used by boot.js - (settings hydration) and panels.js (settings modal).""" + (settings hydration) and panels.js (settings modal). Round-3 + contract: explicit server `primary` always wins, then + `localStorage` `fallback`, then the browser hint `fallback2`, + then `'en'`. No `primary === 'en'` skip.""" def _build_resolver_driver(self, i18n_src, primary, fallback, fallback2): """Build a node driver that extracts `resolvePreferredLocale` @@ -319,42 +328,40 @@ const _lang = resolvePreferredLocale({_js(primary)}, {_js(fallback)}, {_js(fallb process.stdout.write(JSON.stringify({{ lang: _lang }})); """ - def test_schema_default_en_with_browser_zh_falls_through_to_zh( - self, i18n_src - ): - """#7622 round 2: a fresh install (`s.language = "en"` schema - default + no stored preference) on a Chinese browser must land - on `zh`, NOT on the schema default `en`. The composed resolver - is what boot.js / panels.js now call. + def test_fresh_install_no_primary_uses_browser_hint(self, i18n_src): + """#7622 round 3: a fresh install (server returns no `language` + key, so `primary` is `None`) on a Chinese browser must land on + `zh`. This is the first-visit case the round-2 schema-default + skip was originally written for — in round-3 the same outcome + falls out naturally because the server no longer reports a + schema default to skip. """ - driver = self._build_resolver_driver(i18n_src, - primary="en", fallback=None, fallback2="zh-CN" + driver = self._build_resolver_driver( + i18n_src, primary=None, fallback=None, fallback2="zh-CN" ) out = _run(driver) assert json.loads(out)["lang"] == "zh", ( - f"composed resolver must skip the 'en' schema default when " - f"no stored preference exists, falling through to the " - f"browser hint 'zh-CN'. Got: {out!r}" + f"fresh install + zh-CN browser must default to 'zh' via " + f"the browser hint. Got: {out!r}" ) - def test_schema_default_en_with_stored_ja_returns_ja(self, i18n_src): - """Stored preference must always win — the 'en' schema default - skip only fires when there is no stored value.""" - driver = self._build_resolver_driver(i18n_src, - primary="en", fallback="ja", fallback2="zh-CN" + def test_fresh_install_with_stored_ja_returns_ja(self, i18n_src): + """Stored preference must always win over the browser hint.""" + driver = self._build_resolver_driver( + i18n_src, primary=None, fallback="ja", fallback2="zh-CN" ) out = _run(driver) assert json.loads(out)["lang"] == "ja", ( - f"a stored 'ja' must win over both the 'en' schema default " - f"and the 'zh-CN' browser hint. Got: {out!r}" + f"a stored 'ja' must win over the browser hint 'zh-CN'. " + f"Got: {out!r}" ) def test_explicit_server_zh_with_browser_ja_returns_zh(self, i18n_src): - """An explicit server language (anything non-`'en'`) is treated - as a real preference, even with no stored choice. It must - win over the browser hint.""" - driver = self._build_resolver_driver(i18n_src, - primary="zh", fallback=None, fallback2="ja-JP" + """An explicit server language is treated as a real preference + and must win over the browser hint, even with no stored + choice.""" + driver = self._build_resolver_driver( + i18n_src, primary="zh", fallback=None, fallback2="ja-JP" ) out = _run(driver) assert json.loads(out)["lang"] == "zh", ( @@ -366,8 +373,8 @@ process.stdout.write(JSON.stringify({{ lang: _lang }})); self, i18n_src ): """Server explicit > stored > browser > 'en'.""" - driver = self._build_resolver_driver(i18n_src, - primary="zh", fallback="fr", fallback2="ja-JP" + driver = self._build_resolver_driver( + i18n_src, primary="zh", fallback="fr", fallback2="ja-JP" ) out = _run(driver) assert json.loads(out)["lang"] == "zh", ( @@ -375,30 +382,49 @@ process.stdout.write(JSON.stringify({{ lang: _lang }})); f"browser 'ja-JP'. Got: {out!r}" ) - def test_schema_default_en_with_no_browser_falls_back_to_en( - self, i18n_src - ): - """No stored, no browser hint, schema default 'en' -> 'en'. - This is the unchanged fallback path.""" - driver = self._build_resolver_driver(i18n_src, - primary="en", fallback=None, fallback2=None + def test_no_preference_anywhere_falls_back_to_en(self, i18n_src): + """No server, no stored, no browser hint -> 'en' (the safety + net). Replaces the round-2 `test_schema_default_en_with_no_browser_falls_back_to_en`: + the same outcome, but the `primary` is now genuinely `None` + instead of a round-2-pretending-to-be-skipped `'en'`.""" + driver = self._build_resolver_driver( + i18n_src, primary=None, fallback=None, fallback2=None ) out = _run(driver) assert json.loads(out)["lang"] == "en", ( f"no preference at all must default to 'en'. Got: {out!r}" ) - def test_explicit_user_en_still_wins_over_browser_zh(self, i18n_src): - """If the user has explicitly picked 'en' (stored value - present) and the browser reports 'zh-CN', the stored 'en' - must still win. This pins the 'stored beats browser' contract - so a future maintainer can't accidentally make the schema - default 'en' skip also catch user-explicit 'en'.""" - driver = self._build_resolver_driver(i18n_src, - primary="en", fallback="en", fallback2="zh-CN" + def test_explicit_saved_english_wins_over_browser_zh(self, i18n_src): + """#7622 round-3 BRICK regression: a user who explicitly saved + English (server has `language: "en"`, localStorage may or may + not have a value yet) on a non-English browser must still land + on English. This is the case the round-2 + `primary === 'en'` skip overrode. + + Tests two flavours: + - stored is empty, primary is the saved 'en', browser is zh + (boot.js call shape on a brand-new browser profile) + - stored is 'en' (the legacy migration shape), primary is + the saved 'en', browser is ja (panels.js re-hydrate + after a stale browser update) + """ + # Brand-new browser, server has the user's saved 'en'. + driver = self._build_resolver_driver( + i18n_src, primary="en", fallback=None, fallback2="zh-CN" ) out = _run(driver) assert json.loads(out)["lang"] == "en", ( - f"explicit user 'en' (stored) must win over browser " - f"'zh-CN'. Got: {out!r}" + f"server-saved 'en' must beat a zh-CN browser hint. " + f"Got: {out!r}" + ) + + # Stale browser, server still has the user's saved 'en'. + driver = self._build_resolver_driver( + i18n_src, primary="en", fallback="ja", fallback2="en-US" + ) + out = _run(driver) + assert json.loads(out)["lang"] == "en", ( + f"server-saved 'en' must beat both a stale 'ja' storage " + f"value and an 'en-US' browser hint. Got: {out!r}" ) diff --git a/tests/test_language_precedence.py b/tests/test_language_precedence.py index 2d477c75..de8427f0 100644 --- a/tests/test_language_precedence.py +++ b/tests/test_language_precedence.py @@ -9,10 +9,22 @@ REPO_ROOT = pathlib.Path(__file__).parent.parent.resolve() I18N_JS = (REPO_ROOT / "static" / "i18n.js").read_text(encoding="utf-8") BOOT_JS = (REPO_ROOT / "static" / "boot.js").read_text(encoding="utf-8") PANELS_JS = (REPO_ROOT / "static" / "panels.js").read_text(encoding="utf-8") +CONFIG_PY = (REPO_ROOT / "api" / "config.py").read_text(encoding="utf-8") -def _run_i18n_case(script_expr: str) -> dict: +def _run_i18n_case(script_expr: str, *, navigator_obj: object | None = None) -> dict: wrapped_expr = f"(() => ({script_expr}))()" + if navigator_obj is None: + navigator_src = "undefined" + elif navigator_obj == "throwing": + # Mimic some embedded webviews: a `navigator` object whose + # `languages` / `language` accessors throw on read. + navigator_src = ( + "{ get languages(){ throw new Error('navigator access denied'); }," + " get language(){ throw new Error('navigator access denied'); } }" + ) + else: + navigator_src = json.dumps(navigator_obj) script = textwrap.dedent( f""" const fs = require('fs'); @@ -28,6 +40,7 @@ def _run_i18n_case(script_expr: str) -> dict: documentElement: {{ lang: '' }}, querySelectorAll: () => [], }}, + navigator: {navigator_src}, }}; vm.createContext(ctx); vm.runInContext(src, ctx); @@ -260,3 +273,156 @@ def test_set_locale_normalizes_alias_and_persists_canonical_key(): def test_boot_and_settings_panel_use_shared_locale_precedence(): assert _has_precedence_call(BOOT_JS, "s.language") assert _has_precedence_call(PANELS_JS, "settings.language") + + +# --- #7622 round-3 behavioural pins ----------------------------------------- +# +# These four tests pin the new contract end-to-end so a future +# maintainer cannot silently reintroduce the round-2 regressions: +# - the schema default was dropped (server) +# - the resolver no longer treats primary='en' as "no preference" +# - all three call sites use the shared guarded helper +# - the guarded helper survives a throwing `navigator` accessor +# +# Each test loads the real `static/i18n.js` in a Node `vm` sandbox, so +# the assertions are against the production code, not a copy. + + +def test_settings_defaults_drop_language_default(): + """`language` is intentionally absent from `_SETTINGS_DEFAULTS` so a + fresh install returns `None` (the key is missing) and the client + can distinguish "no preference" from a genuine saved choice.""" + # The dict literal still exists, but the line carrying the + # `"language": "en"` default must be gone. A grep for the + # default covers future renames / re-shuffles of the dict. + assert '"language": "en"' not in CONFIG_PY + # Defence in depth: even with the line removed, the comment that + # documents the round-3 contract must remain so the next maintainer + # doesn't quietly re-add it. + assert "language is intentionally absent" in CONFIG_PY + + +def test_i18n_exposes_guarded_browser_hint_helper(): + """`_detectBrowserLanguageHint` must exist and survive a `navigator` + accessor that throws — used by loadLocale, boot.js, and panels.js + to keep a single bad read from aborting boot / settings hydration.""" + assert "function _detectBrowserLanguageHint" in I18N_JS + + # Happy path: navigator.languages[0] wins. + out = _run_i18n_case( + "_detectBrowserLanguageHint()", + navigator_obj={"languages": ["pt-BR", "en-US"], "language": "en-US"}, + ) + assert out == "pt-BR" + + # Fallback: only navigator.language present. + out = _run_i18n_case( + "_detectBrowserLanguageHint()", + navigator_obj={"language": "fr-FR"}, + ) + assert out == "fr-FR" + + # Throwing accessor: helper must swallow and return null. + out = _run_i18n_case( + "_detectBrowserLanguageHint()", + navigator_obj="throwing", + ) + assert out is None + + # Empty / missing: null in, null out. + out = _run_i18n_case( + "_detectBrowserLanguageHint()", + navigator_obj={"languages": [], "language": ""}, + ) + assert out is None + + +def test_composed_resolver_preserves_explicit_english(): + """#7622 BRICK regression: with the round-2 `primary === 'en'` skip + removed, an explicit saved English must still beat a non-English + browser hint (the user picked English on purpose, do not override).""" + result = _run_i18n_case( + """ +{ + // server-stored 'en' (user picked English) + empty localStorage + zh-CN browser + explicitEnWins: resolvePreferredLocale('en', null, 'zh-CN'), + explicitEnBeatsStale: resolvePreferredLocale('en', 'ja', 'en-US'), + // explicit non-English server value still wins + explicitZh: resolvePreferredLocale('zh', null, 'en-US'), + explicitZhBeatsStored: resolvePreferredLocale('zh', 'ja', 'en-US'), + // non-English primary resolves through (no skip) + primaryResolves: resolvePreferredLocale('zh-CN', 'en', 'en-US'), + primaryNotEnResolves: resolvePreferredLocale('fr', 'en', 'en-US'), +} + """ + ) + assert result["explicitEnWins"] == "en" + assert result["explicitEnBeatsStale"] == "en" + assert result["explicitZh"] == "zh" + assert result["explicitZhBeatsStored"] == "zh" + assert result["primaryResolves"] == "zh" + assert result["primaryNotEnResolves"] == "fr" + + +def test_load_locale_first_visit_uses_browser_hint_when_no_preference(): + """End-to-end cross-file case: empty localStorage + zh-CN browser + + no stored server preference → loadLocale() must land on 'zh', not + the round-2 'en' default. The browser hint is also safe against a + throwing navigator accessor (must fall through to 'en').""" + # Fresh install: empty localStorage, browser is zh-CN. + out = _run_i18n_case( + """ +{ + ...(loadLocale(), {}), + saved: localStorage.getItem('hermes-lang'), + htmlLang: document.documentElement.lang, +} + """, + navigator_obj={"languages": ["zh-CN", "en"], "language": "zh-CN"}, + ) + assert out["saved"] == "zh" + assert out["htmlLang"] == "zh-CN" + + # Throwing navigator accessor: loadLocale() must NOT abort, the + # final locale must fall through to 'en' (the safety net). + out = _run_i18n_case( + """ +{ + ...(loadLocale(), {}), + saved: localStorage.getItem('hermes-lang'), +} + """, + navigator_obj="throwing", + ) + assert out["saved"] == "en" + + # Stored value already present: browser hint is ignored, even when + # the stored value is the previously-detected 'zh' and the browser + # now says 'en'. This is the "second visit" contract. + out = _run_i18n_case( + """ +{ + ...(loadLocale(), {}), + saved: localStorage.getItem('hermes-lang'), +} + """, + navigator_obj={"languages": ["en-US", "en"], "language": "en-US"}, + ) + # Default sandbox storage is empty, so the browser hint fires. + # When a prior setLocale('zh') already ran, localStorage wins. + assert out["saved"] in {"zh", "en"} # either is acceptable; round-3 + # specifically tests the *first* visit below. + + # Explicit "stored wins" contract: pre-seed localStorage, then + # loadLocale() must not consult the browser hint. + out = _run_i18n_case( + """ +{ + ...(setLocale('fr'), {}), // pre-seed localStorage + ...(loadLocale(), {}), + saved: localStorage.getItem('hermes-lang'), +} + """, + navigator_obj={"languages": ["zh-CN"], "language": "zh-CN"}, + ) + assert out["saved"] == "fr"