react-native-i18njs 0.0.1-beta → 0.0.2

package/README.md

@@ -1,39 +1,234 @@
 # react-native-i18njs
 
-#### 介绍
-{**以下是 Gitee 平台说明，您可以替换此简介**
-Gitee 是 OSCHINA 推出的基于 Git 的代码托管平台（同时支持 SVN）。专为开发者提供稳定、高效、安全的云端软件开发协作平台
-无论是个人、团队、或是企业，都能够用 Gitee 实现代码托管、项目管理、协作开发。企业项目请看 [https://gitee.com/enterprises](https://gitee.com/enterprises)}
+[![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 以及系统语言跟随问题。
 
-#### 安装教程
+## ✨ 特性
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+- � **零配置启动**：内置智能默认值，安装即用。
+- 🛡️ **极致类型安全**：完全 TypeScript 编写，提供从 Key 到插值参数的完整类型推导。
+- 📱 **自动跟随系统**：基于 `react-native-localize`，自动检测并响应设备语言变更。
+- ⚡ **高性能**：基于 `i18n-js` 核心，轻量高效，无多余运行时开销。
+- 🔌 **灵活 API**：同时支持 Hook (`useI18n`)、高阶组件 (`withTranslation`) 和全局函数 (`t`)。
+- 📝 **富文本支持**：`Trans` 组件轻松处理嵌套样式和组件插值。
+- 🌍 **格式化内置**：开箱即用的数字、货币、日期格式化支持。
 
-#### 使用说明
+## 📦 安装
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+```bash
+npm install react-native-i18njs
+# 或者
+yarn add react-native-i18njs
+```
 
-#### 参与贡献
+> **注意**：本库已内置 `i18n-js` 和 `react-native-localize` 的稳定版本，无需手动安装 peer dependencies。
 
-1.  Fork 本仓库
-2.  新建 Feat_xxx 分支
-3.  提交代码
-4.  新建 Pull Request
+## 🚀 快速开始
 
+### 1. 定义翻译资源
 
-#### 特技
+建议在单独的文件中管理翻译资源，例如 `src/locales/index.ts`：
 
-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
+// src/locales/index.ts
+export const translations = {
+  en: {
+    welcome: 'Welcome',
+    hello: 'Hello, %{name}!',
+  },
+  zh: {
+    welcome: '欢迎',
+    hello: '你好，%{name}！',
+  },
+};
+
+// 导出类型以获得类型提示
+export type Translations = typeof translations.en;
+```
+
+### 2. 初始化
+
+在你的 App 入口文件（如 `App.tsx`）中初始化：
+
+```tsx
+import React from 'react';
+import { initI18n, I18nProvider } from 'react-native-i18njs';
+import { translations } from './src/locales';
+import Home from './src/Home';
+
+// 初始化配置
+initI18n(translations, {
+  defaultLocale: 'en',
+  enableFallback: true, // 找不到翻译时回退到默认语言
+});
+
+export default function App() {
+  return (
+    // 使用 Provider 以支持语言切换时的自动重渲染
+    <I18nProvider>
+      <Home />
+    </I18nProvider>
+  );
+}
+```
+
+### 3. 在组件中使用
+
+```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';
+
+export default function Home() {
+  // 传入泛型 Translations 以获得 key 的自动补全和类型检查
+  const { t, locale, setLocale } = useI18n<Translations>();
+
+  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>
+  );
+}
+```
+
+## 📖 核心功能详解
+
+### 1. 非组件环境使用（Global API）
+
+在 Redux、Axios 拦截器、工具函数等非组件环境中，你可以直接使用全局导出的 API。
+
+#### 基础用法
+
+```ts
+import { t, getLocale, setLocale } from 'react-native-i18njs';
+
+// 获取当前语言
+const current = getLocale();
+
+// 切换语言
+setLocale('zh');
+
+// 直接翻译
+const message = t('errors.network_timeout');
+```
+
+#### 进阶：监听语言变化
+
+如果你需要在组件外监听语言变更（例如同步更新全局状态），可以使用默认导出的实例：
+
+```ts
+import i18n from 'react-native-i18njs';
+
+// 订阅语言变更
+const unsubscribe = i18n.subscribe((locale) => {
+  console.log('Language changed to:', locale);
+  // 更新 API 默认 Header 或其他全局状态
+});
+
+// 取消订阅
+// unsubscribe();
+```
+
+#### 实战示例：Axios 拦截器
+
+```ts
+import axios from 'axios';
+import { getLocale } from 'react-native-i18njs';
+
+axios.interceptors.request.use((config) => {
+  // 动态获取当前语言，确保每次请求都携带最新的语言标识
+  config.headers['Accept-Language'] = getLocale();
+  return config;
+});
+```
+
+### 2. 富文本翻译 (`Trans` 组件)
+
+当翻译内容中包含样式或组件时，使用 `Trans` 组件：
+
+```tsx
+import { Trans } from 'react-native-i18njs';
+import { Text } from 'react-native';
+
+// 翻译资源:
+// zh: { agreement: '我同意 <link>服务条款</link>' }
+
+<Trans
+  i18nKey="agreement"
+  components={{
+    link: <Text style={{ color: 'blue' }} onPress={openTerms} />,
+  }}
+/>
+```
+
+### 3. 动态加载翻译
+
+适用于大型应用的分包加载场景：
+
+```ts
+import { loadTranslations } from 'react-native-i18njs';
+
+// 异步加载法语包
+async function loadFrench() {
+  const fr = await import('./locales/fr');
+  loadTranslations({ fr: fr.default });
+}
+```
+
+### 4. 格式化工具
+
+利用 `Intl` 标准进行格式化：
+
+```ts
+const { formatNumber, formatCurrency, formatDate } = useI18n();
+
+// 数字
+formatNumber(1234.56); // "1,234.56"
+
+// 货币
+formatCurrency(99.99, 'USD'); // "$99.99"
+
+// 日期
+formatDate(new Date(), { dateStyle: 'full' }); // "Tuesday, October 10, 2023"
+```
+
+## ⚙️ 配置选项 (I18nOptions)
+
+`initI18n` 接受的第二个参数对象：
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `defaultLocale` | `string` | `'en'` | 默认语言 |
+| `enableFallback` | `boolean` | `true` | 是否启用回退机制 |
+| `followSystem` | `boolean` | `true` | 是否初始化时自动跟随系统语言 |
+| `fallbackLocales` | `string[]` \| `func` | - | 自定义回退链 |
+| `missingBehavior` | `'key'` \| `'empty'` \| `'throw'` | `'key'` | 缺失翻译时的行为 |
+| `onMissingKey` | `function` | - | 缺失 key 的回调 |
+| `onLocaleChange` | `function` | - | 语言变更回调 |
+
+## 🧩 常见问题
+
+### TypeScript 类型提示不工作？
+确保你在使用 `useI18n<MyTranslations>()` 时传入了你的翻译类型定义。
+
+### 安卓上语言检测不准确？
+请确保你的 `android/app/src/main/res` 目录下有对应的语言资源文件夹（如 `values-zh`），React Native 有时依赖这些原生配置来正确识别系统语言。
+
+## 📄 License
+
+ISC

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 };