@nice2dev/i18n 1.0.3

package/dist/index.d.ts

@@ -0,0 +1,439 @@
+/**
+ * @nice2dev/i18n
+ * Shared internationalization infrastructure for Nice2Dev UI libraries.
+ *
+ * Features:
+ * - NiceI18nProvider for React context-based translations
+ * - Built-in dictionaries for 20 languages
+ * - ICU MessageFormat with pluralization, gender, ordinals, and select
+ * - Browser language detection
+ * - Custom translation function support (e.g. react-i18next)
+ *
+ * @packageDocumentation
+ */
+
+import { default as default_2 } from 'react';
+
+/**
+ * Check common RTL issues in styles.
+ * This is a static analysis helper for development.
+ */
+export declare function analyzeStylesForRTL(styles: Record<string, string | number>): string[];
+
+/**
+ * Create a locale-aware currency formatter.
+ */
+export declare function createCurrencyFormatter(lang: NiceSupportedLang, currency?: string): NiceCurrencyFormatter;
+
+/**
+ * Create a locale-aware date formatter.
+ */
+export declare function createDateFormatter(lang: NiceSupportedLang, style?: DateFormatStyle): NiceDateFormatter;
+
+/**
+ * Create a translator function that supports ICU MessageFormat.
+ */
+export declare function createICUTranslator(dict: Record<string, string>, lang?: NiceSupportedLang): (key: string, defaultValue: string, values?: Record<string, string | number | Date>) => string;
+
+/**
+ * Create a locale-aware number formatter.
+ */
+export declare function createNumberFormatter(lang: NiceSupportedLang): NiceNumberFormatter;
+
+/**
+ * Create a locale-aware time formatter.
+ */
+export declare function createTimeFormatter(lang: NiceSupportedLang, style?: DateFormatStyle): NiceTimeFormatter;
+
+/** 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';
+
+/** Get user's preferred language from browser. */
+export declare function detectBrowserLanguage(): NiceSupportedLang;
+
+/**
+ * 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
+ */
+export declare function flipAlignment(align: string, isRTL: boolean): string;
+
+/**
+ * Flip a horizontal position for RTL.
+ * left ↔ right
+ */
+export declare function flipHorizontal(position: 'left' | 'right'): 'left' | 'right';
+
+/**
+ * Format an ICU MessageFormat string with values.
+ *
+ * @example
+ * // Simple placeholder
+ * formatICU('Hello, {name}!', { name: 'World' }) // 'Hello, World!'
+ *
+ * // Plural
+ * formatICU('{count, plural, one{# item} other{# items}}', { count: 5 }, { lang: 'en' }) // '5 items'
+ *
+ * // Select (gender)
+ * formatICU('{gender, select, male{He} female{She} other{They}} liked it', { gender: 'female' }) // 'She liked it'
+ *
+ * // Ordinal
+ * formatICU('{pos, selectordinal, one{#st} two{#nd} few{#rd} other{#th}}', { pos: 3 }, { lang: 'en' }) // '3rd'
+ *
+ * // Number formatting
+ * formatICU('Price: {price, number, currency}', { price: 99.99 }) // 'Price: $99.99'
+ *
+ * // Date formatting
+ * formatICU('Date: {date, date, long}', { date: new Date() }) // 'Date: January 15, 2025'
+ */
+export declare function formatICU(template: string, values?: Record<string, string | number | Date>, options?: ICUFormatOptions): string;
+
+/**
+ * ICU MessageFormat-lite interpolation.
+ * Supports basic {placeholder} and {plural, count, ...} patterns.
+ */
+export declare function formatMessage(template: string, values?: Record<string, string | number>): string;
+
+/**
+ * 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 translation statistics for all languages.
+ */
+export declare function getAllTranslationStats(): TranslationStats[];
+
+/**
+ * Get the current document direction.
+ */
+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 the BCP 47 locale tag for a NiceSupportedLang code.
+ */
+export declare function getLocaleTag(lang: NiceSupportedLang): string;
+
+/**
+ * Get logical property names based on physical ones.
+ * Useful for generating RTL-safe CSS.
+ */
+export declare function getLogicalProperty(physical: string): string;
+
+/**
+ * Find missing translations for a specific language.
+ */
+export declare function getMissingTranslations(lang: NiceSupportedLang): MissingTranslation[];
+
+/**
+ * Get ordinal category for a number in a given language.
+ * e.g., English: 1st, 2nd, 3rd, 4th...
+ */
+export declare function getOrdinalCategory(n: number, lang: NiceSupportedLang): OrdinalCategory;
+
+/**
+ * Get plural category for a number in a given language.
+ * Implements CLDR plural rules for supported languages.
+ */
+export declare function getPluralCategory(n: number, lang: NiceSupportedLang): PluralCategory;
+
+/**
+ * Generate CSS custom property values for RTL support.
+ */
+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.
+ */
+export declare function getTextDirection(lang: string): 'ltr' | 'rtl';
+
+/**
+ * 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;
+}
+
+export declare interface ICUFormatOptions {
+    lang?: NiceSupportedLang;
+    locale?: string;
+}
+
+/**
+ * Check if a language uses RTL text direction.
+ */
+export declare function isRTLLanguage(lang: string): boolean;
+
+/** Check if a language is supported. */
+export declare function isSupported(lang: string): lang is NiceSupportedLang;
+
+/**
+ * Look up a term in the glossary for a given language.
+ * Returns the approved translation or undefined.
+ */
+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 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"];
+
+export declare interface NiceCurrencyFormatter {
+    format: (value: number) => string;
+}
+
+export declare interface NiceDateFormatter {
+    format: (date: Date | number) => string;
+    formatRange: (start: Date | number, end: Date | number) => string;
+    formatRelative: (date: Date | number) => string;
+}
+
+/**
+ * Provider for plugging in your own translation function (e.g. from react-i18next)
+ * OR using built-in dictionaries via the `lang` prop.
+ *
+ * @example
+ * // Mode 1 — Built-in dictionaries (20 languages out of the box):
+ * <NiceI18nProvider lang="pl">
+ *   <MyApp />
+ * </NiceI18nProvider>
+ *
+ * @example
+ * // Mode 2 — Custom translation function (e.g. react-i18next):
+ * import { useTranslation } from 'react-i18next';
+ * function App() {
+ *   const { t } = useTranslation();
+ *   return (
+ *     <NiceI18nProvider t={t}>
+ *       <MyPage />
+ *     </NiceI18nProvider>
+ *   );
+ * }
+ *
+ * @example
+ * // Mode 3 — No provider, English defaults work out of the box:
+ * <NiceButton>Click me</NiceButton>
+ */
+export declare const NiceI18nProvider: default_2.FC<NiceI18nProviderProps>;
+
+export declare interface NiceI18nProviderProps {
+    /** Custom translation function — takes priority over `lang`. */
+    t?: NiceTranslateFn;
+    /** Built-in language code. Uses bundled dictionaries for 20 languages. */
+    lang?: NiceSupportedLang;
+    /** Extra translations to merge on top of built-in dictionary. */
+    overrides?: Record<string, string>;
+    children: default_2.ReactNode;
+}
+
+export declare interface NiceNumberFormatter {
+    format: (value: number) => string;
+    formatCompact: (value: number) => string;
+    formatPercent: (value: number) => string;
+}
+
+export declare type NiceSupportedLang = (typeof NICE_SUPPORTED_LANGS)[number];
+
+export declare interface NiceTimeFormatter {
+    format: (date: Date | number) => string;
+}
+
+/**
+ * Translation function type.
+ * Accepts a key and a default/fallback value, returns the translated string.
+ */
+export declare type NiceTranslateFn = (key: string, defaultValue: string) => string;
+
+/**
+ * Type-safe ordinal helper.
+ */
+export declare function ordinal(n: number, forms: Partial<Record<OrdinalCategory, string>> & {
+    other: string;
+}, lang?: NiceSupportedLang): string;
+
+export declare type OrdinalCategory = 'one' | 'two' | 'few' | 'other';
+
+/**
+ * Type-safe plural helper.
+ * Returns the appropriate form based on count.
+ */
+export declare function plural(count: number, forms: Partial<Record<PluralCategory, string>> & {
+    other: string;
+}, lang?: NiceSupportedLang): string;
+
+export declare type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+
+/**
+ * CSS custom properties for RTL-aware components.
+ * Use these as fallbacks in CSS-in-JS or CSS modules.
+ */
+export declare const RTL_CSS_VARS: {
+    readonly dirMultiplier: "--nice-dir-multiplier";
+    readonly inlineStart: "--nice-inline-start";
+    readonly inlineEnd: "--nice-inline-end";
+};
+
+/**
+ * Languages that use right-to-left text direction.
+ * Currently not in NICE_SUPPORTED_LANGS but planned for future.
+ */
+export declare const RTL_LANGUAGES: readonly ["ar", "he", "fa", "ur", "yi", "ps"];
+
+export declare interface RTLContextValue {
+    /** Current text direction */
+    dir: 'ltr' | 'rtl';
+    /** Whether current direction is RTL */
+    isRTL: boolean;
+    /** Flip alignment helper */
+    flip: (align: string) => string;
+    /** Get RTL-aware value */
+    value: <T>(values: {
+        ltr: T;
+        rtl: T;
+    }) => T;
+}
+
+export declare type RTLLanguage = typeof RTL_LANGUAGES[number];
+
+/**
+ * Provider for RTL context.
+ * Automatically detects RTL languages and provides helpers.
+ */
+export declare const RTLProvider: default_2.FC<RTLProviderProps>;
+
+export declare interface RTLProviderProps {
+    /** Language code to determine direction */
+    lang: string;
+    /** Whether to automatically set document direction */
+    autoSetDocument?: boolean;
+    children: default_2.ReactNode;
+}
+
+/**
+ * Get the appropriate value based on text direction.
+ */
+export declare function rtlValue<T>(values: {
+    ltr: T;
+    rtl: T;
+}, isRTL: boolean): T;
+
+export declare interface RTLVerificationResult {
+    component: string;
+    issues: string[];
+    recommendations: string[];
+    isRTLReady: boolean;
+}
+
+/**
+ * Type-safe select helper (for gender, etc.).
+ */
+export declare function select<T extends string>(value: T, forms: Partial<Record<T, string>> & {
+    other: string;
+}): string;
+
+/**
+ * Set the document's text direction and lang attribute.
+ * Updates both <html> attributes for proper RTL support.
+ */
+export declare function setDocumentDirection(lang: string): void;
+
+export declare interface TranslationResult {
+    key: string;
+    original: string;
+    translated: string;
+}
+
+export declare interface TranslationStats {
+    lang: NiceSupportedLang;
+    totalKeys: number;
+    translatedKeys: number;
+    missingKeys: number;
+    coverage: number;
+}
+
+/**
+ * Hook that returns true if current layout is RTL.
+ */
+export declare function useIsRTL(): boolean;
+
+/**
+ * React hook: locale-aware currency formatting.
+ */
+export declare function useNiceCurrencyFormat(lang: NiceSupportedLang, currency?: string): NiceCurrencyFormatter;
+
+/**
+ * React hook: locale-aware date formatting.
+ */
+export declare function useNiceDateFormat(lang: NiceSupportedLang, style?: DateFormatStyle): NiceDateFormatter;
+
+/**
+ * React hook: locale-aware number formatting.
+ */
+export declare function useNiceNumberFormat(lang: NiceSupportedLang): NiceNumberFormatter;
+
+/**
+ * React hook: locale-aware time formatting.
+ */
+export declare function useNiceTimeFormat(lang: NiceSupportedLang, style?: DateFormatStyle): NiceTimeFormatter;
+
+/** Internal hook used by Nice2Dev UI components. */
+export declare function useNiceTranslation(): {
+    t: NiceTranslateFn;
+};
+
+/**
+ * Hook to access RTL context and helpers.
+ */
+export declare function useRTL(): RTLContextValue;
+
+/**
+ * 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 { }