快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• src/lib/index.ts
• template/i18nrc.js
• template/i18nrc.ts
• src/lib/type.ts
• src/type.ts
• test/utils.ts
• src/lib/utils.ts
• src/lib/constants.ts
• src/bin/i18n.ts

i18n-pro 是一个轻量级、开箱即用的 JavaScript 国际化自动翻译解决方案，旨在让国际化变得简单而愉悦。该项目支持变量插值、类型标签和格式化器等灵活特性，并提供自动翻译功能，支持增量翻译和多平台翻译服务（如 Google X、OpenAI、百度、有道等）。项目采用"文本即 Key"的设计理念，在特定场景（如多义词）下也支持自定义 Key（README.md:1-44）。

项目由命令行工具和函数 API 两大部分组成。命令行工具负责根据指定规则（正则表达式）解析需要翻译的文本，使用支持的翻译平台进行翻译，最终生成语言包文件。函数 API 则通过 initI18n、t 和 setI18n 提供多语言支持，两者配合可轻松集成到任何 JavaScript 项目中（README.md:52-106）。

环境要求

该项目是一个纯 JavaScript/TypeScript 解决方案，需要在 Node.js 环境中运行。根据配置文件模板分析，项目支持 CommonJS 和 ES Module 两种模块格式。

基础环境：

• Node.js（建议版本需要确认，查看 package.json 中的 engines 字段）
• npm、yarn 或 pnpm 包管理器

可选依赖：

• TypeScript（如果使用 .ts 配置文件）
• 翻译平台 API 密钥（根据选择的翻译服务配置）

安装步骤

通过 npm 安装

使用 npm 安装 i18n-pro 作为项目依赖：

bash
1npm install i18n-pro

通过 yarn 安装

bash
1yarn add i18n-pro

通过 pnpm 安装

bash
1pnpm add i18n-pro

安装完成后，需要在项目根目录创建配置文件。项目支持 JavaScript 和 TypeScript 两种配置格式。

配置文件创建

JavaScript 配置格式

创建 i18nrc.js 文件，使用 CommonJS 模块导出配置对象。配置文件模板示例如下（template/i18nrc.js:1-20）：

javascript
1const { join } = require('path')
2
3module.exports = {
4  funcName: 't',
5  // entry: join(__dirname, './src/'),
6  // fileRegExp: /\.[jt]s$/,
7  input: 'src/**/*.{js,ts}',
8  output: {
9    path: join(__dirname, './i18n/'),
10  },
11  translator: 'googlex',
12  googlexConfig: {
13    from: 'en',
14    to: ['zh-CN', 'ja'],
15    codeLocaleMap: {
16      'zh-CN': 'zh',
17    },
18    // proxy: 'http://127.0.0.1:1087',
19  },
20}

TypeScript 配置格式

创建 i18nrc.ts 文件，使用 ES Module 语法导出配置。TypeScript 配置需要导入 Config 类型以获得类型提示（template/i18nrc.ts:1-25）：

typescript
1import { fileURLToPath } from 'node:url'
2import { join, dirname } from 'node:path'
3import { Config } from '../src/type'
4
5const __filename = fileURLToPath(import.meta.url)
6const __dirname = dirname(__filename)
7
8export default {
9  funcName: 't',
10  input: 'src/**/*.{js,ts}',
11  output: {
12    path: join(__dirname, './i18n/'),
13  },
14  translator: 'googlex',
15  googlexConfig: {
16    from: 'en',
17    to: ['zh-CN', 'ja'],
18    codeLocaleMap: {
19      'zh-CN': 'zh',
20    },
21  },
22} as Config

核心配置参数说明

配置参数定义在 src/type.ts 中，主要包括以下字段（src/type.ts:1-72）：

最短可运行路径

步骤一：初始化国际化配置

在应用入口文件中导入 initI18n 函数并初始化配置。initI18n 函数接收 I18nState 状态对象，返回包含 setI18n 和 t 的 API 对象（src/lib/index.ts:51-77）：

typescript
1import { initI18n } from 'i18n-pro'
2
3const { t, setI18n } = initI18n({
4  namespace: 'my-app',
5  locale: 'en',
6  langs: {
7    en: {
8      'Hello World': 'Hello World',
9    },
10    'zh-CN': {
11      'Hello World': '你好世界',
12    },
13  },
14})

initI18n 函数支持配置命名空间、起始索引、格式化回调等高级选项。如果命名空间已存在，会在控制台输出错误信息（src/lib/index.ts:55-68）。

步骤二：使用翻译函数

使用 t 函数包裹需要翻译的文本。项目支持"文本即 Key"模式，直接使用原始文本作为键值（README.md:64-100）：

javascript
1// 普通字符串
2t('Hello World')
3
4// 变量插值
5t('Hi, {0}', 'developer friends')
6
7// 类型标签 - 数字
8t('i18n-pro has reached {n0} users', 100000000)
9
10// 类型标签 - 货币
11t('The selling price is {c0}', 14999)
12
13// 类型标签 - 日期
14t(`Today's date is {d0}`, new Date())
15
16// 类型标签 - 时间
17t('Current time: {t0}', new Date())
18
19// 类型标签 - 复数
20t('I have {p0 apple}, {p1 banana} and {p2 pear}', 5, 4, 3)

对于需要自定义 Key 的场景（如多义词），可以使用 t.t 方法（README.md:83-100）：

javascript
1// 自定义 Key 模式
2t.t('custom-key', 'Hello World')
3t.t('custom-key', 'Hi, {0}', 'developer friends')

步骤三：动态切换语言

使用 setI18n 函数动态切换语言或更新语言包。该函数支持异步加载语言包（src/lib/index.ts:5-49）：

typescript
1// 切换语言
2await setI18n({ locale: 'zh-CN' })
3
4// 动态加载语言包
5await setI18n({
6  locale: 'ja',
7  langs: {
8    ja: async () => {
9      const lang = await import('./i18n/ja.json')
10      return lang.default
11    },
12  },
13})

setI18n 函数会检查语言包是否为函数类型，如果是则异步加载并缓存加载结果。如果加载失败，会在控制台输出错误信息（src/lib/index.ts:24-34）。

运行验证

验证翻译功能

创建测试文件验证翻译功能是否正常工作：

javascript
1import { initI18n } from 'i18n-pro'
2
3const { t, setI18n } = initI18n({
4  namespace: 'test',
5  locale: 'en',
6  langs: {
7    en: { greeting: 'Hello' },
8    'zh-CN': { greeting: '你好' },
9  },
10})
11
12console.log(t('greeting')) // 输出: Hello
13
14setI18n({ locale: 'zh-CN' }).then(() => {
15  console.log(t('greeting')) // 输出: 你好
16})

验证命令行工具

运行命令行工具提取和翻译文本（命令行入口文件位于 src/bin/i18n.ts，具体命令需要确认）：

bash
1# 建议命令（需要确认 package.json 中的 bin 配置）
2npx i18n-pro

预期输出包括翻译日志和生成的语言包文件。翻译日志可以帮助追踪翻译过程中的问题（README.md:42）。

常见问题与排错

问题一：命名空间冲突

现象：控制台输出 Namespace 'xxx' already exists. 错误信息。

原因：重复调用 initI18n 初始化同一个命名空间。

解决方案：确保每个命名空间只初始化一次，或使用不同的命名空间名称。错误信息在 initI18n 函数中输出（src/lib/index.ts:58-60）。

问题二：语言包加载失败

现象：控制台输出 Failed to load language pack for 'xxx' 错误信息。

原因：动态语言包函数返回的值不是有效对象。

解决方案：确保异步加载函数返回 Promise 且解析值为对象类型。setI18n 函数会验证加载结果是否为对象（src/lib/index.ts:29-33）。

问题三：beginIndex 类型错误

现象：控制台输出 beginIndex must be a number. 错误信息。

原因：beginIndex 配置项类型不正确。

解决方案：确保 beginIndex 为数字类型或未定义。initI18n 函数会进行类型检查并删除无效配置（src/lib/index.ts:62-68）。

问题四：翻译平台配置错误

现象：命令行工具无法正常翻译文本。

原因：翻译平台配置不完整或 API 密钥无效。

解决方案：检查配置文件中的 translator 和对应平台的配置项。例如使用 googlex 翻译器时，需要配置 googlexConfig（template/i18nrc.js:11-19）。如需代理，取消注释 proxy 配置项。

API 概览

核心 API 类型定义

项目导出的核心 API 类型定义在 src/lib/type.ts 中（src/lib/type.ts:105-157）：

SetI18n 类型：设置或更新国际化状态的函数类型，接收可选的 locale 和 langs 参数，返回 Promise 包装的只读 I18nState。

Translate 接口：翻译函数接口，除基础翻译功能外，还包含以下方法：

• t(key, text, ...args)：使用自定义 Key 获取翻译文本
• withLocale(locale?)：返回绑定指定 locale 的新翻译函数

I18nState 状态结构

I18nState 定义了国际化状态的完整结构（src/lib/type.ts:26-103）：

格式化回调函数用于处理翻译文本中的类型标签。例如配置了 {n0} 形式的动态参数时，必须配置 formatNumber 回调（src/lib/type.ts:47-54）。

下一步建议

完成快速上手后，建议进一步了解以下内容：

1. 命令行详细用法：查阅命令行文档了解更多提取规则和翻译选项
2. 匹配规则：学习如何自定义正则表达式匹配需要翻译的文本
3. 翻译日志：了解如何通过日志输出追踪翻译问题
4. 多平台配置：配置不同的翻译平台（百度、有道、腾讯、阿里云、微软、Google、OpenAI 等）

详细文档链接可在 README 的帮助文档部分找到（README.md:107-116）。