@siteping/widget 0.11.0 → 0.12.0

package/dist/i18n.d.ts

@@ -12,7 +12,7 @@
  * dictionary file) exists. Adding a locale cannot silently fall back to
  * English anymore.
  */
-import { type BuiltinLocale } from "./types.js";
+import type { BuiltinLocale } from "./types.js";
 /**
  * Lazy dictionary loaders for every non-English built-in locale. Use static
  * `() => import("./xx.js").then((m) => m.xx)` thunks — bundlers keep
@@ -26,7 +26,8 @@ export interface I18n<T> {
     /**
      * Create a translation function for the given locale.
      *
-     * Locale resolution: exact language match > English fallback, per key.
+     * Locale resolution, per key: `registerLocale` override > built-in
+     * dictionary of the language > English fallback.
      * Non-English built-in locales are lazy-loaded via `loadLocale` — call
      * `await loadLocale(locale)` at init if you want the UI to render in the
      * target language immediately; until the dictionary lands, keys resolve
@@ -34,17 +35,20 @@ export interface I18n<T> {
      */
     createT(locale: string): TranslateFunction<T>;
     /**
-     * Dynamically import a built-in locale and register it. Returns the
-     * loaded dictionary, or `null` if the locale isn't a known built-in.
-     * Custom locales registered via `registerLocale` bypass this loader —
-     * they are already in the registry (and are returned as registered, so a
-     * partial custom dictionary comes back partial).
+     * Dynamically import a built-in locale (once) and register it. Returns the
+     * locale as `createT` resolves it — the built-in dictionary with any
+     * `registerLocale` overrides on top — or `null` for a code that is neither
+     * built in nor registered. A custom code never hits a loader: it comes
+     * back as registered, so a partial custom dictionary comes back partial.
      */
     loadLocale(locale: string): Promise<Partial<T> | null>;
     /**
-     * Register a custom locale at runtime. Partial dictionaries are welcome —
-     * missing keys fall back to English per key, so overriding a single
-     * string never requires copying the whole catalog.
+     * Register translations at runtime, for a new locale or over a built-in
+     * one. Partial dictionaries are welcome: the keys given override the
+     * built-in dictionary (whenever it loads), every other key keeps its
+     * built-in value, then falls back to English — so overriding a single
+     * string never requires copying the whole catalog. Calls for the same
+     * code accumulate.
      */
     registerLocale(code: string, translations: Partial<T>): void;
 }