@nice2dev/i18n 1.1.7 → 1.1.10

package/dist/index.d.ts

@@ -400,6 +400,9 @@ export declare function getJapaneseEra(date: Date): JapaneseEra | null;
  */
 export declare function getJapaneseYear(date: Date): number | null;
 
+/** The dictionary of `lang` if it has been loaded already, otherwise `undefined`. */
+export declare function getLoadedNiceDictionary(lang: NiceSupportedLang): NiceDictionary | undefined;
+
 /**
  * Get the BCP 47 locale tag for a NiceSupportedLang code.
  */
@@ -601,6 +604,19 @@ export declare interface LoaderState {
     currentLanguage: NiceSupportedLang;
 }
 
+/**
+ * Load one language's built-in dictionary. Cached, and concurrent calls share one request.
+ * Await it before the first render to start in that language instead of in English:
+ *
+ * ```ts
+ * await loadNiceDictionary('pl');
+ * root.render(<NiceI18nLazyProvider lang="pl"><App /></NiceI18nLazyProvider>);
+ * ```
+ *
+ * An unknown code loads English, as `NiceI18nProvider` falls back to it.
+ */
+export declare function loadNiceDictionary(lang: NiceSupportedLang): Promise<NiceDictionary>;
+
 /**
  * Look up a term in the glossary for a given language.
  * Returns the approved translation or undefined.
@@ -622,6 +638,13 @@ export declare const NICE_I18N_DICTIONARIES: Record<NiceSupportedLang, Record<st
  */
 export declare const NICE_I18N_VARIANTS: Partial<Record<string, Partial<Record<NiceI18nVariant, Record<string, string>>>>>;
 
+/**
+ * The languages with a built-in dictionary.
+ *
+ * Its own module, free of dictionary imports: the context, `useNiceTranslation` and the
+ * lazy provider need the list but must not pull thirty dictionaries in with it.
+ * `i18nDictionaries.ts` re-exports both names, so existing imports keep working.
+ */
 export declare const NICE_SUPPORTED_LANGS: readonly ["en", "pl", "de", "fr", "es", "it", "pt", "nl", "sv", "no", "da", "fi", "cs", "sk", "hu", "ro", "bg", "uk", "ja", "ko", "zh", "ar", "hi", "bn", "th", "vi", "id", "sw", "fil", "ms"];
 
 export declare interface NiceCurrencyFormatter {
@@ -634,6 +657,41 @@ export declare interface NiceDateFormatter {
     formatRelative: (date: Date | number) => string;
 }
 
+declare type NiceDictionary = Record<string, string>;
+
+/**
+ * A drop-in for `NiceI18nProvider` — same `t` / `lang` / `overrides` — that loads only the
+ * language in use, on demand, instead of carrying all thirty dictionaries in the bundle.
+ *
+ * @example
+ * <NiceI18nLazyProvider lang="pl">
+ *   <App />
+ * </NiceI18nLazyProvider>
+ */
+export declare const NiceI18nLazyProvider: default_2.FC<NiceI18nLazyProviderProps>;
+
+export declare interface NiceI18nLazyProviderProps {
+    /**
+     * Custom translation function — takes priority over `lang` and nothing is loaded, as with
+     * `NiceI18nProvider`. Lets this provider replace that one everywhere, so nothing in an app
+     * has to reach for the module that holds all thirty dictionaries.
+     */
+    t?: NiceTranslateFn;
+    /** Built-in language code; its dictionary is loaded on first use. Default `'en'`. */
+    lang?: NiceSupportedLang;
+    /** Extra translations merged on top of the loaded dictionary. */
+    overrides?: Record<string, string>;
+    /**
+     * Rendered instead of `children` until the first dictionary has loaded. Leave it out to
+     * render the children straight away, in the controls' built-in English. On a language
+     * switch the previous language stays on screen until the new one arrives.
+     */
+    fallback?: default_2.ReactNode;
+    /** Called when a dictionary fails to load; the controls keep their current language. */
+    onError?: (error: unknown) => void;
+    children: default_2.ReactNode;
+}
+
 /**
  * Provider for plugging in your own translation function (e.g. from react-i18next)
  * OR using built-in dictionaries via the `lang` prop.
@@ -827,7 +885,12 @@ export declare function pseudoLocalize(text: string, options?: PseudoLocalizatio
  */
 export declare function pseudoLocalizeDictionary(dictionary: Record<string, string>, options?: PseudoLocalizationOptions): Record<string, string>;
 
-/** Resolve a register-aware dictionary by locale + variant. */
+/**
+ * Resolve a register-aware dictionary by locale + variant.
+ *
+ * Reads `pl` from its own module rather than through the aggregate, so this
+ * function pulls one language instead of all thirty.
+ */
 export declare function resolvePlVariant(variant: NiceI18nVariant): Record<string, string>;
 
 /**
@@ -1037,9 +1100,16 @@ export declare function useNiceNumberFormat(lang: NiceSupportedLang): NiceNumber
  */
 export declare function useNiceTimeFormat(lang: NiceSupportedLang, style?: DateFormatStyle): NiceTimeFormatter;
 
-/** Internal hook used by Nice2Dev UI components. */
+/**
+ * Internal hook used by Nice2Dev UI components.
+ *
+ * `lang` is the language the nearest provider was given ('en' with no provider). Pass it to
+ * `Intl` / `toLocaleDateString` instead of `undefined`, which uses the browser's language and
+ * can disagree with the language the rest of the interface is in.
+ */
 export declare function useNiceTranslation(): {
     t: NiceTranslateFn;
+    lang: NiceSupportedLang;
 };
 
 /**