RepoThread Logo
RepoThread
价格

项目总览

相关源文件

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

i18n-pro 是一个开箱即用的轻量级 JavaScript 国际化（i18n）自动翻译解决方案，旨在简化多语言应用的开发流程。该项目通过命令行工具与函数 API 的协同工作，实现了从文本提取、自动翻译到语言包生成的完整工作流，显著降低了国际化的接入成本。

项目的核心愿景是"让国际化变得简单且令人愉快"，通过提供零配置启动、增量翻译、多平台支持等特性，帮助开发者专注于业务逻辑而非繁琐的翻译管理工作。

README.md:1-2 明确了项目定位为轻量级 JavaScript i18n 自动翻译解决方案。README.md:32-33 阐述了项目的愿景声明。

核心特性

轻量级与简单配置

项目在包体积上进行了极致优化，确保对应用性能影响最小化。配置设计遵循"约定优于配置"原则，开发者可快速启动而无需复杂的初始化设置。

灵活的文本处理

支持变量插值，允许在翻译文本中嵌入动态内容。同时引入了独特的类型标签和格式化器，支持数字、货币、日期、时间、复数等多种数据类型的本地化处理。

自动翻译能力

自动翻译是该库的核心特性之一，包含以下子能力：

  • 增量翻译：仅翻译新增文本，自动移除未使用的翻译条目，避免重复工作
  • 多平台支持：集成 Google x、OpenAI、Google、Microsoft、Tencent、Alibaba Cloud、Youdao、Baidu 等多个翻译平台
  • 翻译日志：提供多种日志输出，便于问题追踪和调试

无 Key 设计

采用 text-as-key（文本即 Key）模式，开发者无需维护额外的 Key 映射表。在特定场景（如一词多义）下，也支持 custom-key 模式以满足精细化控制需求。

README.md:34-44 详细列出了项目的六大核心特性。README.md:36-43 重点说明了自动翻译功能的子特性。

技术栈

技术领域技术选型说明
运行环境JavaScript支持任意 JavaScript 项目集成
包管理npm通过 npm 分发，包名为 i18n-pro
CLI 工具命令行工具基于正则表达式解析源码文本
翻译服务多平台 API支持 8+ 主流翻译平台
文本匹配正则表达式可配置的匹配规则

系统架构

i18n-pro 的系统架构由两大核心组件构成：命令行工具 和 函数 API。两者相互协作，形成完整的国际化解决方案。

正在加载图表渲染器...

架构说明

  1. 命令行工具：负责从源代码中提取待翻译文本，通过正则表达式匹配 t() 函数调用，调用翻译平台 API 进行翻译，最终生成语言包 JSON 文件
  2. 函数 API：提供运行时国际化支持，initI18n 初始化配置并加载语言包，t 函数包装文本实现翻译，setI18n 动态切换语言
  3. 外部服务：集成多个翻译平台，通过适配器模式屏蔽平台差异

README.md:52-59 说明了系统由命令行工具和函数 API 两大部分组成。README.md:101-106 详细描述了函数 API 的三个核心方法及其职责。

核心模块详解

模块一：命令行工具 - 文本解析器

职责边界：负责从源代码文件中提取所有需要翻译的文本内容，基于可配置的正则表达式规则进行匹配。不负责翻译逻辑本身，仅完成文本提取和去重。

入口与关键 API：

  • 命令行入口：i18n-pro 命令（具体命令名称需要确认）
  • 匹配规则配置：Match Rules

关键数据结构：

  • 输入：源代码文件路径、匹配规则配置
  • 输出：去重后的文本列表，包含文本内容及其位置信息

关键调用链：

  1. 扫描指定目录下的源代码文件
  2. 应用正则表达式匹配 t() 函数调用
  3. 提取函数参数中的文本内容
  4. 去重并生成待翻译文本集合

README.md:60-64 解释了命令行工具如何通过匹配规则解析文本。

模块二：命令行工具 - 翻译引擎

职责边界：负责调用外部翻译平台 API，将提取的文本翻译为目标语言。支持多平台切换和增量翻译策略。

入口与关键 API：

  • 翻译平台配置：支持 Google x、OpenAI、Google、Microsoft、Tencent、Alibaba Cloud、Youdao、Baidu 等平台
  • 增量翻译逻辑：仅翻译新增文本，跳过已翻译内容

关键数据结构：

  • 输入：待翻译文本列表、目标语言列表、平台配置
  • 输出：翻译结果映射表（源文本 -> 翻译文本）

错误处理与边界条件：

  • 翻译 API 调用失败时的重试机制（需要确认具体实现）
  • 网络超时处理
  • API 配额限制处理

README.md:40-42 列出了支持的翻译平台。

模块三：命令行工具 - 语言包生成器

职责边界：负责将翻译结果序列化为语言包文件格式（通常为 JSON），并处理增量更新时的文件合并与清理。

入口与关键 API：

  • 输出文件路径配置
  • 文件格式：JSON 结构

关键数据结构：

  • text-as-key 模式：{ "Hello World": "你好世界" }
  • custom-key 模式：{ "custom-key": "你好世界" }

关键调用链：

  1. 接收翻译引擎的输出结果
  2. 根据模式选择 Key 生成策略
  3. 合并现有语言包（增量更新场景）
  4. 移除未使用的翻译条目
  5. 写入文件系统

README.md:60 说明了命令行工具最终生成语言包文件。

模块四：函数 API - initI18n 初始化模块

职责边界：负责初始化 i18n 配置，加载语言包数据，返回完整的 API 对象（包含 t 和 setI18n 方法）。不负责具体的翻译逻辑。

入口与关键 API：

  • initI18n(config)：初始化函数，接收配置对象
  • 返回值：包含 t 和 setI18n 方法的 API 对象

关键数据结构：

  • 配置对象结构（需要确认具体字段）：
    • 语言包数据
    • 默认语言设置
    • 格式化器配置

关键调用链：

  1. 接收配置参数
  2. 验证配置完整性
  3. 初始化内部状态（当前语言、语言包映射）
  4. 返回 API 对象

README.md:101-102 描述了 initI18n 的职责。

模块五：函数 API - t 翻译函数

职责边界：包装文本实现国际化，同时作为命令行工具的匹配标识符。支持变量插值、类型标签和格式化。

入口与关键 API：

  • t(text, ...args)：text-as-key 模式
  • t.t(key, text, ...args)：custom-key 模式

关键数据结构：

  • 普通字符串：t('Hello World')
  • 变量插值：t('Hi, {0}', 'developer friends')
  • 类型标签：
    • {n0} - 数字
    • {c0} - 货币
    • {d0} - 日期
    • {t0} - 时间
    • {p0 apple} - 复数

关键调用链：

  1. 接收文本和可选参数
  2. 查找当前语言包中的翻译
  3. 应用变量插值和格式化
  4. 返回处理后的字符串

README.md:64-100 展示了两种模式的具体使用示例。

模块六：函数 API - setI18n 语言切换模块

职责边界：负责动态切换当前语言和语言包，触发 UI 更新。

入口与关键 API：

  • setI18n(language, languagePack?)：设置语言和可选的语言包

关键数据结构：

  • 输入：语言标识符（如 'en'、'zh-CN'）、可选的语言包数据
  • 副作用：更新内部状态，可能触发重新渲染

README.md:104 描述了 setI18n 的职责。

关键数据流

以下时序图展示了从文本提取到运行时翻译的完整数据流：

正在加载图表渲染器...

数据流说明

  1. 构建时阶段（CLI 工具）：

    • 开发者执行翻译命令，CLI 工具扫描源代码文件
    • 文本解析器使用正则表达式匹配所有 t() 函数调用
    • 翻译引擎调用外部翻译平台 API 进行批量翻译
    • 语言包生成器将结果序列化为 JSON 文件并写入文件系统

  2. 运行时阶段（函数 API）：

    • 应用启动时调用 initI18n 加载语言包
    • t() 函数根据当前语言查找翻译并应用格式化
    • setI18n() 动态切换语言，触发 UI 更新

README.md:52-59 和 README.md:101-106 共同支撑了上述架构和数据流设计。

文本匹配模式

text-as-key 模式

这是默认且推荐的模式，直接使用文本内容作为 Key，简化了国际化流程：

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

custom-key 模式

在需要精细化控制的场景（如一词多义）下，可以使用自定义 Key：

javascript
1// 使用 t.t() 方法，第一个参数为自定义 Key
2t.t('custom-key', 'Hello World')
3t.t('greeting', 'Hi, {0}', 'developer friends')
4t.t('user-count', 'i18n-pro has reached {n0} users', 100000000)

README.md:64-100 展示了两种模式的完整示例。

适用场景

场景类型适用性说明
Web 应用支持任意 JavaScript 框架
移动应用适用于 React Native、Ionic 等混合开发框架
Node.js 服务端支持服务端渲染（SSR）场景
组件库开发可作为组件库的国际化基础设施
多语言内容平台适合需要频繁更新翻译内容的场景
快速原型开发零配置启动，适合快速验证国际化需求

项目核心能力量化

指标数值/说明
包体积极致轻量（具体数值需参考 Bundlephobia）
支持的翻译平台8+ 个主流平台
核心函数 API3 个
文本匹配模式2 种
支持的类型标签5 种
配置复杂度零配置启动

报告阅读路线图

以下图表展示了本文档各章节的关系与推荐阅读顺序：

正在加载图表渲染器...

阅读建议

  1. 快速入门：按顺序阅读"项目简介与愿景"→"核心特性"→"适用场景"
  2. 深入理解：重点阅读"系统架构"→"核心模块详解"→"关键数据流"
  3. 实践应用：参考"文本匹配模式"进行实际开发

总结

i18n-pro 通过命令行工具与函数 API 的双组件架构，实现了从文本提取、自动翻译到运行时国际化的完整闭环。其核心优势在于：

  1. 极简接入：text-as-key 模式消除了 Key 管理负担
  2. 增量更新：仅翻译新增内容，提升效率
  3. 多平台支持：灵活切换翻译服务提供商
  4. 类型安全：丰富的类型标签支持复数、货币等复杂场景

该项目适合需要快速实现国际化能力的 JavaScript 项目，特别是对翻译自动化有较高要求的团队。