@pithy-sh/i18n 0.12.0 → 0.14.0

package/src/react/useNegotiatedLocale.ts

@@ -3,11 +3,13 @@
 
 import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
 import { localeDirection } from "@pithy-sh/core/src/i18n/locale";
-import { useCallback, useEffect, useMemo, useState } from "react";
-import { applyDocumentLocale, readBrowserSignals, rememberBrowserLocale } from "../browser/signals";
+import { useRead } from "@pithy-sh/ui-core/src/read";
+import { useCallback, useMemo, useState } from "react";
 import { loadKitCatalog } from "../catalogs/browser";
 import type { I18nClientProjection } from "../client/projection";
 import { resolveBrowserLocale } from "../resolve/browser";
+import { browserLocaleEnvironment } from "./browserLocaleEnvironment";
+import type { LocaleEnvironment } from "./localeEnvironment";
 import type { TranslatorSource } from "./translator";
 
 /** What the hook hands back: what to mount, what was chosen, and how to choose again. */
@@ -20,8 +22,14 @@ export interface NegotiatedLocale {
   readonly source: TranslatorSource | null;
   /** The catalog locale in force — the words the app has. */
   readonly locale: string;
-  /** Choose a language. Remembers it on this device and puts `lang`/`dir` on the document. */
+  /** Choose a language. Remembers it on this device and applies it through the environment. */
   readonly choose: (locale: string) => void;
+  /**
+   * `true` when the locale in force lays out in the other direction from the one this launch started with, and the
+   * new direction takes effect only after the app reloads. React Native's rule; a browser never answers `true`. A
+   * screen says so rather than flip half a layout.
+   */
+  readonly reloadRequired: boolean;
 }
 
 /** What the caller knows that the browser cannot work out for itself. */
@@ -50,6 +58,12 @@ export interface NegotiatedLocaleOptions {
    * catch it here where you know what your API meant.
    */
   readonly persist?: (locale: string) => void | Promise<void>;
+  /**
+   * Where the starting signals come from, where a choice is remembered and how the locale is applied. The browser's
+   * by default; pass `nativeLocaleEnvironment` from `@pithy-sh/i18n/src/native/environment` on React Native. Keep it
+   * the same object for the life of the component.
+   */
+  readonly environment?: LocaleEnvironment;
 }
 
 /**
@@ -62,8 +76,8 @@ export interface NegotiatedLocaleOptions {
 const UNNEGOTIATED_LOCALE = "en";
 
 /**
- * Negotiate the reader's locale in the browser, load that locale's catalog, and keep the document in
- * step.
+ * Negotiate the reader's locale, load that locale's catalog, and keep the platform in step: the document in a
+ * browser, `I18nManager` on React Native, through `options.environment`.
  *
  * **It takes what a browser holds.** `projection` is `virtual:pithy/i18n` — locale metadata and nothing
  * else — so a screen reads the chain order **this project** configured rather than one the front end
@@ -91,24 +105,23 @@ export function useNegotiatedLocale(
   // and every hook below runs either way and answers for it rather than being skipped — a hook behind a
   // condition is the one thing React does not allow.
   const config = projection.enabled ? projection : null;
-  // The same fact as a boolean, and the two effects below depend on **this** rather than on `config`.
-  // Composed, `config` is `projection` under another name, so its identity is the caller's — and a
-  // caller is free to hand the hook a fresh object every render (`{ ...i18nConfig }`, or a parse in a
-  // component body). An effect keyed on that identity re-runs on every render; the catalog effect sets
-  // state, so it re-renders itself, forever, with no error anywhere to read. Both effects want nothing
-  // from `config` but whether it is there, and a boolean is stable by value however the caller spells
-  // its projection.
+  // The same fact as a boolean, which the catalog read and the document hook key on rather than `config`. A caller
+  // is free to hand the hook a fresh projection every render, and a boolean is stable by value however it is spelled.
   const enabled = projection.enabled;
+  const environment = options.environment ?? browserLocaleEnvironment;
 
+  const signals = environment.useSignals(config);
+  // A signal still being read, such as storage on React Native: nothing is negotiated, fetched or applied until it
+  // answers, so a remembered choice is not preceded by a flash of another language.
+  const pending = enabled && signals === undefined;
   const resolved = useMemo(
     () =>
-      config === null
+      config === null || signals === undefined
         ? null
-        : resolveBrowserLocale({ ...readBrowserSignals(config), account: options.account }, config),
-    [config, options.account],
+        : resolveBrowserLocale({ ...signals, account: options.account }, config),
+    [config, signals, options.account],
   );
   const [chosen, setChosen] = useState<string | null>(null);
-  const [kit, setKit] = useState<{ locale: string; catalog: MessageCatalog } | null>(null);
 
   const locale = chosen ?? resolved?.catalogLocale ?? UNNEGOTIATED_LOCALE;
   // A chosen locale is a catalog locale, so it carries no region; the negotiated one may be more
@@ -119,28 +132,18 @@ export function useNegotiatedLocale(
   // project without the capability could mean.
   const defaultLocale = config?.defaultLocale ?? UNNEGOTIATED_LOCALE;
 
-  useEffect(() => {
-    // No chunk is asked for at all with the capability uncomposed, and that is the whole of what keeps
-    // `source` null there: `kit` never arrives, so the memo below has nothing to mount and the caller
-    // renders through the same null it already renders through while a catalog is in flight.
-    if (!enabled) return;
-    let live = true;
-    loadKitCatalog(locale)
-      .then((catalog) => {
-        if (live) setKit({ locale, catalog });
-      })
-      // A per-locale chunk that will not load — a 404 after a deploy, an offline tab — must not leave
-      // the provider unmounted forever with `lang` already changed on the document. That is the
-      // "declares a language it does not speak" failure by another road: a screen reader believes the
-      // attribute and mispronounces English. An empty catalog mounts the provider, so every screen
-      // falls through to the English it was scaffolded with, which is what is actually on screen.
-      .catch(() => {
-        if (live) setKit({ locale, catalog: {} });
-      });
-    return () => {
-      live = false;
-    };
-  }, [enabled, locale]);
+  // No chunk is asked for with the capability uncomposed, which is what keeps `source` null there. A per-locale chunk
+  // that will not load — a 404 after a deploy, an offline tab — mounts an empty catalog rather than leaving the
+  // provider unmounted under a `lang` already changed on the document: every screen then falls through to the
+  // English it was scaffolded with, which is what is actually on screen.
+  const kit = useRead(
+    `catalog:${locale}`,
+    async (): Promise<{ locale: string; catalog: MessageCatalog }> => ({
+      locale,
+      catalog: await loadKitCatalog(locale).catch((): MessageCatalog => ({})),
+    }),
+    { skip: !enabled || pending },
+  ).value;
 
   // Derived from the locale in force, never taken off `resolved`. `resolveBrowserLocale` answers for
   // what the *chain* negotiated, and `choose` moves past it: a reader who picks Arabic from a language
@@ -150,13 +153,7 @@ export function useNegotiatedLocale(
   // byte-identical to what it answered before.
   const direction = localeDirection(locale);
 
-  useEffect(() => {
-    // Nothing negotiated it, so nothing declares it. A project without the capability keeps the `lang`
-    // its `index.html` shipped — restamping the document with a locale no chain chose would be the
-    // "declares a language it does not speak" failure with the negotiation removed rather than added.
-    if (!enabled) return;
-    applyDocumentLocale(locale, direction);
-  }, [enabled, locale, direction]);
+  const reloadRequired = environment.useApply(enabled && !pending, locale, direction);
 
   const persist = options.persist;
   const choose = useCallback(
@@ -164,9 +161,13 @@ export function useNegotiatedLocale(
       // No languages to choose between, and no `storageKey` to remember one under.
       if (config === null) return;
       if (!config.supportedLocales.includes(next)) return;
-      // The device first, always: it is synchronous, it cannot fail in a way worth waiting for, and it
-      // is what answers on the next visit if the account write does not land.
-      rememberBrowserLocale(next, config);
+      // The device first, always: it is what answers on the next visit if the account write does not land. Not
+      // awaited, and a failure costs only the memory of the choice, never the choice.
+      try {
+        Promise.resolve(environment.remember(next, config)).catch(() => undefined);
+      } catch {
+        // A store that throws before it answers. The reader still gets the language.
+      }
       setChosen(next);
       // Then the account, when the app knows who is reading. Not awaited — a language switch is a
       // render, not a round trip, and nothing on screen should wait for a preference.
@@ -178,13 +179,13 @@ export function useNegotiatedLocale(
       // reporting is a question about the adopter's own API, so it is answered inside `persist`.
       Promise.resolve(persist?.(next)).catch(() => undefined);
     },
-    [config, persist],
+    [config, persist, environment],
   );
 
   const source = useMemo<TranslatorSource | null>(() => {
     // Only once the catalog for *this* locale has landed. Mounting the previous locale's catalog under
     // the new locale's tag is a page that says it is Spanish and reads English. This is also the one
-    // test the uncomposed case has to pass: nothing ever loads a catalog there, so `kit` stays null
+    // test the uncomposed case has to pass: nothing ever loads a catalog there, so `kit` stays undefined
     // and no provider is ever mounted over screens already rendering their baked English.
     if (kit?.locale !== locale) return null;
     return {
@@ -194,5 +195,5 @@ export function useNegotiatedLocale(
     };
   }, [kit, locale, formattingLocale, options.messages, defaultLocale]);
 
-  return { source, locale, choose };
+  return { source, locale, choose, reloadRequired };
 }

package/src/resolve/browser.ts

@@ -88,7 +88,8 @@ export interface BrowserLocaleSignals {
 /**
  * The reader's locale, by the configured browser chain.
  *
- * Default order: `?lang=`, the account, local storage, the server's answer, the project default.
+ * Default order: `?lang=`, the account, local storage, the browser's own languages, the server's answer,
+ * the project default.
  *
  * **The account outranks the device.** `pithy_auth_users.locale` is where a person's locale lives, so a
  * signed-in reader who picks a language on one device must not silently be reading another language on

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/i18n";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.12.0";
+export const PACKAGE_VERSION = "0.14.0";