@orderly.network/i18n 3.0.0-beta.1 → 3.0.0-beta.10

package/dist/index.d.mts

@@ -1,54 +1,75 @@
-import { L as LocaleCode, R as Resources, a as LocaleContextState } from './constant-BeXwHrGj.mjs';
-export { b as Language, d as LocaleContext, f as LocaleEnum, e as LocaleMessages, P as PopupMode, c as PopupProps, g as defaultLanguages, h as defaultLng, i as defaultNS, l as en, k as i18nCookieKey, j as i18nLocalStorageKey, u as useLocaleContext } from './constant-BeXwHrGj.mjs';
+import { R as Resources, A as AsyncResources, L as LocaleCode, a as LanguageContextState } from './constant-BwPxVQ3H.mjs';
+export { b as Language, d as LanguageContext, f as LocaleEnum, e as LocaleMessages, P as PopupMode, c as PopupProps, g as defaultLanguages, h as defaultLng, i as defaultNS, l as en, k as i18nCookieKey, j as i18nLocalStorageKey, u as useLanguageContext } from './constant-BwPxVQ3H.mjs';
 import * as react_i18next from 'react-i18next';
-import { I18nextProviderProps, FallbackNs, UseTranslationOptions } from 'react-i18next';
+import { FallbackNs, UseTranslationOptions } from 'react-i18next';
 export * from 'react-i18next';
 import * as i18next from 'i18next';
 import { InitOptions, FlatNamespace, KeyPrefix } from 'i18next';
 export { createInstance, default as i18next } from 'i18next';
-import { ReactNode, PropsWithChildren, FC } from 'react';
+import { PropsWithChildren, FC } from 'react';
 import { $Tuple } from 'react-i18next/helpers';
 export { generatePath, getLocalePathFromPathname, parseI18nLang, removeLangPrefix } from './utils.mjs';
 
 declare function createI18nInstance(options?: InitOptions): i18next.i18n;
 declare const i18n: i18next.i18n;
 
+declare function registerResources(resources: Resources | AsyncResources | undefined, localeCode: LocaleCode): Promise<void>;
+
 type BackendOptions = {
     loadPath: (lang: LocaleCode, ns: string) => string | string[] | undefined;
 };
+declare class Backend {
+    options: BackendOptions;
+    cache: Set<string>;
+    constructor(options: BackendOptions);
+    fetchData(url: string): Promise<any>;
+    loadLanguage(lang: LocaleCode, ns: string): Promise<void>;
+}
 
-type I18nProviderProps = Partial<I18nextProviderProps>;
-declare const I18nProvider: React.FC<I18nProviderProps>;
-type LocaleProviderProps = {
-    children: ReactNode;
-    locale?: LocaleCode;
-    resource?: Record<string, string>;
-    resources?: Resources;
+/**
+ * Register the default language bundle before your React tree renders to reduce
+ * flicker of raw translation keys.
+ */
+declare const registerDefaultResource: (messages: Record<string, string>) => void;
+
+/**
+ * Shape of a locale JSON file loaded via dynamic import / Vite `import.meta.glob`.
+ */
+type LocaleJsonModule = {
+    default?: Record<string, string> | string | null;
+};
+declare function asMessageRecord(value: Record<string, string> | string | null | undefined): Record<string, string>;
+/**
+ * Loads a locale JSON module via a Vite `import.meta.glob` loader or a dynamic `import()` thunk,
+ * and normalizes `default` to a flat message record.
+ * Missing `loader`, rejected `loader()`, or missing/invalid `default` yields `{}` (see {@link asMessageRecord}).
+ */
+declare function importLocaleJsonModule(loader: (() => Promise<LocaleJsonModule>) | undefined): Promise<Record<string, string>>;
+
+type LanguageProviderProps = PropsWithChildren<{
+    backend?: BackendOptions;
     /**
      * supported languages, you can select supported languages from default languages
      */
     supportedLanguages?: LocaleCode[];
     /** optional conversion function to use to modify the detected language code */
     convertDetectedLanguage?: (lang: string) => LocaleCode;
-    backend?: BackendOptions;
-} & Partial<LocaleContextState>;
-declare const LocaleProvider: React.FC<LocaleProviderProps>;
+} & Partial<LanguageContextState>>;
+declare const LanguageProvider: FC<LanguageProviderProps>;
 
-declare function useTranslation<Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined, KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined>(ns?: Ns, options?: UseTranslationOptions<KPrefix>): react_i18next.UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
-
-declare function useLocaleCode(): LocaleCode;
-
-/**
- * preload default locale resources to prevent flickering of raw translation keys
- */
-declare const preloadDefaultResource: (messages: Record<string, string>) => void;
+type LocaleProviderProps = LanguageProviderProps & {
+    /** Active locale; when set and bundles exist, syncs i18n language via `changeLanguage`. */
+    locale?: LocaleCode;
+    /** Flat key-value messages for `defaultNS`; used together with `locale` when `resources` is not provided. */
+    resource?: Record<string, string>;
+    /**
+     * Preload locale bundles: static `Resources` map, or an async loader (same contract as
+     * `ExternalLocaleProvider`). When set, takes precedence over `locale` + `resource`.
+     */
+    resources?: Resources | AsyncResources;
+};
+declare const LocaleProvider: FC<LocaleProviderProps>;
 
-/**
- * Async loader contract for pulling translation resources from an external system.
- * Implementations are expected to return the full message table for the given locale
- * and namespace so that the bundle can be replaced atomically.
- */
-type AsyncResources = (lang: LocaleCode, ns: string) => Promise<Record<string, string>>;
 type ExternalLocaleProviderProps = PropsWithChildren<{
     resources?: Resources | AsyncResources;
 }>;
@@ -62,8 +83,31 @@ type ExternalLocaleProviderProps = PropsWithChildren<{
  *   synchronously on mount.
  *
  * This component renders no UI; it only manages i18n side effects and simply
- * returns its children.
+ * returns its children. Same behavior as calling `useRegisterExternalResources(resources)`
+ * in your own component under `LocaleProvider`.
  */
 declare const ExternalLocaleProvider: FC<ExternalLocaleProviderProps>;
 
-export { type AsyncResources, ExternalLocaleProvider, type ExternalLocaleProviderProps, I18nProvider, type I18nProviderProps, LocaleCode, LocaleContextState, LocaleProvider, type LocaleProviderProps, Resources, createI18nInstance, i18n, preloadDefaultResource, useLocaleCode, useTranslation };
+declare function useTranslation<Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined, KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined>(ns?: Ns, options?: UseTranslationOptions<KPrefix>): react_i18next.UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
+
+declare function useLocaleCode(): LocaleCode;
+
+/**
+ * Registers host-provided i18n resources into the shared i18n instance whenever
+ * the active locale or `resources` reference changes.
+ *
+ * - When `resources` is a function, it is invoked for the current locale to
+ *   load the bundle (e.g. from another bundle, backend, or runtime loader).
+ * - When `resources` is a static map, all provided locale bundles are registered.
+ *
+ * Prefer a stable `resources` reference (e.g. `useCallback` for loaders, module
+ * scope or `useMemo` for static maps) to avoid unnecessary re-registration.
+ */
+declare function useRegisterExternalResources(resources?: Resources | AsyncResources): void;
+
+/**
+ * preload default locale resources to prevent flickering of raw translation keys
+ */
+declare const preloadDefaultResource: (messages: Record<string, string>) => void;
+
+export { AsyncResources, Backend, type BackendOptions, ExternalLocaleProvider, type ExternalLocaleProviderProps, LanguageContextState, LanguageProvider, type LanguageProviderProps, LocaleCode, type LocaleJsonModule, LocaleProvider, type LocaleProviderProps, Resources, asMessageRecord, createI18nInstance, i18n, importLocaleJsonModule, preloadDefaultResource, registerDefaultResource, registerResources, useLocaleCode, useRegisterExternalResources, useTranslation };

package/dist/index.d.ts

@@ -1,54 +1,75 @@
-import { L as LocaleCode, R as Resources, a as LocaleContextState } from './constant-BeXwHrGj.js';
-export { b as Language, d as LocaleContext, f as LocaleEnum, e as LocaleMessages, P as PopupMode, c as PopupProps, g as defaultLanguages, h as defaultLng, i as defaultNS, l as en, k as i18nCookieKey, j as i18nLocalStorageKey, u as useLocaleContext } from './constant-BeXwHrGj.js';
+import { R as Resources, A as AsyncResources, L as LocaleCode, a as LanguageContextState } from './constant-BwPxVQ3H.js';
+export { b as Language, d as LanguageContext, f as LocaleEnum, e as LocaleMessages, P as PopupMode, c as PopupProps, g as defaultLanguages, h as defaultLng, i as defaultNS, l as en, k as i18nCookieKey, j as i18nLocalStorageKey, u as useLanguageContext } from './constant-BwPxVQ3H.js';
 import * as react_i18next from 'react-i18next';
-import { I18nextProviderProps, FallbackNs, UseTranslationOptions } from 'react-i18next';
+import { FallbackNs, UseTranslationOptions } from 'react-i18next';
 export * from 'react-i18next';
 import * as i18next from 'i18next';
 import { InitOptions, FlatNamespace, KeyPrefix } from 'i18next';
 export { createInstance, default as i18next } from 'i18next';
-import { ReactNode, PropsWithChildren, FC } from 'react';
+import { PropsWithChildren, FC } from 'react';
 import { $Tuple } from 'react-i18next/helpers';
 export { generatePath, getLocalePathFromPathname, parseI18nLang, removeLangPrefix } from './utils.js';
 
 declare function createI18nInstance(options?: InitOptions): i18next.i18n;
 declare const i18n: i18next.i18n;
 
+declare function registerResources(resources: Resources | AsyncResources | undefined, localeCode: LocaleCode): Promise<void>;
+
 type BackendOptions = {
     loadPath: (lang: LocaleCode, ns: string) => string | string[] | undefined;
 };
+declare class Backend {
+    options: BackendOptions;
+    cache: Set<string>;
+    constructor(options: BackendOptions);
+    fetchData(url: string): Promise<any>;
+    loadLanguage(lang: LocaleCode, ns: string): Promise<void>;
+}
 
-type I18nProviderProps = Partial<I18nextProviderProps>;
-declare const I18nProvider: React.FC<I18nProviderProps>;
-type LocaleProviderProps = {
-    children: ReactNode;
-    locale?: LocaleCode;
-    resource?: Record<string, string>;
-    resources?: Resources;
+/**
+ * Register the default language bundle before your React tree renders to reduce
+ * flicker of raw translation keys.
+ */
+declare const registerDefaultResource: (messages: Record<string, string>) => void;
+
+/**
+ * Shape of a locale JSON file loaded via dynamic import / Vite `import.meta.glob`.
+ */
+type LocaleJsonModule = {
+    default?: Record<string, string> | string | null;
+};
+declare function asMessageRecord(value: Record<string, string> | string | null | undefined): Record<string, string>;
+/**
+ * Loads a locale JSON module via a Vite `import.meta.glob` loader or a dynamic `import()` thunk,
+ * and normalizes `default` to a flat message record.
+ * Missing `loader`, rejected `loader()`, or missing/invalid `default` yields `{}` (see {@link asMessageRecord}).
+ */
+declare function importLocaleJsonModule(loader: (() => Promise<LocaleJsonModule>) | undefined): Promise<Record<string, string>>;
+
+type LanguageProviderProps = PropsWithChildren<{
+    backend?: BackendOptions;
     /**
      * supported languages, you can select supported languages from default languages
      */
     supportedLanguages?: LocaleCode[];
     /** optional conversion function to use to modify the detected language code */
     convertDetectedLanguage?: (lang: string) => LocaleCode;
-    backend?: BackendOptions;
-} & Partial<LocaleContextState>;
-declare const LocaleProvider: React.FC<LocaleProviderProps>;
+} & Partial<LanguageContextState>>;
+declare const LanguageProvider: FC<LanguageProviderProps>;
 
-declare function useTranslation<Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined, KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined>(ns?: Ns, options?: UseTranslationOptions<KPrefix>): react_i18next.UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
-
-declare function useLocaleCode(): LocaleCode;
-
-/**
- * preload default locale resources to prevent flickering of raw translation keys
- */
-declare const preloadDefaultResource: (messages: Record<string, string>) => void;
+type LocaleProviderProps = LanguageProviderProps & {
+    /** Active locale; when set and bundles exist, syncs i18n language via `changeLanguage`. */
+    locale?: LocaleCode;
+    /** Flat key-value messages for `defaultNS`; used together with `locale` when `resources` is not provided. */
+    resource?: Record<string, string>;
+    /**
+     * Preload locale bundles: static `Resources` map, or an async loader (same contract as
+     * `ExternalLocaleProvider`). When set, takes precedence over `locale` + `resource`.
+     */
+    resources?: Resources | AsyncResources;
+};
+declare const LocaleProvider: FC<LocaleProviderProps>;
 
-/**
- * Async loader contract for pulling translation resources from an external system.
- * Implementations are expected to return the full message table for the given locale
- * and namespace so that the bundle can be replaced atomically.
- */
-type AsyncResources = (lang: LocaleCode, ns: string) => Promise<Record<string, string>>;
 type ExternalLocaleProviderProps = PropsWithChildren<{
     resources?: Resources | AsyncResources;
 }>;
@@ -62,8 +83,31 @@ type ExternalLocaleProviderProps = PropsWithChildren<{
  *   synchronously on mount.
  *
  * This component renders no UI; it only manages i18n side effects and simply
- * returns its children.
+ * returns its children. Same behavior as calling `useRegisterExternalResources(resources)`
+ * in your own component under `LocaleProvider`.
  */
 declare const ExternalLocaleProvider: FC<ExternalLocaleProviderProps>;
 
-export { type AsyncResources, ExternalLocaleProvider, type ExternalLocaleProviderProps, I18nProvider, type I18nProviderProps, LocaleCode, LocaleContextState, LocaleProvider, type LocaleProviderProps, Resources, createI18nInstance, i18n, preloadDefaultResource, useLocaleCode, useTranslation };
+declare function useTranslation<Ns extends FlatNamespace | $Tuple<FlatNamespace> | undefined, KPrefix extends KeyPrefix<FallbackNs<Ns>> = undefined>(ns?: Ns, options?: UseTranslationOptions<KPrefix>): react_i18next.UseTranslationResponse<FallbackNs<Ns>, KPrefix>;
+
+declare function useLocaleCode(): LocaleCode;
+
+/**
+ * Registers host-provided i18n resources into the shared i18n instance whenever
+ * the active locale or `resources` reference changes.
+ *
+ * - When `resources` is a function, it is invoked for the current locale to
+ *   load the bundle (e.g. from another bundle, backend, or runtime loader).
+ * - When `resources` is a static map, all provided locale bundles are registered.
+ *
+ * Prefer a stable `resources` reference (e.g. `useCallback` for loaders, module
+ * scope or `useMemo` for static maps) to avoid unnecessary re-registration.
+ */
+declare function useRegisterExternalResources(resources?: Resources | AsyncResources): void;
+
+/**
+ * preload default locale resources to prevent flickering of raw translation keys
+ */
+declare const preloadDefaultResource: (messages: Record<string, string>) => void;
+
+export { AsyncResources, Backend, type BackendOptions, ExternalLocaleProvider, type ExternalLocaleProviderProps, LanguageContextState, LanguageProvider, type LanguageProviderProps, LocaleCode, type LocaleJsonModule, LocaleProvider, type LocaleProviderProps, Resources, asMessageRecord, createI18nInstance, i18n, importLocaleJsonModule, preloadDefaultResource, registerDefaultResource, registerResources, useLocaleCode, useRegisterExternalResources, useTranslation };