@burojs/i18n-core 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -1,21 +1,30 @@
-import { FallbackLng } from 'i18next';
-
+import { FallbackLng } from "i18next";
+//#region src/types/adapter.d.ts
 interface I18nAdapter {
-    t: (key: string, params?: Record<string, unknown>) => string;
-    changeLocale: (locale: string) => Promise<void>;
-    loadNamespace: (namespace: string, locale: string) => Promise<void>;
-    getCurrentLocale: () => string;
-    hasKey: (key: string) => boolean;
-    /**
-     * Subscribe to active-locale changes (fired by {@link I18nAdapter.changeLocale}).
-     * Returns an unsubscribe fn. Optional — adapters that cannot notify omit it,
-     * and the React layer then degrades to a non-reactive locale read. This is
-     * what powers the live language switch (no page reload): `useLocale()` wires
-     * it into `useSyncExternalStore`.
-     */
-    onLocaleChange?: (cb: () => void) => () => void;
+  t: (key: string, params?: Record<string, unknown>) => string;
+  changeLocale: (locale: string) => Promise<void>;
+  loadNamespace: (namespace: string, locale: string) => Promise<void>;
+  getCurrentLocale: () => string;
+  /**
+   * True when a USABLE STRING exists at `key` (an object node is not one).
+   * Pass `count` to ask about a count family (`<key>_one | _few | _many |
+   * _other`): i18next resolves the suffix only when it is asked with a count,
+   * so without one a present family reports missing.
+   */
+  hasKey: (key: string, options?: {
+    count?: number;
+  }) => boolean;
+  /**
+   * Subscribe to active-locale changes (fired by {@link I18nAdapter.changeLocale}).
+   * Returns an unsubscribe fn. Optional — adapters that cannot notify omit it,
+   * and the React layer then degrades to a non-reactive locale read. This is
+   * what powers the live language switch (no page reload): `useLocale()` wires
+   * it into `useSyncExternalStore`.
+   */
+  onLocaleChange?: (cb: () => void) => () => void;
 }
-
+//#endregion
+//#region src/types/bundle.d.ts
 /**
  * Recursive translation bundle: keys map to a string, a nested bundle, or an
  * ARRAY of either.
@@ -30,17 +39,18 @@ interface I18nAdapter {
  * the package that owns the type.
  */
 type TranslationBundle = {
-    [key: string]: string | TranslationBundle | readonly (string | TranslationBundle)[];
+  [key: string]: string | TranslationBundle | readonly (string | TranslationBundle)[];
 };
 /**
  * Per-resource bundle: optional async loader returning default-export bundle.
  */
 type ResourceBundle = (() => Promise<{
-    default: TranslationBundle;
+  default: TranslationBundle;
 }>) | Record<string, () => Promise<{
-    default: TranslationBundle;
+  default: TranslationBundle;
 }>>;
-
+//#endregion
+//#region src/types/i18n-keys.d.ts
 /**
  * Open interface for opt-in codegen-typed i18n keys.
  *
@@ -50,14 +60,13 @@ type ResourceBundle = (() => Promise<{
  *     }
  *   }
  */
-interface I18nKeys {
-}
+interface I18nKeys {}
 /**
  * Open interface for keys requiring interpolation parameters.
  */
-interface I18nKeysWithParams {
-}
-
+interface I18nKeysWithParams {}
+//#endregion
+//#region src/lookup.d.ts
 /**
  * Build candidate keys for fallback lookup.
  *
@@ -67,26 +76,27 @@ interface I18nKeysWithParams {
  *   3. common.<key>               — global common
  *   4. <key>                      — raw fallback (debug only)
  *
- * If `key` is already namespaced (starts with `resources.`, `enums.` or
- * `common.`), return it as-is without further scoping.
+ * If `key` is already namespaced (starts with `resources.`, `enums.`,
+ * `common.` or `blocks.`), return it as-is without further scoping.
  */
 declare function resolveKey(key: string, resource?: string): string[];
-
+//#endregion
+//#region src/i18next-adapter.d.ts
 interface I18nextAdapterConfig {
-    defaultLocale: string;
-    locales: string[];
-    resources?: Record<string, Record<string, TranslationBundle>>;
-    /**
-     * A single fallback locale (`'en'`) applies uniformly to every locale. A
-     * `fr → en` fallback for one locale but not another needs i18next's own
-     * per-locale chain shape instead — `{ fr: ['en'], default: ['en'] }` — so
-     * this accepts i18next's full `FallbackLng` type rather than just `string`.
-     * The chain is entirely CONFIG: nothing in this adapter special-cases any
-     * particular locale code, here or anywhere else.
-     */
-    fallbackLocale?: FallbackLng;
-    keySeparator?: string | false;
-    nsSeparator?: string | false;
+  defaultLocale: string;
+  locales: string[];
+  resources?: Record<string, Record<string, TranslationBundle>>;
+  /**
+   * A single fallback locale (`'en'`) applies uniformly to every locale. A
+   * `fr → en` fallback for one locale but not another needs i18next's own
+   * per-locale chain shape instead — `{ fr: ['en'], default: ['en'] }` — so
+   * this accepts i18next's full `FallbackLng` type rather than just `string`.
+   * The chain is entirely CONFIG: nothing in this adapter special-cases any
+   * particular locale code, here or anywhere else.
+   */
+  fallbackLocale?: FallbackLng;
+  keySeparator?: string | false;
+  nsSeparator?: string | false;
 }
 /**
  * Default I18nAdapter implementation backed by i18next.
@@ -94,47 +104,67 @@ interface I18nextAdapterConfig {
  * (e.g. 'common', 'resources').
  */
 declare function createI18nextAdapter(config: I18nextAdapterConfig): Promise<I18nAdapter>;
-
+//#endregion
+//#region src/i18n.d.ts
 interface I18nFacade {
-    t: (key: string, options?: {
-        resource?: string;
-        params?: Record<string, unknown>;
-    }) => string;
-    /**
-     * True when a translation for `key` EXISTS (through the same candidate chain
-     * as {@link I18nFacade.t}). Distinct from `t`, which returns the raw key on a
-     * miss — the content model probes presence with `has` to tell "no bundle
-     * entry" (render nothing) from "bundle entry === key text".
-     */
-    has: (key: string, options?: {
-        resource?: string;
-    }) => boolean;
-    changeLocale: (locale: string) => Promise<void>;
-    getCurrentLocale: () => string;
-    /**
-     * Subscribe to active-locale changes. Returns an unsubscribe fn. When the
-     * adapter can't notify, this is a no-op subscription (returns an unsubscribe
-     * that does nothing) — the live language switch then falls back to a static
-     * read. Consumed by `useLocale()` via `useSyncExternalStore`.
-     */
-    onLocaleChange: (cb: () => void) => () => void;
-    loadNamespace: (namespace: string, locale: string) => Promise<void>;
-    adapter: I18nAdapter;
+  /**
+   * Translate `key` through the candidate chain. `count` selects a count
+   * family's form (`<key>_one | _few | _many | _other`, by the locale's CLDR
+   * rules) and interpolates `{{count}}`; a family asked without a count is
+   * missing. A `count` inside `params` only interpolates.
+   */
+  t: (key: string, options?: {
+    resource?: string;
+    params?: Record<string, unknown>;
+    count?: number;
+  }) => string;
+  /**
+   * True when a translation for `key` EXISTS (through the same candidate chain
+   * as {@link I18nFacade.t}). Distinct from `t`, which returns the raw key on a
+   * miss — the content model probes presence with `has` to tell "no bundle
+   * entry" (render nothing) from "bundle entry === key text". Pass `count` to probe a count family.
+   */
+  has: (key: string, options?: {
+    resource?: string;
+    count?: number;
+  }) => boolean;
+  changeLocale: (locale: string) => Promise<void>;
+  getCurrentLocale: () => string;
+  /**
+   * Subscribe to active-locale changes. Returns an unsubscribe fn. When the
+   * adapter can't notify, this is a no-op subscription (returns an unsubscribe
+   * that does nothing) — the live language switch then falls back to a static
+   * read. Consumed by `useLocale()` via `useSyncExternalStore`.
+   */
+  onLocaleChange: (cb: () => void) => () => void;
+  loadNamespace: (namespace: string, locale: string) => Promise<void>;
+  /**
+   * The locale codes this app can switch to. Optional: a facade built without
+   * a list (a hand-rolled one, a test double) simply does not say, and a
+   * language control then offers only the active locale. `createI18nFromRegistry`
+   * fills it from the registry.
+   */
+  locales?: () => readonly string[];
+  adapter: I18nAdapter;
 }
 interface CreateI18nConfig {
-    adapter: I18nAdapter;
-    warnOnMissing?: boolean;
+  adapter: I18nAdapter;
+  warnOnMissing?: boolean;
+  /** The switchable locale codes, exposed as {@link I18nFacade.locales}. */
+  locales?: () => readonly string[];
 }
 declare function createI18n(config: CreateI18nConfig): I18nFacade;
-
+//#endregion
+//#region src/resource-context.d.ts
 interface ResourceI18n {
-    t: (key: string, options?: {
-        resource?: string;
-        params?: Record<string, unknown>;
-    }) => string;
-    changeLocale: (locale: string) => Promise<void>;
-    getCurrentLocale: () => string;
-    resource: string;
+  t: (key: string, options?: {
+    resource?: string;
+    params?: Record<string, unknown>;
+    count?: number;
+  }) => string;
+  changeLocale: (locale: string) => Promise<void>;
+  getCurrentLocale: () => string;
+  resource: string;
 }
 /**
  * Wraps an I18nFacade with a default resource scope.
@@ -142,7 +172,8 @@ interface ResourceI18n {
  * Pass an explicit `resource` option to override the default scope.
  */
 declare function createResourceI18n(i18n: I18nFacade, resource: string): ResourceI18n;
-
+//#endregion
+//#region src/locale-registry.d.ts
 /**
  * One package/app/domain module's offering for one locale.
  *
@@ -155,54 +186,79 @@ declare function createResourceI18n(i18n: I18nFacade, resource: string): Resourc
  * twenty-first `case`.
  */
 interface LocaleContribution {
-    /** Locale code this contribution provides strings for (e.g. 'en', 'es', 'fr'). */
-    locale: string;
-    /**
-     * i18next namespace the bundle merges into. Defaults to `'common'` — the
-     * same default namespace `createI18nextAdapter` uses.
-     */
-    namespace?: string;
-    /**
-     * Declared merge priority. On a key collision within the same
-     * (locale, namespace), the contribution with the HIGHER priority wins —
-     * not whichever happened to register last. Ties fall back to registration
-     * order (last registered wins), which is why two genuinely competing
-     * sources must declare distinct priorities rather than relying on the tie
-     * break.
-     */
-    priority: number;
-    /**
-     * Where this contribution came from — a package name, `'app'`, an enum
-     * module name. Diagnostic only (surfaced by {@link LocaleRegistry.contributions}
-     * for debugging a collision); never branched on.
-     */
-    source: string;
-    bundle: TranslationBundle;
+  /** Locale code this contribution provides strings for (e.g. 'en', 'es', 'fr'). */
+  locale: string;
+  /**
+   * i18next namespace the bundle merges into. Defaults to `'common'` — the
+   * same default namespace `createI18nextAdapter` uses.
+   */
+  namespace?: string;
+  /**
+   * Declared merge priority. On a key collision within the same
+   * (locale, namespace), the contribution with the HIGHER priority wins —
+   * not whichever happened to register last. Ties fall back to registration
+   * order (last registered wins), which is why two genuinely competing
+   * sources must declare distinct priorities rather than relying on the tie
+   * break.
+   */
+  priority: number;
+  /**
+   * Where this contribution came from — a package name, `'app'`, an enum
+   * module name. Diagnostic only (surfaced by {@link LocaleRegistry.contributions}
+   * for debugging a collision); never branched on.
+   */
+  source: string;
+  bundle: TranslationBundle;
 }
 interface LocaleRegistry {
-    /** Add one contribution. Order of registration does not matter for the merge result — only `priority` does (see {@link LocaleContribution.priority}). */
-    register(contribution: LocaleContribution): void;
-    /**
-     * Every locale code that has at least one contribution, sorted. Derived
-     * purely from what was registered — nothing enumerates or counts locales
-     * anywhere else in this module.
-     */
-    locales(): string[];
-    /** Every namespace that has at least one contribution, sorted. */
-    namespaces(): string[];
-    /** All registered contributions, in registration order. For diagnostics/tests. */
-    contributions(): readonly LocaleContribution[];
-    /**
-     * Assemble `{ [locale]: { [namespace]: TranslationBundle } }`, ready to
-     * pass straight as `createI18nextAdapter`'s `resources` config. Within one
-     * (locale, namespace) group, contributions are deep-merged in ascending
-     * priority order, so a higher-priority contribution's leaves win over a
-     * lower-priority one's on any overlapping key while leaving the rest of
-     * the lower-priority bundle intact.
-     */
-    buildResources(): Record<string, Record<string, TranslationBundle>>;
+  /**
+   * The primary locale, as declared to {@link createLocaleRegistry}: the one
+   * whose text is the default in code, and the locale every other one falls
+   * back to. The single source of truth for it — `createI18nFromRegistry`
+   * defaults both the starting locale and the fallback to it, and
+   * `@burojs/testing`'s `checkApp` reads it to know which locale is exempt
+   * from `i18n.missing`. Never derived from contributions or their order.
+   */
+  primary(): string;
+  /** Add one contribution. Order of registration does not matter for the merge result — only `priority` does (see {@link LocaleContribution.priority}). */
+  register(contribution: LocaleContribution): void;
+  /**
+   * Every locale code that has at least one contribution, sorted. Derived
+   * purely from what was registered — nothing enumerates or counts locales
+   * anywhere else in this module.
+   */
+  locales(): string[];
+  /** Every namespace that has at least one contribution, sorted. */
+  namespaces(): string[];
+  /** All registered contributions, in registration order. For diagnostics/tests. */
+  contributions(): readonly LocaleContribution[];
+  /**
+   * Assemble `{ [locale]: { [namespace]: TranslationBundle } }`, ready to
+   * pass straight as `createI18nextAdapter`'s `resources` config. Within one
+   * (locale, namespace) group, contributions are deep-merged in ascending
+   * priority order, so a higher-priority contribution's leaves win over a
+   * lower-priority one's on any overlapping key while leaving the rest of
+   * the lower-priority bundle intact.
+   *
+   * Throws when no contribution is registered for {@link primary}: a
+   * fallback chain that ends at a locale with no bundle, and a primary that
+   * `locales()` (and so every language switcher built from it) does not
+   * list, is a misconfiguration (usually a typo, `'en-US'` for `'en'`, or a
+   * glob that missed its file), not a state to render. An app that really
+   * has no strings for its primary locale registers an empty bundle for it.
+   */
+  buildResources(): Record<string, Record<string, TranslationBundle>>;
 }
-declare function createLocaleRegistry(): LocaleRegistry;
+interface LocaleRegistryOptions {
+  /**
+   * The primary locale: the one whose text is the default in code. Required,
+   * and declared here rather than inferred, because nothing in the
+   * contributions says which locale it is — registration order and the
+   * sorted `locales()` both carry no meaning.
+   */
+  primary: string;
+}
+declare function createLocaleRegistry(options: LocaleRegistryOptions): LocaleRegistry;
 /**
  * A bundler-produced glob module, as `import.meta.glob` (Vite) or an
  * equivalent walk over `require.context` (webpack) would yield it: a flat
@@ -214,24 +270,24 @@ declare function createLocaleRegistry(): LocaleRegistry;
  * whatever their bundler offers) and hands the plain object here.
  */
 type LocaleGlobModule = TranslationBundle | {
-    default: TranslationBundle;
+  default: TranslationBundle;
 };
 interface LocaleContributionsFromGlobOptions {
-    /** {@link LocaleContribution.source} for every contribution produced. */
-    source: string;
-    /** {@link LocaleContribution.priority} for every contribution produced. */
-    priority: number;
-    /** {@link LocaleContribution.namespace}. Defaults to `'common'`. */
-    namespace?: string;
-    /**
-     * Extracts the locale code from a glob path. Default matches a bare
-     * `<locale>.ts`/`<locale>.tsx`/`<locale>.js` filename (`'./locales/en.ts'`
-     * → `'en'`, `'./locales/fr-CA.ts'` → `'fr-CA'`) — no restriction to a
-     * known set of codes; whatever the filename says IS the locale code. Paths
-     * that don't match are skipped rather than guessed at (same discipline as
-     * `docsFromGlob`).
-     */
-    localeOf?: (path: string) => string | undefined;
+  /** {@link LocaleContribution.source} for every contribution produced. */
+  source: string;
+  /** {@link LocaleContribution.priority} for every contribution produced. */
+  priority: number;
+  /** {@link LocaleContribution.namespace}. Defaults to `'common'`. */
+  namespace?: string;
+  /**
+   * Extracts the locale code from a glob path. Default matches a bare
+   * `<locale>.ts`/`<locale>.tsx`/`<locale>.js` filename (`'./locales/en.ts'`
+   * → `'en'`, `'./locales/fr-CA.ts'` → `'fr-CA'`) — no restriction to a
+   * known set of codes; whatever the filename says IS the locale code. Paths
+   * that don't match are skipped rather than guessed at (same discipline as
+   * `docsFromGlob`).
+   */
+  localeOf?: (path: string) => string | undefined;
 }
 /**
  * Normalize a bundler glob of per-locale files into {@link LocaleContribution}s.
@@ -241,21 +297,30 @@ interface LocaleContributionsFromGlobOptions {
  * mechanism for adding a language.
  */
 declare function localeContributionsFromGlob(glob: Record<string, LocaleGlobModule>, options: LocaleContributionsFromGlobOptions): LocaleContribution[];
-
-type CreateI18nFromRegistryConfig = Pick<I18nextAdapterConfig, 'defaultLocale' | 'fallbackLocale' | 'keySeparator' | 'nsSeparator'> & {
-    warnOnMissing?: boolean;
+//#endregion
+//#region src/create-i18n-from-registry.d.ts
+type CreateI18nFromRegistryConfig = Partial<Pick<I18nextAdapterConfig, 'defaultLocale' | 'fallbackLocale' | 'keySeparator' | 'nsSeparator'>> & {
+  warnOnMissing?: boolean;
 };
 /**
  * Wires a {@link LocaleRegistry} straight into `createI18nextAdapter` +
  * `createI18n`: `registry.locales()` becomes the adapter's `locales`,
- * `registry.buildResources()` becomes its `resources`. This is the ONLY
- * place those two need to be threaded together — an app that builds its own
- * registry never re-lists its locale codes to hand them to the adapter, it
- * just calls this.
+ * `registry.buildResources()` becomes its `resources`, and
+ * `registry.primary()` is both the starting locale and the fallback unless
+ * `defaultLocale` (the starting locale, say a stored choice) or
+ * `fallbackLocale` (say a per-locale chain) overrides it. This is the ONLY
+ * place those need to be threaded together — an app that builds its own
+ * registry never re-lists its locale codes, or restates its primary locale,
+ * to hand them to the adapter; it just calls this.
+ *
+ * Throws when the registry's primary locale has no contribution (see
+ * {@link LocaleRegistry.buildResources}).
  */
-declare function createI18nFromRegistry(registry: LocaleRegistry, config: CreateI18nFromRegistryConfig): Promise<I18nFacade>;
-
+declare function createI18nFromRegistry(registry: LocaleRegistry, config?: CreateI18nFromRegistryConfig): Promise<I18nFacade>;
+//#endregion
+//#region src/index.d.ts
 declare const PACKAGE_NAME: "@burojs/i18n-core";
 declare const PACKAGE_VERSION: "0.0.0";
-
-export { type CreateI18nConfig, type CreateI18nFromRegistryConfig, type I18nAdapter, type I18nFacade, type I18nKeys, type I18nKeysWithParams, type I18nextAdapterConfig, type LocaleContribution, type LocaleContributionsFromGlobOptions, type LocaleGlobModule, type LocaleRegistry, PACKAGE_NAME, PACKAGE_VERSION, type ResourceBundle, type ResourceI18n, type TranslationBundle, createI18n, createI18nFromRegistry, createI18nextAdapter, createLocaleRegistry, createResourceI18n, localeContributionsFromGlob, resolveKey };
+//#endregion
+export { type CreateI18nConfig, type CreateI18nFromRegistryConfig, type I18nAdapter, type I18nFacade, type I18nKeys, type I18nKeysWithParams, type I18nextAdapterConfig, type LocaleContribution, type LocaleContributionsFromGlobOptions, type LocaleGlobModule, type LocaleRegistry, type LocaleRegistryOptions, PACKAGE_NAME, PACKAGE_VERSION, type ResourceBundle, type ResourceI18n, type TranslationBundle, createI18n, createI18nFromRegistry, createI18nextAdapter, createLocaleRegistry, createResourceI18n, localeContributionsFromGlob, resolveKey };
+//# sourceMappingURL=index.d.ts.map