@nice2dev/i18n 1.1.9 → 1.2.0

package/dist/index.d.ts

@@ -4,11 +4,14 @@
  *
  * Features:
  * - NiceI18nProvider for React context-based translations
- * - Built-in dictionaries for 20 languages
+ * - Built-in dictionaries for 30 languages, loaded one language at a time
  * - ICU MessageFormat with pluralization, gender, ordinals, and select
  * - Browser language detection
  * - Custom translation function support (e.g. react-i18next)
  *
+ * Nothing on this entry imports a dictionary (1.2.0). What needs all thirty at once — the
+ * dictionary map, `createTranslator`, the translation tooling — is in `@nice2dev/i18n/all`.
+ *
  * @packageDocumentation
  */
 
@@ -185,9 +188,6 @@ export declare function createTimeFormatter(lang: NiceSupportedLang, style?: Dat
  */
 export declare function createTimezoneFormatter(lang: NiceSupportedLang, timezone: string, options?: TimezoneFormatterOptions): TimezoneFormatter;
 
-/** Get a translation function without React context (for non-component code). */
-export declare function createTranslator(lang?: NiceSupportedLang, overrides?: Record<string, string>): NiceTranslateFn;
-
 export declare type DateFormatStyle = 'short' | 'medium' | 'long' | 'full';
 
 export declare const DEFAULT_CALENDAR: Record<NiceSupportedLang, CalendarSystem>;
@@ -269,17 +269,6 @@ export declare interface DynamicLoader {
  */
 export declare function expandText(text: string, factor?: number, useVowelDoubling?: boolean): string;
 
-/**
- * Find fuzzy matches in existing translations for reuse.
- * Compares the English value to find similar existing translations.
- */
-export declare function findSimilarTranslation(englishValue: string, lang: NiceSupportedLang, threshold?: number): {
-    key: string;
-    english: string;
-    translated: string;
-    similarity: number;
-} | undefined;
-
 /**
  * Flip a horizontal alignment for RTL.
  * start ↔ end, left ↔ right
@@ -316,6 +305,13 @@ export declare function flipHorizontal(position: 'left' | 'right'): 'left' | 'ri
  */
 export declare function formatICU(template: string, values?: Record<string, string | number | Date>, options?: ICUFormatOptions): string;
 
+/**
+ * ICU MessageFormat-lite interpolation, the one helper of this module that is not a provider.
+ *
+ * 1.2.0: the provider moved to ./lazyDictionaries (it loads one language at a time), the
+ * language helpers to ./languages and `createTranslator` to ./all — this module used to
+ * import every dictionary for the eager provider.
+ */
 /**
  * ICU MessageFormat-lite interpolation.
  * Supports basic {placeholder} and {plural, count, ...} patterns.
@@ -327,26 +323,11 @@ export declare function formatMessage(template: string, values?: Record<string,
  */
 export declare function fromUTC(date: Date, toTimezone?: string): Date;
 
-/**
- * Generate a coverage report in markdown format.
- */
-export declare function generateCoverageReport(): string;
-
-/**
- * Generate TypeScript code for translations to be added to the dictionary.
- */
-export declare function generateTranslationCode(lang: NiceSupportedLang, translations: TranslationResult[]): string;
-
 /**
  * Get all available timezones with their info.
  */
 export declare function getAllTimezones(lang?: NiceSupportedLang, referenceDate?: Date): TimezoneInfo[];
 
-/**
- * Get translation statistics for all languages.
- */
-export declare function getAllTranslationStats(): TranslationStats[];
-
 /**
  * Get all available calendar systems.
  */
@@ -377,14 +358,6 @@ export declare function getCurrentCalendarDate(calendar: CalendarSystem, lang?:
  */
 export declare function getDocumentDirection(): 'ltr' | 'rtl';
 
-/**
- * Get all glossary entries for a specific language.
- */
-export declare function getGlossaryForLanguage(lang: NiceSupportedLang): Array<{
-    en: string;
-    translation: string;
-}>;
-
 /**
  * Get number of days in a Hijri month.
  */
@@ -400,6 +373,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.
  */
@@ -411,11 +387,6 @@ export declare function getLocaleTag(lang: NiceSupportedLang): string;
  */
 export declare function getLogicalProperty(physical: string): string;
 
-/**
- * Find missing translations for a specific language.
- */
-export declare function getMissingTranslations(lang: NiceSupportedLang): MissingTranslation[];
-
 /**
  * Get the next DST transition date for a timezone.
  */
@@ -448,11 +419,6 @@ export declare function getRecommendedCalendars(lang: NiceSupportedLang): Calend
  */
 export declare function getRTLCSSVars(isRTL: boolean): Record<string, string>;
 
-/**
- * Get all keys from the English dictionary (source of truth).
- */
-export declare function getSourceKeys(): string[];
-
 /**
  * Get text direction for a language.
  */
@@ -468,17 +434,6 @@ export declare function getTimezoneInfo(timezone: string, lang?: NiceSupportedLa
  */
 export declare function getTimezonesGrouped(lang?: NiceSupportedLang, referenceDate?: Date): Record<string, TimezoneInfo[]>;
 
-/**
- * Get translation statistics for a language.
- */
-export declare function getTranslationStats(lang: NiceSupportedLang): TranslationStats;
-
-export declare interface GlossaryEntry {
-    en: string;
-    translations: Partial<Record<NiceSupportedLang, string>>;
-    context?: string;
-}
-
 /**
  * Hebrew month names.
  */
@@ -602,26 +557,26 @@ export declare interface LoaderState {
 }
 
 /**
- * Look up a term in the glossary for a given language.
- * Returns the approved translation or undefined.
+ * 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.
  */
-export declare function lookupGlossary(englishTerm: string, lang: NiceSupportedLang): string | undefined;
-
-export declare interface MissingTranslation {
-    key: string;
-    englishValue: string;
-}
-
-export declare const NICE_GLOSSARY: GlossaryEntry[];
-
-export declare const NICE_I18N_DICTIONARIES: Record<NiceSupportedLang, Record<string, string>>;
+export declare function loadNiceDictionary(lang: NiceSupportedLang): Promise<NiceDictionary>;
 
 /**
- * Locale-and-register variants. Built on top of the base pl dictionary;
- * unspecified keys fall back to NICE_I18N_DICTIONARIES.pl.
+ * The languages with a built-in dictionary, and the two helpers that only need the list.
+ *
+ * Its own module, free of dictionary imports: the context, `useNiceTranslation` and the
+ * provider need the list but must not pull thirty dictionaries in with it. Until 1.1.x
+ * `isSupported` and `detectBrowserLanguage` sat next to the eager provider, in a module that
+ * imported all of them.
  */
-export declare const NICE_I18N_VARIANTS: Partial<Record<string, Partial<Record<NiceI18nVariant, Record<string, string>>>>>;
-
 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,18 +589,32 @@ export declare interface NiceDateFormatter {
     formatRelative: (date: Date | number) => string;
 }
 
+declare type NiceDictionary = Record<string, string>;
+
+/**
+ * {@link NiceI18nProvider} under its 1.1.10 name — the same component, so code written for
+ * 1.1.10 needs no change.
+ */
+export declare const NiceI18nLazyProvider: default_2.FC<NiceI18nProviderProps>;
+
+/** The props of {@link NiceI18nLazyProvider} — the same as {@link NiceI18nProviderProps}. */
+export declare type NiceI18nLazyProviderProps = NiceI18nProviderProps;
+
 /**
- * Provider for plugging in your own translation function (e.g. from react-i18next)
- * OR using built-in dictionaries via the `lang` prop.
+ * Puts a translator in context for every Nice control below it: your own translation function
+ * (e.g. from react-i18next), or the built-in dictionary of `lang`, loaded on first use.
  *
  * @example
- * // Mode 1 — Built-in dictionaries (20 languages out of the box):
- * <NiceI18nProvider lang="pl">
- *   <MyApp />
- * </NiceI18nProvider>
+ * // Built-in dictionaries (30 languages); start in Polish rather than in English:
+ * await loadNiceDictionary('pl');
+ * root.render(
+ *   <NiceI18nProvider lang="pl">
+ *     <MyApp />
+ *   </NiceI18nProvider>,
+ * );
  *
  * @example
- * // Mode 2 — Custom translation function (e.g. react-i18next):
+ * // Custom translation function (e.g. react-i18next) — nothing is loaded:
  * import { useTranslation } from 'react-i18next';
  * function App() {
  *   const { t } = useTranslation();
@@ -657,23 +626,32 @@ export declare interface NiceDateFormatter {
  * }
  *
  * @example
- * // Mode 3 — No provider, English defaults work out of the box:
+ * // No provider: the controls' built-in English.
  * <NiceButton>Click me</NiceButton>
  */
 export declare const NiceI18nProvider: default_2.FC<NiceI18nProviderProps>;
 
 export declare interface NiceI18nProviderProps {
-    /** Custom translation function — takes priority over `lang`. */
+    /**
+     * Custom translation function (e.g. from react-i18next) — takes priority over `lang`, and
+     * no dictionary is loaded.
+     */
     t?: NiceTranslateFn;
-    /** Built-in language code. Uses bundled dictionaries for 20 languages. */
+    /** Built-in language code; its dictionary is loaded on first use. Default `'en'`. */
     lang?: NiceSupportedLang;
-    /** Extra translations to merge on top of built-in dictionary. */
+    /** 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;
 }
 
-export declare type NiceI18nVariant = 'formal' | 'informal';
-
 export declare interface NiceNumberFormatter {
     format: (value: number) => string;
     formatCompact: (value: number) => string;
@@ -827,14 +805,6 @@ 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.
- *
- * 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>;
-
 /**
  * CSS custom properties for RTL-aware components.
  * Use these as fallbacks in CSS-in-JS or CSS modules.
@@ -971,20 +941,6 @@ export declare type TranslationDictionary = Record<string, string>;
 
 export declare type TranslationNamespace = Record<string, TranslationDictionary>;
 
-export declare interface TranslationResult {
-    key: string;
-    original: string;
-    translated: string;
-}
-
-export declare interface TranslationStats {
-    lang: NiceSupportedLang;
-    totalKeys: number;
-    translatedKeys: number;
-    missingKeys: number;
-    coverage: number;
-}
-
 /**
  * React hook for calendar formatting.
  */
@@ -1014,7 +970,7 @@ export declare function useDynamicI18n(): DynamicI18nContextValue;
 export declare function useDynamicTranslation(namespace?: string): {
     t: (key: string, params?: Record<string, string | number>) => string;
     isLoading: boolean;
-    currentLanguage: "no" | "de" | "en" | "pl" | "fr" | "es" | "it" | "pt" | "nl" | "sv" | "da" | "fi" | "cs" | "sk" | "hu" | "ro" | "bg" | "uk" | "ja" | "ko" | "zh" | "ar" | "hi" | "bn" | "th" | "vi" | "id" | "sw" | "fil" | "ms";
+    currentLanguage: "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";
 };
 
 /**
@@ -1078,14 +1034,4 @@ export declare function useTimezone(lang: NiceSupportedLang, timezone?: string,
     fromUTC: (date: Date) => Date;
 };
 
-/**
- * Validate translations against the glossary.
- * Returns entries where the translation doesn't match the glossary.
- */
-export declare function validateAgainstGlossary(lang: NiceSupportedLang): Array<{
-    key: string;
-    currentTranslation: string;
-    glossaryTranslation: string;
-}>;
-
 export { }