react-native-i18njs 0.0.1-beta → 0.0.1

package/README.md

@@ -1,39 +1,247 @@
 # react-native-i18njs
 
-#### 介绍
-{**以下是 Gitee 平台说明，您可以替换此简介**
-Gitee 是 OSCHINA 推出的基于 Git 的代码托管平台（同时支持 SVN）。专为开发者提供稳定、高效、安全的云端软件开发协作平台
-无论是个人、团队、或是企业，都能够用 Gitee 实现代码托管、项目管理、协作开发。企业项目请看 [https://gitee.com/enterprises](https://gitee.com/enterprises)}
+一个轻量级、类型安全、零心智负担的 React Native 国际化解决方案。
 
-#### 软件架构
-软件架构说明
+## 特性
 
+- 🚀 **开箱即用**：专为 React Native 设计，API 简单直观。
+- 📦 **自动语言检测**：基于 `react-native-localize` 自动匹配设备语言。
+- 🔄 **自动重渲染**：语言切换时，UI 自动更新。
+- 🛡️ **TypeScript 支持**：完全使用 TypeScript 编写，提供完整的类型提示。
+- 🧩 **基于 `i18n-js`**：轻量封装，默认使用 `i18n-js` 作为翻译引擎。
+- 🔌 **Hooks 支持**：提供 `useI18n` Hook，方便在组件中使用。
+- 📝 **富文本支持**：支持在翻译中嵌入组件。
+- 🔢 **格式化支持**：基于 JS 内置 `Intl` 的数字/货币/日期格式化（可传 options 自定义；环境不支持会自动降级）。
 
-#### 安装教程
+## 安装
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+首先安装本库及其依赖：
 
-#### 使用说明
+```bash
+npm install react-native-i18njs i18n-js react-native-localize
+# 或者
+yarn add react-native-i18njs i18n-js react-native-localize
+```
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+> 插值语法说明：本库基于 `i18n-js`，默认使用 `%{name}`（不是 `{{name}}`）。
 
-#### 参与贡献
+## 上手方式（两种都支持）
 
-1.  Fork 本仓库
-2.  新建 Feat_xxx 分支
-3.  提交代码
-4.  新建 Pull Request
+- **方式 A：不使用 `I18nProvider`（推荐）**：任何地方都能直接 `t()`，没有 React 心智负担；适合工具层/启动阶段/非 UI 代码。
+- **方式 B：使用 `I18nProvider`（可选）**：需要“切换语言后 UI 自动刷新”时再用。
 
+## 模块 1：初始化与全局函数（不需要 Provider）
 
-#### 特技
+### 1) 准备翻译资源
 
-1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
-2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
-3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
-4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
-5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
-6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
+```ts
+export const translations = {
+  en: { welcome: 'Welcome', hello: 'Hello, %{name}!' },
+  zh: { welcome: '欢迎', hello: '你好，%{name}！' },
+};
+```
+
+### 2) 初始化（只做一次）
+
+```ts
+import { initI18n } from 'react-native-i18njs';
+import { translations } from './locales';
+
+initI18n(translations, { defaultLocale: 'en', enableFallback: true });
+```
+
+### 3) 在任何地方直接使用 `t()`
+
+```ts
+import { t, setLocale, getLocale } from 'react-native-i18njs';
+
+setLocale('zh');
+getLocale(); // 'zh'
+t('hello', { name: 'Trae' }); // '你好，Trae！'
+t('missing.key', { defaultValue: '默认文案' });
+```
+
+### 不用 Provider 的典型场景
+
+- 网络层（如 axios 拦截器）拼接错误文案
+- 表单校验/工具函数/Toast 文案
+- Redux/Saga/Store 初始化阶段
+- React 组件之外（比如 navigation 配置、原生桥接回调）
+
+> 注意：不用 Provider 时，切换语言不会自动触发页面重渲染；如果你需要 UI 自动刷新，请看“模块 2”。
+
+## 模块 2：React 自动重渲染（I18nProvider + useI18n）
+
+```tsx
+import React from 'react';
+import { Text, Button } from 'react-native';
+import { I18nProvider, useI18n } from 'react-native-i18njs';
+
+function Home() {
+  const { t, locale, setLocale } = useI18n();
+  return (
+    <>
+      <Text>{t('welcome')}</Text>
+      <Text>{t('hello', { name: 'User' })}</Text>
+      <Text>{locale}</Text>
+      <Button title="EN" onPress={() => setLocale('en')} />
+      <Button title="中文" onPress={() => setLocale('zh')} />
+    </>
+  );
+}
+
+export default function App() {
+  return (
+    <I18nProvider>
+      <Home />
+    </I18nProvider>
+  );
+}
+```
+
+### `I18nProvider` 参数
+
+- `readyGate?: boolean`：为 `true` 时，未 ready 前不渲染 children
+- `fallback?: React.ReactNode`：`readyGate` 期间显示的占位
+
+### `useI18n<T>()`（类型安全 key）
+
+```ts
+type MyTranslations = typeof translations.en;
+const { t } = useI18n<MyTranslations>();
+t('welcome');
+t('home.title');
+```
+
+## 模块 3：动态加载翻译（loadTranslations）
+
+```ts
+import { loadTranslations } from 'react-native-i18njs';
+
+loadTranslations({ fr: { welcome: 'Bonjour' } });
+```
+
+## 模块 4：富文本（Trans）
+
+```tsx
+import React from 'react';
+import { Text } from 'react-native';
+import { Trans } from 'react-native-i18njs';
+
+// translations.en:
+// { description: 'This is <bold>bold</bold> text.', agree: 'I agree to %{terms}' }
+
+<Trans i18nKey="description" components={{ bold: <Text style={{ fontWeight: 'bold' }} /> }} />
+<Trans i18nKey="agree" values={{ terms: <Text style={{ fontWeight: 'bold' }}>Terms</Text> }} />
+```
+
+### `Trans` 参数
+
+- `i18nKey: string`
+- `values?: Record<string, any>`：插值值（字符串/数字/ReactElement 都支持）
+- `components?: Record<string, React.ReactNode>`：标签映射（如 `bold/link`）
+
+### `Trans` 能覆盖的场景
+
+- 句子内局部加粗/斜体/变色/可点击链接（用 `components` 映射 `<bold></bold>` / `<link></link>`）
+- 插值里插入组件（用 `values` 传 ReactElement，例如把 “Terms” 做成可点击文本）
+- 嵌套标签（例如 `<bold>...<italic>...</italic>...</bold>`）
+- 自闭合标签（例如 `<br/>`），可映射成 `components={{ br: <Text>{'\n'}</Text> }}`
+
+### `Trans` 的边界（不适合的场景）
+
+- 不支持标签属性/HTML（例如 `<a href="...">` / `<span style="...">`），需要你把“样式/点击行为”放到 `components` 或 `values` 传入的组件里
+- `components` 目前接收的是“元素”（例如 `<Text />`），不是组件函数（例如 `Text` / `Bold`），因为内部是 `cloneElement`
+- `Trans` 总是返回一个外层 `<Text>`；并且被插入的组件也必须是 `Text` 可渲染的内容（不要把 `<View>` 直接塞进文本里）
+- 不提供 ICU MessageFormat（select/plural/gender）语法；更复杂的语言结构建议拆 key + 用 JS 逻辑组合，或引入 ICU 方案
+- 翻译里如果出现不成对/不匹配的标签，会按纯文本保留（避免静默吞字），建议在翻译侧保持标签成对
+
+## 模块 5：Class 组件（withI18n）
+
+```tsx
+import React from 'react';
+import { Text } from 'react-native';
+import { withI18n } from 'react-native-i18njs';
+
+class Screen extends React.PureComponent<{ t: any }> {
+  render() {
+    return <Text>{this.props.t('welcome')}</Text>;
+  }
+}
+
+export default withI18n(Screen);
+```
+
+## 模块 6：初始化就绪（readyI18n / isI18nReady）
+
+```ts
+import { readyI18n, isI18nReady } from 'react-native-i18njs';
+
+await readyI18n();
+isI18nReady();
+```
+
+## 模块 7：数字/货币/日期格式化（formatNumber / formatCurrency / formatDate）
+
+`Intl` 是 JavaScript 自带的一套“国际化格式化”能力（浏览器和 Node 都有，React Native 取决于引擎/是否带完整 Intl）。
+
+这三个方法基于 `Intl`，默认使用“当前 locale”来格式化，并且都支持传入 `options` 自定义格式。
+
+```ts
+import { useI18n } from 'react-native-i18njs';
+
+const { formatNumber, formatCurrency, formatDate } = useI18n();
+
+formatNumber(1234567.891, { maximumFractionDigits: 2 });
+formatCurrency(99.9, 'CNY', { currencyDisplay: 'narrowSymbol' });
+formatDate(Date.now(), { dateStyle: 'medium', timeStyle: 'short' });
+```
+
+通用性边界：
+
+- 若运行环境没有完整 `Intl`（部分 RN/Hermes 场景），库会自动降级：
+  - number：`String(n)`
+  - currency：``${n} ${currency}``
+  - date：`toISOString()`
+- 如果你希望所有平台表现完全一致，请在你的 App 侧引入 `Intl` polyfill。
+- 如果你想用“非当前 locale”做格式化，请直接使用 `new Intl.NumberFormat('xx', options)` 自行处理。
+
+## 配置参数（I18nOptions）
+
+### `initI18n(translations, options?)`
+
+- `translations: Record<string, any>`：翻译资源（locale 为 key）
+- `options?`：
+  - `defaultLocale?: string`：默认 `'en'`
+  - `enableFallback?: boolean`：默认 `true`
+  - `followSystem?: boolean`：默认 `true`；用户手动 `setLocale` 后不再跟随系统
+  - `fallbackLocales?: string[] | ((locale: string) => string[])`：自定义回退链（按顺序）
+  - `missingBehavior?: 'key' | 'empty' | 'throw'`：默认 `'key'`
+  - `onMissingKey?: (key: string, locale: string) => void`：缺失 key 回调
+  - `onLocaleChange?: (locale: string) => void`：语言变更回调
+
+## API 速查（按模块）
+
+- **初始化/函数**
+  - `initI18n`, `t`, `setLocale`, `getLocale`, `loadTranslations`, `readyI18n`, `isI18nReady`
+- **React 绑定（可选）**
+  - `I18nProvider`, `useI18n`, `I18nContext`, `withI18n`
+- **组件**
+  - `Trans`
+- **类型**
+  - `I18nOptions`, `Translations`, `Path`
+- **默认导出**
+  - `i18nService`：服务单例（`formatNumber/formatCurrency/formatDate/subscribe/updateLocale` 等）
+
+## 常见问题
+
+### 1) `Invalid hook call` / 多个 React 实例
+
+如果你在 monorepo / workspace 中把本库以源码方式链接到示例或业务 App，可能出现重复 React 导致的 Hook 报错。参考本仓库示例的 Metro 配置做依赖指向与屏蔽：
+
+- 示例配置：[example/metro.config.js](./example/metro.config.js)
+
+## 平台支持
+
+- **iOS / Android**: 完全支持。
+- **Web**: 需要配置 `webpack` 以支持 `react-native-localize`。请参考 [react-native-localize 文档](https://github.com/zoontek/react-native-localize)。

package/dist/index.d.mts

@@ -0,0 +1,132 @@
+import { Scope, TranslateOptions } from 'i18n-js';
+import React, { ReactNode } from 'react';
+import { TextProps } from 'react-native';
+
+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?;
+    constructor();
+    init(translations: Translations, options?: I18nOptions): void;
+    loadTranslations(translations: Translations): void;
+    updateLocale(): 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;
+    private handleRTL;
+    private notifyListeners;
+    private setLocaleFromSystem;
+    private applyLocale;
+    private translateAtLocale;
+    private getLocaleChain;
+    private hasTranslation;
+    private normalizeTranslateResult;
+    private normalizeLocaleTag;
+    private normalizeTranslations;
+    private isRTLLocale;
+}
+declare const i18nService: DefaultI18nEngine;
+
+interface I18nContextType {
+    locale: string;
+    setLocale: (locale: string) => 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;
+}
+declare const I18nContext: React.Context<I18nContextType>;
+interface I18nProviderProps {
+    children: ReactNode;
+    readyGate?: boolean;
+    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>;
+    locale: string;
+    setLocale: (locale: string) => void;
+    formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
+    formatCurrency: (n: number, currency: string, options?: Intl.NumberFormatOptions) => string;
+    formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
+};
+
+interface TransProps extends TextProps {
+    i18nKey: string;
+    values?: Record<string, any>;
+    components?: Record<string, ReactNode>;
+}
+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 getLocale: () => string;
+declare const t: (scope: Scope, options?: TranslateOptions) => string;
+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 };

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import { Scope, TranslateOptions } from 'i18n-js';
+import React, { ReactNode } from 'react';
+import { TextProps } from 'react-native';
+
+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?;
+    constructor();
+    init(translations: Translations, options?: I18nOptions): void;
+    loadTranslations(translations: Translations): void;
+    updateLocale(): 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;
+    private handleRTL;
+    private notifyListeners;
+    private setLocaleFromSystem;
+    private applyLocale;
+    private translateAtLocale;
+    private getLocaleChain;
+    private hasTranslation;
+    private normalizeTranslateResult;
+    private normalizeLocaleTag;
+    private normalizeTranslations;
+    private isRTLLocale;
+}
+declare const i18nService: DefaultI18nEngine;
+
+interface I18nContextType {
+    locale: string;
+    setLocale: (locale: string) => 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;
+}
+declare const I18nContext: React.Context<I18nContextType>;
+interface I18nProviderProps {
+    children: ReactNode;
+    readyGate?: boolean;
+    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>;
+    locale: string;
+    setLocale: (locale: string) => void;
+    formatNumber: (n: number, options?: Intl.NumberFormatOptions) => string;
+    formatCurrency: (n: number, currency: string, options?: Intl.NumberFormatOptions) => string;
+    formatDate: (date: Date | number, options?: Intl.DateTimeFormatOptions) => string;
+};
+
+interface TransProps extends TextProps {
+    i18nKey: string;
+    values?: Record<string, any>;
+    components?: Record<string, ReactNode>;
+}
+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 getLocale: () => string;
+declare const t: (scope: Scope, options?: TranslateOptions) => string;
+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 };