react-native-i18njs 0.0.2 → 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-present, wangws
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -4,21 +4,33 @@
 [![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` 核心，轻量高效，无多余运行时开销。
-- 🔌 **灵活 API**：同时支持 Hook (`useI18n`)、高阶组件 (`withTranslation`) 和全局函数 (`t`)。
+- 🔌 **灵活 API**：同时支持 Hook (`useI18n`)、高阶组件 (`withI18n`) 和全局函数 (`t`)。
 - 📝 **富文本支持**：`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
@@ -129,13 +141,13 @@ const message = t('errors.network_timeout');
 
 #### 进阶：监听语言变化
 
-如果你需要在组件外监听语言变更（例如同步更新全局状态），可以使用默认导出的实例：
+如果你需要在组件外监听语言变更（例如同步更新全局状态），可以使用顶层 `subscribe` 函数：
 
 ```ts
-import i18n from 'react-native-i18njs';
+import { subscribe } from 'react-native-i18njs';
 
 // 订阅语言变更
-const unsubscribe = i18n.subscribe((locale) => {
+const unsubscribe = subscribe((locale) => {
   console.log('Language changed to:', locale);
   // 更新 API 默认 Header 或其他全局状态
 });
@@ -144,6 +156,27 @@ const unsubscribe = i18n.subscribe((locale) => {
 // unsubscribe();
 ```
 
+#### 进阶：重置为跟随系统
+
+用户手动调用 `setLocale` 后会锁定语言，不再自动跟随系统。如果需要恢复跟随系统语言：
+
+```ts
+import { resetToSystem } from 'react-native-i18njs';
+
+// 撤销用户锁定，重新跟随系统语言
+resetToSystem();
+```
+
+#### 进阶：RTL 检测
+
+```ts
+import { isRTL } from 'react-native-i18njs';
+
+if (isRTL()) {
+  // 当前为从右到左语言（如阿拉伯语、希伯来语）
+}
+```
+
 #### 实战示例：Axios 拦截器
 
 ```ts
@@ -192,7 +225,7 @@ async function loadFrench() {
 
 ### 4. 格式化工具
 
-利用 `Intl` 标准进行格式化：
+利用 `Intl` 标准进行格式化，在组件中通过 Hook 使用：
 
 ```ts
 const { formatNumber, formatCurrency, formatDate } = useI18n();
@@ -207,6 +240,16 @@ formatCurrency(99.99, 'USD'); // "$99.99"
 formatDate(new Date(), { dateStyle: 'full' }); // "Tuesday, October 10, 2023"
 ```
 
+在非组件环境中，也可以直接使用顶层导出：
+
+```ts
+import { formatNumber, formatCurrency, formatDate } from 'react-native-i18njs';
+
+formatNumber(1234.56);
+formatCurrency(99.99, 'USD');
+formatDate(new Date());
+```
+
 ## ⚙️ 配置选项 (I18nOptions)
 
 `initI18n` 接受的第二个参数对象：
@@ -221,8 +264,31 @@ formatDate(new Date(), { dateStyle: 'full' }); // "Tuesday, October 10, 2023"
 | `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,87 +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;
-    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?;
+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 handleRTL;
-    private notifyListeners;
-    private setLocaleFromSystem;
-    private applyLocale;
-    private translateAtLocale;
-    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;
@@ -98,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>;
@@ -113,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;
@@ -121,12 +99,18 @@ 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 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;
+declare const resetToSystem: () => void;
 declare const readyI18n: () => Promise<void>;
 declare const isI18nReady: () => boolean;
 
-export { I18nContext, type I18nContextType, type I18nOptions, I18nProvider, type I18nProviderProps, type Path, Trans, type Translations, i18nService as default, getLocale, initI18n, isI18nReady, loadTranslations, readyI18n, setLocale, t, useI18n, withI18n };
+export { I18nContext, type I18nContextType, type I18nOptions, I18nProvider, type I18nProviderProps, type Listener, type Path, Trans, type Translations, i18nService as default, formatCurrency, formatDate, formatNumber, getLocale, initI18n, isI18nReady, isRTL, loadTranslations, readyI18n, resetToSystem, setLocale, subscribe, t, useI18n, withI18n };

package/dist/index.d.ts

@@ -2,87 +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;
-    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?;
+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 handleRTL;
-    private notifyListeners;
-    private setLocaleFromSystem;
-    private applyLocale;
-    private translateAtLocale;
-    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;
@@ -98,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>;
@@ -113,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;
@@ -121,12 +99,18 @@ 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 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;
+declare const resetToSystem: () => void;
 declare const readyI18n: () => Promise<void>;
 declare const isI18nReady: () => boolean;
 
-export { I18nContext, type I18nContextType, type I18nOptions, I18nProvider, type I18nProviderProps, type Path, Trans, type Translations, i18nService as default, getLocale, initI18n, isI18nReady, loadTranslations, readyI18n, setLocale, t, useI18n, withI18n };
+export { I18nContext, type I18nContextType, type I18nOptions, I18nProvider, type I18nProviderProps, type Listener, type Path, Trans, type Translations, i18nService as default, formatCurrency, formatDate, formatNumber, getLocale, initI18n, isI18nReady, isRTL, loadTranslations, readyI18n, resetToSystem, setLocale, subscribe, t, useI18n, withI18n };