react-native-i18njs 0.0.3 → 1.0.0

package/README.md

@@ -4,14 +4,17 @@
 [![License](https://img.shields.io/npm/l/react-native-i18njs.svg)](https://www.npmjs.com/package/react-native-i18njs)
 [![Platform](https://img.shields.io/badge/platform-react--native-blue.svg)](https://reactnative.dev)
 [![TypeScript](https://img.shields.io/badge/types-included-blue.svg)](https://www.typescriptlang.org)
+[![gzip size](https://img.shields.io/badge/gzip-%7E3.3%20KB-brightgreen.svg)](https://www.npmjs.com/package/react-native-i18njs)
 
-一个轻量级、类型安全、零心智负担的 React Native 国际化解决方案。
+一个**极致轻量**、类型安全、零心智负担的 React Native 国际化解决方案。  
+构建产物经 minify + gzip 后约 **3.3 KB**，对包体积几乎无感。
 
-专为 React Native 设计，集成了最佳实践，解决了常见的国际化痛点：繁琐的配置、类型缺失、复杂的 API 以及系统语言跟随问题。
+专为 React Native 设计，集成了最佳实践，解决繁琐配置、类型缺失、复杂 API 以及系统语言跟随等问题。
 
 ## ✨ 特性
 
-- � **零配置启动**：内置智能默认值，安装即用。
+- 📦 **极小体积**：ESM 构建 gzip 约 3.3 KB，CJS 约 3.5 KB；源码极致压缩，无冗余依赖。
+- ✨ **零配置启动**：内置智能默认值，安装即用。
 - 🛡️ **极致类型安全**：完全 TypeScript 编写，提供从 Key 到插值参数的完整类型推导。
 - 📱 **自动跟随系统**：基于 `react-native-localize`，自动检测并响应设备语言变更。
 - ⚡ **高性能**：基于 `i18n-js` 核心，轻量高效，无多余运行时开销。
@@ -19,6 +22,15 @@
 - 📝 **富文本支持**：`Trans` 组件轻松处理嵌套样式和组件插值。
 - 🌍 **格式化内置**：开箱即用的数字、货币、日期格式化支持。
 
+## 📦 体积说明 (Bundle Size)
+
+| 格式 | 未压缩 | gzip |
+|------|--------|------|
+| ESM (`.mjs`) | ~8.1 KB | **~3.3 KB** |
+| CJS (`.js`)  | ~8.9 KB | **~3.5 KB** |
+
+以上为单入口打包、开启 minify 后的体积；实际打进业务的增量取决于打包工具的 tree-shaking。推荐使用 ESM 以获得更优体积与 gzip 表现。
+
 ## 📦 安装
 
 ```bash
@@ -252,8 +264,31 @@ formatDate(new Date());
 | `onMissingKey` | `function` | - | 缺失 key 的回调 |
 | `onLocaleChange` | `function` | - | 语言变更回调 |
 
+## ✅ 生产就绪 (Production Ready)
+
+本库在功能与健壮性上已按生产标准实现，具备：
+
+| 能力 | 说明 |
+|------|------|
+| **多场景使用** | 组件内（Hook / HOC）、组件外（全局 `t`、格式化、Redux/拦截器等）统一 API |
+| **插值与复数** | `%{name}` 插值、`one`/`other` 等复数规则（透传 i18n-js），支持 `defaultValue` |
+| **缺失策略** | `missingBehavior`：回退 key / 空串 / 抛错；`onMissingKey` 便于上报与兜底 |
+| **语言链** | 当前 locale 自动降级（如 en-US → en）、自定义 `fallbackLocales`、可函数动态回退 |
+| **系统语言** | 基于 `react-native-localize`，App 回到前台自动同步；`setLocale` 用户锁定、`resetToSystem` 恢复跟随 |
+| **动态文案** | `loadTranslations` 合并新语种/命名空间，`subscribe` 通知 UI 更新 |
+| **RTL** | 按语言/script 检测 RTL，调用 `I18nManager`（需重启生效，属 RN 限制） |
+| **格式化** | 数字/货币/日期使用 `Intl` 并带缓存，无 Intl 环境有降级 |
+| **富文本** | `Trans` 支持标签解析、组件映射、插值内嵌 React 节点 |
+| **类型安全** | `Path<T>`、`useI18n<T>` 提供 key 补全与校验 |
+| **环境兼容** | 无 `Intl` / 无 `react-native-localize` 时 try-catch 降级，不抛错 |
+
+使用前请在 App 入口**先调用 `initI18n`**，再使用 `t` / `useI18n` / `Trans` 等。
+
 ## 🧩 常见问题
 
+### 使用前必须先 init 吗？
+是的。在调用 `t`、`useI18n`、`Trans` 等之前，请在应用入口（如 `App.tsx`）执行一次 `initI18n(translations, options)`，否则会使用空翻译表。
+
 ### TypeScript 类型提示不工作？
 确保你在使用 `useI18n<MyTranslations>()` 时传入了你的翻译类型定义。
 

package/dist/index.d.mts

@@ -2,100 +2,70 @@ import { Scope, TranslateOptions } from 'i18n-js';
 import React, { ReactNode } from 'react';
 import { TextProps } from 'react-native';
 
+type Translations = Record<string, any>;
+type Listener = (locale: string, change?: {
+    type: 'locale' | 'translations';
+    version: number;
+}) => void;
 interface I18nOptions {
     defaultLocale?: string;
     enableFallback?: boolean;
     onLocaleChange?: (locale: string) => void;
     fallbackLocales?: string[] | ((locale: string) => string[]);
-    /**
-     * 是否跟随系统语言变化自动切换。
-     * - 默认 true：初始化会使用系统语言；App 回到前台时会再次同步系统语言（直到用户手动 setLocale）。
-     * - 设为 false：始终使用 defaultLocale / 手动 setLocale，不再自动同步系统语言。
-     */
     followSystem?: boolean;
     missingBehavior?: 'key' | 'empty' | 'throw';
     onMissingKey?: (key: string, locale: string) => void;
 }
-type Translations = Record<string, any>;
-type Listener = (locale: string, change?: {
-    type: 'locale' | 'translations';
-    version: number;
-}) => void;
-/**
- * i18n 引擎接口，定义了任何翻译引擎必须实现的方法
- */
-interface I18nEngine {
-    init(translations: Translations, options?: I18nOptions): void;
-    loadTranslations(translations: Translations): void;
-    setLocale(locale: string): void;
-    getLocale(): string;
-    t(scope: Scope, options?: TranslateOptions): string;
-    formatNumber(n: number, options?: Intl.NumberFormatOptions): string;
-    formatCurrency(n: number, currency: string, options?: Intl.NumberFormatOptions): string;
-    formatDate(date: Date | number, options?: Intl.DateTimeFormatOptions): string;
-    subscribe(listener: Listener): () => void;
-    isRTL(): boolean;
-    /** 重置为跟随系统语言，撤销 setLocale 的用户锁定 */
-    resetToSystem(): void;
-    ready(): Promise<void>;
-    isReady(): boolean;
-}
-/**
- * 默认的 i18n-js 引擎实现
- */
-declare class DefaultI18nEngine implements I18nEngine {
-    private i18n;
-    private listeners;
-    private onLocaleChange?;
-    private fallbackLocales?;
-    private missingBehavior;
-    private onMissingKey?;
-    private enableFallback;
-    private followSystem;
-    private localeSource;
-    private initialized;
-    private version;
-    private readyPromise;
-    private resolveReady?;
-    /** Intl 格式化器缓存，key = locale + JSON(options) */
-    private numberFormatCache;
-    private dateFormatCache;
-    /** locale chain 缓存，locale 或 fallbackLocales 变化时失效 */
-    private localeChainCache;
+declare class E {
+    private i;
+    private ls;
+    private cb?;
+    private fb?;
+    private mb;
+    private mk?;
+    private ef;
+    private fs;
+    private sr;
+    private ok;
+    private v;
+    private rp;
+    private rr?;
+    private nc;
+    private dc;
+    private lc;
     constructor();
-    init(translations: Translations, options?: I18nOptions): void;
-    loadTranslations(translations: Translations): void;
+    init(tr: Translations, o?: I18nOptions): void;
+    loadTranslations(tr: Translations): void;
     updateLocale(): void;
-    setLocale(locale: string): void;
+    setLocale(l: string): void;
     getLocale(): string;
     resetToSystem(): void;
     t(scope: Scope, options?: TranslateOptions): string;
-    formatNumber(n: number, options?: Intl.NumberFormatOptions): string;
-    formatCurrency(n: number, currency: string, options?: Intl.NumberFormatOptions): string;
-    formatDate(date: Date | number, options?: Intl.DateTimeFormatOptions): string;
-    subscribe(listener: Listener): () => void;
+    formatNumber(n: number, o?: Intl.NumberFormatOptions): string;
+    formatCurrency(n: number, c: string, o?: Intl.NumberFormatOptions): string;
+    formatDate(d: Date | number, o?: Intl.DateTimeFormatOptions): string;
+    subscribe(l: Listener): () => void;
     isRTL(): boolean;
     ready(): Promise<void>;
     isReady(): boolean;
-    private invalidateCaches;
-    private getCachedNumberFormat;
-    private getCachedDateFormat;
-    private handleRTL;
-    private notifyListeners;
-    private setLocaleFromSystem;
-    private applyLocale;
-    private translateAtLocale;
-    /** 将 locale 及其自动降级（如 en-US → en）追加到 chain 中 */
-    private pushWithDegradation;
-    private getLocaleChain;
-    private hasTranslation;
-    private normalizeTranslateResult;
-    private normalizeLocaleTag;
-    private normalizeTranslations;
-    private isRTLLocale;
+    private cl;
+    private gn;
+    private gd;
+    private em;
+    private ap;
+    private hr;
+    private ta;
+    private dg;
+    private gc;
+    private ht;
+    private nr;
+    private nt;
 }
-declare const i18nService: DefaultI18nEngine;
+declare const i18nService: E;
 
+type Path<T> = T extends object ? {
+    [K in keyof T]: `${Exclude<K, symbol>}${"" | `.${Path<T[K]>}`}`;
+}[keyof T] : never;
 interface I18nContextType {
     locale: string;
     setLocale: (locale: string) => void;
@@ -111,12 +81,6 @@ interface I18nProviderProps {
     fallback?: ReactNode;
 }
 declare const I18nProvider: React.FC<I18nProviderProps>;
-declare function withI18n<P extends object>(Component: React.ComponentType<P & I18nContextType>): React.FC<Omit<P, keyof I18nContextType>>;
-
-type Path<T> = T extends object ? {
-    [K in keyof T]: `${Exclude<K, symbol>}${"" | `.${Path<T[K]>}`}`;
-}[keyof T] : never;
-
 type TFunction<T> = (scope: T extends Translations ? Path<T> : string, options?: TranslateOptions) => string;
 declare function useI18n<T = Translations>(): {
     t: TFunction<T>;
@@ -126,6 +90,7 @@ declare function useI18n<T = Translations>(): {
     formatCurrency: (n: number, currency: string, options?: Intl.NumberFormatOptions) => string;
     formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
 };
+declare function withI18n<P extends object>(C: React.ComponentType<P & I18nContextType>): React.FC<Omit<P, keyof I18nContextType>>;
 
 interface TransProps extends TextProps {
     i18nKey: string;
@@ -134,17 +99,16 @@ interface TransProps extends TextProps {
 }
 declare const Trans: React.FC<TransProps>;
 
-declare const initI18n: (translations: Translations, options?: I18nOptions) => void;
-declare const loadTranslations: (translations: Translations) => void;
-declare const setLocale: (locale: string) => void;
+declare const initI18n: (t: Translations, o?: I18nOptions) => void;
+declare const loadTranslations: (t: Translations) => void;
+declare const setLocale: (l: string) => void;
 declare const getLocale: () => string;
-declare const t: (scope: Scope, options?: TranslateOptions) => string;
-declare const formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
-declare const formatCurrency: (n: number, currency: string, options?: Intl.NumberFormatOptions) => string;
-declare const formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
-declare const subscribe: (listener: Listener) => (() => void);
+declare const t: (scope: Scope, o?: TranslateOptions) => string;
+declare const formatNumber: (n: number, o?: Intl.NumberFormatOptions) => string;
+declare const formatCurrency: (n: number, c: string, o?: Intl.NumberFormatOptions) => string;
+declare const formatDate: (d: Date | number, o?: Intl.DateTimeFormatOptions) => string;
+declare const subscribe: (l: Listener) => () => void;
 declare const isRTL: () => boolean;
-/** 重置为跟随系统语言，撤销 setLocale 的用户锁定 */
 declare const resetToSystem: () => void;
 declare const readyI18n: () => Promise<void>;
 declare const isI18nReady: () => boolean;

package/dist/index.d.ts

@@ -2,100 +2,70 @@ import { Scope, TranslateOptions } from 'i18n-js';
 import React, { ReactNode } from 'react';
 import { TextProps } from 'react-native';
 
+type Translations = Record<string, any>;
+type Listener = (locale: string, change?: {
+    type: 'locale' | 'translations';
+    version: number;
+}) => void;
 interface I18nOptions {
     defaultLocale?: string;
     enableFallback?: boolean;
     onLocaleChange?: (locale: string) => void;
     fallbackLocales?: string[] | ((locale: string) => string[]);
-    /**
-     * 是否跟随系统语言变化自动切换。
-     * - 默认 true：初始化会使用系统语言；App 回到前台时会再次同步系统语言（直到用户手动 setLocale）。
-     * - 设为 false：始终使用 defaultLocale / 手动 setLocale，不再自动同步系统语言。
-     */
     followSystem?: boolean;
     missingBehavior?: 'key' | 'empty' | 'throw';
     onMissingKey?: (key: string, locale: string) => void;
 }
-type Translations = Record<string, any>;
-type Listener = (locale: string, change?: {
-    type: 'locale' | 'translations';
-    version: number;
-}) => void;
-/**
- * i18n 引擎接口，定义了任何翻译引擎必须实现的方法
- */
-interface I18nEngine {
-    init(translations: Translations, options?: I18nOptions): void;
-    loadTranslations(translations: Translations): void;
-    setLocale(locale: string): void;
-    getLocale(): string;
-    t(scope: Scope, options?: TranslateOptions): string;
-    formatNumber(n: number, options?: Intl.NumberFormatOptions): string;
-    formatCurrency(n: number, currency: string, options?: Intl.NumberFormatOptions): string;
-    formatDate(date: Date | number, options?: Intl.DateTimeFormatOptions): string;
-    subscribe(listener: Listener): () => void;
-    isRTL(): boolean;
-    /** 重置为跟随系统语言，撤销 setLocale 的用户锁定 */
-    resetToSystem(): void;
-    ready(): Promise<void>;
-    isReady(): boolean;
-}
-/**
- * 默认的 i18n-js 引擎实现
- */
-declare class DefaultI18nEngine implements I18nEngine {
-    private i18n;
-    private listeners;
-    private onLocaleChange?;
-    private fallbackLocales?;
-    private missingBehavior;
-    private onMissingKey?;
-    private enableFallback;
-    private followSystem;
-    private localeSource;
-    private initialized;
-    private version;
-    private readyPromise;
-    private resolveReady?;
-    /** Intl 格式化器缓存，key = locale + JSON(options) */
-    private numberFormatCache;
-    private dateFormatCache;
-    /** locale chain 缓存，locale 或 fallbackLocales 变化时失效 */
-    private localeChainCache;
+declare class E {
+    private i;
+    private ls;
+    private cb?;
+    private fb?;
+    private mb;
+    private mk?;
+    private ef;
+    private fs;
+    private sr;
+    private ok;
+    private v;
+    private rp;
+    private rr?;
+    private nc;
+    private dc;
+    private lc;
     constructor();
-    init(translations: Translations, options?: I18nOptions): void;
-    loadTranslations(translations: Translations): void;
+    init(tr: Translations, o?: I18nOptions): void;
+    loadTranslations(tr: Translations): void;
     updateLocale(): void;
-    setLocale(locale: string): void;
+    setLocale(l: string): void;
     getLocale(): string;
     resetToSystem(): void;
     t(scope: Scope, options?: TranslateOptions): string;
-    formatNumber(n: number, options?: Intl.NumberFormatOptions): string;
-    formatCurrency(n: number, currency: string, options?: Intl.NumberFormatOptions): string;
-    formatDate(date: Date | number, options?: Intl.DateTimeFormatOptions): string;
-    subscribe(listener: Listener): () => void;
+    formatNumber(n: number, o?: Intl.NumberFormatOptions): string;
+    formatCurrency(n: number, c: string, o?: Intl.NumberFormatOptions): string;
+    formatDate(d: Date | number, o?: Intl.DateTimeFormatOptions): string;
+    subscribe(l: Listener): () => void;
     isRTL(): boolean;
     ready(): Promise<void>;
     isReady(): boolean;
-    private invalidateCaches;
-    private getCachedNumberFormat;
-    private getCachedDateFormat;
-    private handleRTL;
-    private notifyListeners;
-    private setLocaleFromSystem;
-    private applyLocale;
-    private translateAtLocale;
-    /** 将 locale 及其自动降级（如 en-US → en）追加到 chain 中 */
-    private pushWithDegradation;
-    private getLocaleChain;
-    private hasTranslation;
-    private normalizeTranslateResult;
-    private normalizeLocaleTag;
-    private normalizeTranslations;
-    private isRTLLocale;
+    private cl;
+    private gn;
+    private gd;
+    private em;
+    private ap;
+    private hr;
+    private ta;
+    private dg;
+    private gc;
+    private ht;
+    private nr;
+    private nt;
 }
-declare const i18nService: DefaultI18nEngine;
+declare const i18nService: E;
 
+type Path<T> = T extends object ? {
+    [K in keyof T]: `${Exclude<K, symbol>}${"" | `.${Path<T[K]>}`}`;
+}[keyof T] : never;
 interface I18nContextType {
     locale: string;
     setLocale: (locale: string) => void;
@@ -111,12 +81,6 @@ interface I18nProviderProps {
     fallback?: ReactNode;
 }
 declare const I18nProvider: React.FC<I18nProviderProps>;
-declare function withI18n<P extends object>(Component: React.ComponentType<P & I18nContextType>): React.FC<Omit<P, keyof I18nContextType>>;
-
-type Path<T> = T extends object ? {
-    [K in keyof T]: `${Exclude<K, symbol>}${"" | `.${Path<T[K]>}`}`;
-}[keyof T] : never;
-
 type TFunction<T> = (scope: T extends Translations ? Path<T> : string, options?: TranslateOptions) => string;
 declare function useI18n<T = Translations>(): {
     t: TFunction<T>;
@@ -126,6 +90,7 @@ declare function useI18n<T = Translations>(): {
     formatCurrency: (n: number, currency: string, options?: Intl.NumberFormatOptions) => string;
     formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
 };
+declare function withI18n<P extends object>(C: React.ComponentType<P & I18nContextType>): React.FC<Omit<P, keyof I18nContextType>>;
 
 interface TransProps extends TextProps {
     i18nKey: string;
@@ -134,17 +99,16 @@ interface TransProps extends TextProps {
 }
 declare const Trans: React.FC<TransProps>;
 
-declare const initI18n: (translations: Translations, options?: I18nOptions) => void;
-declare const loadTranslations: (translations: Translations) => void;
-declare const setLocale: (locale: string) => void;
+declare const initI18n: (t: Translations, o?: I18nOptions) => void;
+declare const loadTranslations: (t: Translations) => void;
+declare const setLocale: (l: string) => void;
 declare const getLocale: () => string;
-declare const t: (scope: Scope, options?: TranslateOptions) => string;
-declare const formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
-declare const formatCurrency: (n: number, currency: string, options?: Intl.NumberFormatOptions) => string;
-declare const formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
-declare const subscribe: (listener: Listener) => (() => void);
+declare const t: (scope: Scope, o?: TranslateOptions) => string;
+declare const formatNumber: (n: number, o?: Intl.NumberFormatOptions) => string;
+declare const formatCurrency: (n: number, c: string, o?: Intl.NumberFormatOptions) => string;
+declare const formatDate: (d: Date | number, o?: Intl.DateTimeFormatOptions) => string;
+declare const subscribe: (l: Listener) => () => void;
 declare const isRTL: () => boolean;
-/** 重置为跟随系统语言，撤销 setLocale 的用户锁定 */
 declare const resetToSystem: () => void;
 declare const readyI18n: () => Promise<void>;
 declare const isI18nReady: () => boolean;