bug: a Traditional Chinese browser (zh-TW, zh-HK, zh-MO) opens the panel in Traditional Chinese, not Simplified (#971)

Author: lukepolo

nuxt.config.ts

@@ -159,12 +159,7 @@ export default defineNuxtConfig({
     bundle: {
       optimizeTranslationDirective: false,
     },
-    detectBrowserLanguage: {
-      useCookie: true,
-      cookieKey: "i18n_redirected",
-      redirectOn: "root",
-      fallbackLocale: "en",
-    },
+    detectBrowserLanguage: false,
     locales: [
       { code: "en", name: "English", file: "en.json", flag: "🇬🇧" },
       { code: "ar", name: "العربية", file: "ar_SA.json", flag: "🇸🇦" }, // Arabic

pages/settings/index.vue

@@ -17,6 +17,7 @@ import {
 } from "@/components/ui/popover";
 import { useI18n } from "vue-i18n";
 import PageTransition from "~/components/ui/transitions/PageTransition.vue";
+import { savePickedLocale } from "~/utilities/locale";
 const { locale, locales, setLocale } = useI18n();
 
 const availableLocales = computed(() => {
@@ -45,6 +46,7 @@ const handleLocaleChange = (
     | "pt-BR"
     | "zh",
 ) => {
+  savePickedLocale(newLocale);
   setLocale(newLocale);
 };
 </script>

plugins/locale.client.ts

@@ -0,0 +1,31 @@
+import {
+  LEGACY_LOCALE_COOKIE,
+  legacyPickedLocale,
+  readPickedLocale,
+  resolveLocale,
+  savePickedLocale,
+} from "~/utilities/locale";
+
+export default defineNuxtPlugin(async () => {
+  const i18n = useNuxtApp().$i18n;
+
+  const legacy = useCookie<string | null>(LEGACY_LOCALE_COOKIE);
+  if (legacy.value) {
+    const picked = legacyPickedLocale(
+      legacy.value,
+      i18n.getBrowserLocale() || "en",
+    );
+    if (picked && !readPickedLocale()) {
+      savePickedLocale(picked);
+    }
+    legacy.value = null;
+  }
+
+  await i18n.setLocale(
+    resolveLocale(
+      i18n.localeCodes.value,
+      navigator.languages,
+      readPickedLocale(),
+    ) as typeof i18n.locale.value,
+  );
+});

tests/plugins/locale.spec.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import localePlugin from "~/plugins/locale.client";
+import {
+  resetBrowserLanguages,
+  setBrowserLanguages,
+} from "../helpers/browserLocale";
+
+const PICKED_LOCALE_KEY = "5stack:locale";
+
+const app = () =>
+  useNuxtApp() as unknown as {
+    $i18n: {
+      locale: { value: string };
+      setLocale: (code: string) => Promise<void>;
+    };
+    _vueI18n: { __firstAccess: boolean };
+  };
+
+const locale = () => app().$i18n.locale.value;
+
+async function boot() {
+  app()._vueI18n.__firstAccess = true;
+  await (localePlugin as unknown as () => Promise<void>)();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+}
+
+beforeEach(() => {
+  localStorage.clear();
+  document.cookie = "i18n_redirected=; max-age=0; path=/";
+});
+
+afterEach(async () => {
+  resetBrowserLanguages();
+  localStorage.clear();
+  document.cookie = "i18n_redirected=; max-age=0; path=/";
+  await app().$i18n.setLocale("en");
+});
+
+describe("the language a visitor first sees", () => {
+  it("is Traditional Chinese for a zh-TW browser, and stays that way across pages", async () => {
+    setBrowserLanguages(["zh-TW", "zh", "en-US"]);
+
+    await boot();
+    expect(locale()).toBe("zh-Hant");
+
+    await useRouter().push("/faq");
+    await useRouter().push("/");
+    expect(locale()).toBe("zh-Hant");
+  });
+
+  it("is the visitor's own pick over their browser", async () => {
+    setBrowserLanguages(["zh-TW"]);
+    localStorage.setItem(PICKED_LOCALE_KEY, "ja");
+
+    await boot();
+
+    expect(locale()).toBe("ja");
+  });
+
+  it("is not written to a cookie for the next visit", async () => {
+    setBrowserLanguages(["de-DE"]);
+
+    await boot();
+    await useRouter().push("/faq");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(document.cookie).not.toContain("i18n_redirected");
+  });
+});
+
+describe("the old i18n_redirected cookie", () => {
+  it("no longer holds a zh-TW browser on Simplified Chinese", async () => {
+    setBrowserLanguages(["zh-TW"]);
+    document.cookie = "i18n_redirected=zh-Hans; path=/";
+
+    await boot();
+
+    expect(locale()).toBe("zh-Hant");
+    expect(localStorage.getItem(PICKED_LOCALE_KEY)).toBeNull();
+    expect(document.cookie).not.toContain("i18n_redirected");
+  });
+
+  it("carries over a language the visitor picked", async () => {
+    setBrowserLanguages(["en-US"]);
+    document.cookie = "i18n_redirected=de; path=/";
+
+    await boot();
+
+    expect(locale()).toBe("de");
+    expect(localStorage.getItem(PICKED_LOCALE_KEY)).toBe("de");
+    expect(document.cookie).not.toContain("i18n_redirected");
+  });
+});

tests/utilities/locale.spec.ts

@@ -0,0 +1,85 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  legacyPickedLocale,
+  matchBrowserLocale,
+  resolveLocale,
+} from "~/utilities/locale";
+import {
+  resetBrowserLanguages,
+  setBrowserLanguages,
+} from "../helpers/browserLocale";
+
+const i18n = () =>
+  useNuxtApp().$i18n as unknown as {
+    localeCodes: { value: string[] };
+    getBrowserLocale: () => string | undefined;
+  };
+
+const codes = () => i18n().localeCodes.value;
+
+afterEach(resetBrowserLanguages);
+
+describe("the language a browser is shown", () => {
+  it.each([
+    ["zh-TW", "zh-Hant"],
+    ["zh-HK", "zh-Hant"],
+    ["zh-MO", "zh-Hant"],
+    ["zh-Hant-TW", "zh-Hant"],
+    ["zh-CN", "zh-Hans"],
+    ["zh-SG", "zh-Hans"],
+    ["zh", "zh-Hans"],
+    ["pt-BR", "pt"],
+    ["pt-PT", "pt"],
+    ["en-US", "en"],
+    ["de", "de"],
+  ])("%s gets %s", (tag, expected) => {
+    expect(matchBrowserLocale([tag], codes())).toBe(expected);
+  });
+
+  it("takes the first language the browser lists that we have", () => {
+    expect(matchBrowserLocale(["nl-NL", "zh-TW", "en-US"], codes())).toBe(
+      "zh-Hant",
+    );
+  });
+
+  it("falls back to English when we have none of them", () => {
+    expect(resolveLocale(codes(), ["nl-NL", "fi"], null)).toBe("en");
+  });
+
+  it("skips a tag the browser mangled", () => {
+    expect(matchBrowserLocale(["en_US!", "de-DE"], codes())).toBe("de");
+  });
+});
+
+describe("a visitor's own pick", () => {
+  it("wins over the browser", () => {
+    expect(resolveLocale(codes(), ["zh-TW"], "ja")).toBe("ja");
+  });
+
+  it("is ignored when it names a language we no longer have", () => {
+    expect(resolveLocale(codes(), ["zh-TW"], "lv")).toBe("zh-Hant");
+  });
+});
+
+describe("the old i18n_redirected cookie", () => {
+  it("is not a pick when it holds the guess the old detection made", () => {
+    setBrowserLanguages(["zh-TW"]);
+    const oldGuess = i18n().getBrowserLocale() || "en";
+
+    expect(legacyPickedLocale("zh-Hans", oldGuess)).toBeNull();
+  });
+
+  it("is a pick when it differs from that guess", () => {
+    setBrowserLanguages(["en-US"]);
+    const oldGuess = i18n().getBrowserLocale() || "en";
+
+    expect(legacyPickedLocale("de", oldGuess)).toBe("de");
+  });
+
+  it("is not a pick when it holds the English fallback", () => {
+    setBrowserLanguages(["nl-NL"]);
+    const oldGuess = i18n().getBrowserLocale() || "en";
+
+    expect(legacyPickedLocale("en", oldGuess)).toBeNull();
+  });
+});

utilities/locale.ts

@@ -0,0 +1,66 @@
+const PICKED_LOCALE_KEY = "5stack:locale";
+
+export const LEGACY_LOCALE_COOKIE = "i18n_redirected";
+
+export function readPickedLocale(): string | null {
+  try {
+    return localStorage.getItem(PICKED_LOCALE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+export function savePickedLocale(code: string) {
+  try {
+    localStorage.setItem(PICKED_LOCALE_KEY, code);
+  } catch {}
+}
+
+function findCode(codes: readonly string[], tag: string) {
+  return codes.find((code) => code.toLowerCase() === tag.toLowerCase());
+}
+
+// Browsers send a region (zh-TW, zh-HK), never the script our Chinese locales
+// are named by; maximize() supplies the script that region writes in.
+export function matchBrowserLocale(
+  browserTags: readonly string[],
+  codes: readonly string[],
+): string | undefined {
+  for (const tag of browserTags) {
+    let locale: Intl.Locale;
+    try {
+      locale = new Intl.Locale(tag).maximize();
+    } catch {
+      continue;
+    }
+
+    const code =
+      findCode(codes, tag) ??
+      findCode(codes, `${locale.language}-${locale.script}`) ??
+      findCode(codes, locale.language);
+    if (code) {
+      return code;
+    }
+  }
+}
+
+export function resolveLocale(
+  codes: readonly string[],
+  browserTags: readonly string[],
+  picked: string | null,
+): string {
+  if (picked && codes.includes(picked)) {
+    return picked;
+  }
+  return matchBrowserLocale(browserTags, codes) ?? "en";
+}
+
+// The old cookie was written on every first visit, so it holds the browser
+// guess as often as a real pick. Only a value that guess wouldn't have made is
+// known to be the visitor's own choice.
+export function legacyPickedLocale(
+  cookie: string | null | undefined,
+  oldGuess: string,
+): string | null {
+  return cookie && cookie !== oldGuess ? cookie : null;
+}