react-native-i18njs 0.0.1 → 0.0.2

package/README.md

@@ -1,97 +1,76 @@
 # react-native-i18njs
 
+[![npm version](https://img.shields.io/npm/v/react-native-i18njs.svg)](https://www.npmjs.com/package/react-native-i18njs)
+[![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)
+
 一个轻量级、类型安全、零心智负担的 React Native 国际化解决方案。
 
-## 特性
+专为 React Native 设计，集成了最佳实践，解决了常见的国际化痛点：繁琐的配置、类型缺失、复杂的 API 以及系统语言跟随问题。
 
-- 🚀 **开箱即用**：专为 React Native 设计，API 简单直观。
-- 📦 **自动语言检测**：基于 `react-native-localize` 自动匹配设备语言。
-- 🔄 **自动重渲染**：语言切换时，UI 自动更新。
-- 🛡️ **TypeScript 支持**：完全使用 TypeScript 编写，提供完整的类型提示。
-- 🧩 **基于 `i18n-js`**：轻量封装，默认使用 `i18n-js` 作为翻译引擎。
-- 🔌 **Hooks 支持**：提供 `useI18n` Hook，方便在组件中使用。
-- 📝 **富文本支持**：支持在翻译中嵌入组件。
-- 🔢 **格式化支持**：基于 JS 内置 `Intl` 的数字/货币/日期格式化（可传 options 自定义；环境不支持会自动降级）。
+## ✨ 特性
 
-## 安装
+- � **零配置启动**：内置智能默认值，安装即用。
+- 🛡️ **极致类型安全**：完全 TypeScript 编写，提供从 Key 到插值参数的完整类型推导。
+- 📱 **自动跟随系统**：基于 `react-native-localize`，自动检测并响应设备语言变更。
+- ⚡ **高性能**：基于 `i18n-js` 核心，轻量高效，无多余运行时开销。
+- 🔌 **灵活 API**：同时支持 Hook (`useI18n`)、高阶组件 (`withTranslation`) 和全局函数 (`t`)。
+- 📝 **富文本支持**：`Trans` 组件轻松处理嵌套样式和组件插值。
+- 🌍 **格式化内置**：开箱即用的数字、货币、日期格式化支持。
 
-首先安装本库及其依赖：
+## 📦 安装
 
 ```bash
-npm install react-native-i18njs i18n-js react-native-localize
+npm install react-native-i18njs
 # 或者
-yarn add react-native-i18njs i18n-js react-native-localize
+yarn add react-native-i18njs
 ```
 
-> 插值语法说明：本库基于 `i18n-js`，默认使用 `%{name}`（不是 `{{name}}`）。
-
-## 上手方式（两种都支持）
+> **注意**：本库已内置 `i18n-js` 和 `react-native-localize` 的稳定版本，无需手动安装 peer dependencies。
 
-- **方式 A：不使用 `I18nProvider`（推荐）**：任何地方都能直接 `t()`，没有 React 心智负担；适合工具层/启动阶段/非 UI 代码。
-- **方式 B：使用 `I18nProvider`（可选）**：需要“切换语言后 UI 自动刷新”时再用。
+## 🚀 快速开始
 
-## 模块 1：初始化与全局函数（不需要 Provider）
+### 1. 定义翻译资源
 
-### 1) 准备翻译资源
+建议在单独的文件中管理翻译资源，例如 `src/locales/index.ts`：
 
 ```ts
+// src/locales/index.ts
 export const translations = {
-  en: { welcome: 'Welcome', hello: 'Hello, %{name}!' },
-  zh: { welcome: '欢迎', hello: '你好，%{name}！' },
+  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: '默认文案' });
+// 导出类型以获得类型提示
+export type Translations = typeof translations.en;
 ```
 
-### 不用 Provider 的典型场景
-
-- 网络层（如 axios 拦截器）拼接错误文案
-- 表单校验/工具函数/Toast 文案
-- Redux/Saga/Store 初始化阶段
-- React 组件之外（比如 navigation 配置、原生桥接回调）
-
-> 注意：不用 Provider 时，切换语言不会自动触发页面重渲染；如果你需要 UI 自动刷新，请看“模块 2”。
+### 2. 初始化
 
-## 模块 2：React 自动重渲染（I18nProvider + useI18n）
+在你的 App 入口文件（如 `App.tsx`）中初始化：
 
 ```tsx
 import React from 'react';
-import { Text, Button } from 'react-native';
-import { I18nProvider, useI18n } from 'react-native-i18njs';
+import { initI18n, I18nProvider } from 'react-native-i18njs';
+import { translations } from './src/locales';
+import Home from './src/Home';
 
-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')} />
-    </>
-  );
-}
+// 初始化配置
+initI18n(translations, {
+  defaultLocale: 'en',
+  enableFallback: true, // 找不到翻译时回退到默认语言
+});
 
 export default function App() {
   return (
+    // 使用 Provider 以支持语言切换时的自动重渲染
     <I18nProvider>
       <Home />
     </I18nProvider>
@@ -99,149 +78,157 @@ export default function App() {
 }
 ```
 
-### `I18nProvider` 参数
+### 3. 在组件中使用
 
-- `readyGate?: boolean`：为 `true` 时，未 ready 前不渲染 children
-- `fallback?: React.ReactNode`：`readyGate` 期间显示的占位
+```tsx
+// src/Home.tsx
+import React from 'react';
+import { Text, Button, View } from 'react-native';
+import { useI18n } from 'react-native-i18njs';
+import { Translations } from './locales';
 
-### `useI18n<T>()`（类型安全 key）
+export default function Home() {
+  // 传入泛型 Translations 以获得 key 的自动补全和类型检查
+  const { t, locale, setLocale } = useI18n<Translations>();
 
-```ts
-type MyTranslations = typeof translations.en;
-const { t } = useI18n<MyTranslations>();
-t('welcome');
-t('home.title');
+  return (
+    <View>
+      <Text>{t('welcome')}</Text>
+      {/* 这里的 name 参数会有类型提示 */}
+      <Text>{t('hello', { name: 'Trae' })}</Text>
+      
+      <Text>当前语言: {locale}</Text>
+      
+      <Button title="Switch to English" onPress={() => setLocale('en')} />
+      <Button title="切换到中文" onPress={() => setLocale('zh')} />
+    </View>
+  );
+}
 ```
 
-## 模块 3：动态加载翻译（loadTranslations）
+## 📖 核心功能详解
 
-```ts
-import { loadTranslations } from 'react-native-i18njs';
+### 1. 非组件环境使用（Global API）
 
-loadTranslations({ fr: { welcome: 'Bonjour' } });
-```
+在 Redux、Axios 拦截器、工具函数等非组件环境中，你可以直接使用全局导出的 API。
 
-## 模块 4：富文本（Trans）
+#### 基础用法
 
-```tsx
-import React from 'react';
-import { Text } from 'react-native';
-import { Trans } from 'react-native-i18njs';
+```ts
+import { t, getLocale, setLocale } from 'react-native-i18njs';
+
+// 获取当前语言
+const current = getLocale();
 
-// translations.en:
-// { description: 'This is <bold>bold</bold> text.', agree: 'I agree to %{terms}' }
+// 切换语言
+setLocale('zh');
 
-<Trans i18nKey="description" components={{ bold: <Text style={{ fontWeight: 'bold' }} /> }} />
-<Trans i18nKey="agree" values={{ terms: <Text style={{ fontWeight: 'bold' }}>Terms</Text> }} />
+// 直接翻译
+const message = t('errors.network_timeout');
 ```
 
-### `Trans` 参数
+#### 进阶：监听语言变化
+
+如果你需要在组件外监听语言变更（例如同步更新全局状态），可以使用默认导出的实例：
 
-- `i18nKey: string`
-- `values?: Record<string, any>`：插值值（字符串/数字/ReactElement 都支持）
-- `components?: Record<string, React.ReactNode>`：标签映射（如 `bold/link`）
+```ts
+import i18n from 'react-native-i18njs';
 
-### `Trans` 能覆盖的场景
+// 订阅语言变更
+const unsubscribe = i18n.subscribe((locale) => {
+  console.log('Language changed to:', locale);
+  // 更新 API 默认 Header 或其他全局状态
+});
 
-- 句子内局部加粗/斜体/变色/可点击链接（用 `components` 映射 `<bold></bold>` / `<link></link>`）
-- 插值里插入组件（用 `values` 传 ReactElement，例如把 “Terms” 做成可点击文本）
-- 嵌套标签（例如 `<bold>...<italic>...</italic>...</bold>`）
-- 自闭合标签（例如 `<br/>`），可映射成 `components={{ br: <Text>{'\n'}</Text> }}`
+// 取消订阅
+// unsubscribe();
+```
 
-### `Trans` 的边界（不适合的场景）
+#### 实战示例：Axios 拦截器
+
+```ts
+import axios from 'axios';
+import { getLocale } from 'react-native-i18njs';
+
+axios.interceptors.request.use((config) => {
+  // 动态获取当前语言，确保每次请求都携带最新的语言标识
+  config.headers['Accept-Language'] = getLocale();
+  return config;
+});
+```
 
-- 不支持标签属性/HTML（例如 `<a href="...">` / `<span style="...">`），需要你把“样式/点击行为”放到 `components` 或 `values` 传入的组件里
-- `components` 目前接收的是“元素”（例如 `<Text />`），不是组件函数（例如 `Text` / `Bold`），因为内部是 `cloneElement`
-- `Trans` 总是返回一个外层 `<Text>`；并且被插入的组件也必须是 `Text` 可渲染的内容（不要把 `<View>` 直接塞进文本里）
-- 不提供 ICU MessageFormat（select/plural/gender）语法；更复杂的语言结构建议拆 key + 用 JS 逻辑组合，或引入 ICU 方案
-- 翻译里如果出现不成对/不匹配的标签，会按纯文本保留（避免静默吞字），建议在翻译侧保持标签成对
+### 2. 富文本翻译 (`Trans` 组件)
 
-## 模块 5：Class 组件（withI18n）
+当翻译内容中包含样式或组件时，使用 `Trans` 组件：
 
 ```tsx
-import React from 'react';
+import { Trans } from 'react-native-i18njs';
 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>;
-  }
-}
+// 翻译资源:
+// zh: { agreement: '我同意 <link>服务条款</link>' }
 
-export default withI18n(Screen);
+<Trans
+  i18nKey="agreement"
+  components={{
+    link: <Text style={{ color: 'blue' }} onPress={openTerms} />,
+  }}
+/>
 ```
 
-## 模块 6：初始化就绪（readyI18n / isI18nReady）
+### 3. 动态加载翻译
+
+适用于大型应用的分包加载场景：
 
 ```ts
-import { readyI18n, isI18nReady } from 'react-native-i18njs';
+import { loadTranslations } from 'react-native-i18njs';
 
-await readyI18n();
-isI18nReady();
+// 异步加载法语包
+async function loadFrench() {
+  const fr = await import('./locales/fr');
+  loadTranslations({ fr: fr.default });
+}
 ```
 
-## 模块 7：数字/货币/日期格式化（formatNumber / formatCurrency / formatDate）
-
-`Intl` 是 JavaScript 自带的一套“国际化格式化”能力（浏览器和 Node 都有，React Native 取决于引擎/是否带完整 Intl）。
+### 4. 格式化工具
 
-这三个方法基于 `Intl`，默认使用“当前 locale”来格式化，并且都支持传入 `options` 自定义格式。
+利用 `Intl` 标准进行格式化：
 
 ```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' });
-```
-
-通用性边界：
+// 数字
+formatNumber(1234.56); // "1,234.56"
 
-- 若运行环境没有完整 `Intl`（部分 RN/Hermes 场景），库会自动降级：
-  - number：`String(n)`
-  - currency：``${n} ${currency}``
-  - date：`toISOString()`
-- 如果你希望所有平台表现完全一致，请在你的 App 侧引入 `Intl` polyfill。
-- 如果你想用“非当前 locale”做格式化，请直接使用 `new Intl.NumberFormat('xx', options)` 自行处理。
+// 货币
+formatCurrency(99.99, 'USD'); // "$99.99"
 
-## 配置参数（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`：语言变更回调
+// 日期
+formatDate(new Date(), { dateStyle: 'full' }); // "Tuesday, October 10, 2023"
+```
 
-## API 速查（按模块）
+## ⚙️ 配置选项 (I18nOptions)
 
-- **初始化/函数**
-  - `initI18n`, `t`, `setLocale`, `getLocale`, `loadTranslations`, `readyI18n`, `isI18nReady`
-- **React 绑定（可选）**
-  - `I18nProvider`, `useI18n`, `I18nContext`, `withI18n`
-- **组件**
-  - `Trans`
-- **类型**
-  - `I18nOptions`, `Translations`, `Path`
-- **默认导出**
-  - `i18nService`：服务单例（`formatNumber/formatCurrency/formatDate/subscribe/updateLocale` 等）
+`initI18n` 接受的第二个参数对象：
 
-## 常见问题
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `defaultLocale` | `string` | `'en'` | 默认语言 |
+| `enableFallback` | `boolean` | `true` | 是否启用回退机制 |
+| `followSystem` | `boolean` | `true` | 是否初始化时自动跟随系统语言 |
+| `fallbackLocales` | `string[]` \| `func` | - | 自定义回退链 |
+| `missingBehavior` | `'key'` \| `'empty'` \| `'throw'` | `'key'` | 缺失翻译时的行为 |
+| `onMissingKey` | `function` | - | 缺失 key 的回调 |
+| `onLocaleChange` | `function` | - | 语言变更回调 |
 
-### 1) `Invalid hook call` / 多个 React 实例
+## 🧩 常见问题
 
-如果你在 monorepo / workspace 中把本库以源码方式链接到示例或业务 App，可能出现重复 React 导致的 Hook 报错。参考本仓库示例的 Metro 配置做依赖指向与屏蔽：
+### TypeScript 类型提示不工作？
+确保你在使用 `useI18n<MyTranslations>()` 时传入了你的翻译类型定义。
 
-- 示例配置：[example/metro.config.js](./example/metro.config.js)
+### 安卓上语言检测不准确？
+请确保你的 `android/app/src/main/res` 目录下有对应的语言资源文件夹（如 `values-zh`），React Native 有时依赖这些原生配置来正确识别系统语言。
 
-## 平台支持
+## 📄 License
 
-- **iOS / Android**: 完全支持。
-- **Web**: 需要配置 `webpack` 以支持 `react-native-localize`。请参考 [react-native-localize 文档](https://github.com/zoontek/react-native-localize)。
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-i18njs",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "一个轻量级、类型安全、零心智负担的 React Native 国际化解决方案。",
   "repository": {
     "type": "git",
@@ -32,11 +32,13 @@
     "build": "tsup",
     "prepack": "npm run build"
   },
+  "dependencies": {
+    "i18n-js": "^4.5.1",
+    "react-native-localize": "^3.6.1"
+  },
   "peerDependencies": {
-    "i18n-js": ">=4 <5",
     "react": ">=16.8",
-    "react-native": ">=0.64",
-    "react-native-localize": ">=3 <4"
+    "react-native": ">=0.64"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -44,11 +46,9 @@
     "@types/react-native": "^0.72.8",
     "@types/react-test-renderer": "^19.1.0",
     "esbuild": "^0.25.0",
-    "i18n-js": "^4.5.1",
     "jest": "^30.2.0",
     "react": "^19.2.3",
     "react-native": "^0.83.1",
-    "react-native-localize": "^3.6.1",
     "react-native-web": "^0.20.0",
     "react-test-renderer": "^19.2.3",
     "ts-jest": "^29.4.6",