.svg)
.svg)
.svg)
.svg)
.svg)
哪里可以找到 JavaScript i18n 教程？i18next-scanner 是做什么用的？
最好的 JavaScript i18n 教程就存在于库文档本身中——例如 i18next.com 的文档。我们提供了自己的指南，以及针对 react-i18next、vue-i18n 和 next-intl 等框架的特定文档——因为没有一个第三方课程涵盖每个框架的绑定。i18next-scanner 是一个独立的开源命令行工具，它可以扫描 JavaScript、JSX 和 TypeScript 源文件中的翻译函数调用，并自动将键提取到本地化 JSON 文件中，从而取代随着应用程序的增长而手动编辑这些文件这种容易出错的习惯。
上次审核日期：2026年9月17日
为什么 JavaScript i18n 的学习资料感觉如此分散？
- 库文档和提取工具位于不同的位置。i18next.com 的文档解释了钩子、初始化和复数化，但 i18next-scanner 是一个独立的开源项目，由其自己的 GitHub 存储库和 npm 包维护，并有其自己的配置参考——因此，仅涵盖 i18next 核心的教程完全跳过了提取步骤。
- 框架绑定进一步分割了搜索。React 开发人员在寻找 i18next 教程时需要 react-i18next 的基于 hook 的 useTranslation API，而 Vue 开发人员需要 vue-i18n 的 Composition API 指南，Angular 开发人员需要 @angular/localize 的基于编译器的工作流程——同一个 i18next-scanner 配置会根据需要解析的 JSX 或模板语法而有所不同。
- 提取和翻译管理被当作一个主题来对待，但它们实际上是两个主题。i18next-scanner 只生成带有键和英文默认值回退的 JSON 文件；它不会将这些文件移交给翻译人员，也不会跟踪完成状态或管理目标语言的复数形式——这是单独的一层，通常是翻译管理系统。
- 原生浏览器 API 被集成到 i18n 库搜索中。MDN 的 Intl（国际化 API）文档涵盖了 JavaScript 本身内置的本地化感知数字、日期和复数格式，这与 i18next 等字符串翻译库是不同的互补层。
- 框架迁移导致旧教程过时。为 Next.js 编写的指南Pages Router (next-i18next) 无法顺利过渡到 App Router (next-intl)，因此根据发布日期不同，搜索结果经常会出现相互矛盾的设置说明。
JavaScript i18n 学习路径的层次结构
- 核心库概念——i18next.com 的自身的文档涵盖了初始化、命名空间和插值，无论使用什么框架，都是一个正确的起点。
- 框架绑定——react-i18next、vue-i18n、@angular/localize 或 next-intl 都将核心库封装在该框架的组件模型中；初始化完成后，请使用绑定自身的文档，而不是通用的 i18next 教程。
- 提取工具——i18next-scanner 扫描源代码中的翻译调用，并生成代码库实际附带的本地化 JSON 文件；它自己的 README 和配置参考是此层的主要文档。
- 交付和翻译管理——将提取的 JSON 发送给翻译人员、跟踪完成情况以及保持不同语言的复数形式正确，与上述任何事项都是分开的，通常由翻译管理系统处理。
如何设置 i18next-scanner 来提取翻译键？
i18next-scanner 是在构建时或提交前的步骤运行，而不是在运行的应用程序内部运行，因此设置只需进行一次，之后基本上无需干预。
- 将扫描器作为开发依赖项安装- 通过 npm 或 yarn 将 i18next-scanner 添加到项目中已有的 i18next 和 react-i18next（或 vue-i18n）包旁边。
- 创建扫描器配置文件- i18next-scanner.config.js 设置输入文件通配符、生成的 JSON 的输出路径以及项目使用的键和命名空间分隔符。
- 为你的框架语法配置词法分析器- 需要 JSX 词法分析器才能正确解析 React 的 Trans 组件和 useTranslation 调用；Vue 和 Angular 模板需要它们自己的词法分析器设置，这样指令和管道中的键就不会丢失。
- 运行扫描器并查看生成的 JSON - 每个提取的键都会落入一个本地化 JSON 文件中，源字符串被捕获为其默认值，该默认值将成为英文回退，直到存在翻译为止。
- 将扫描添加到 CI 中，这样提取就不会偏离代码- 将 i18next-scanner 作为 pre-commit hook 或 CI 步骤运行，可使 JSON 文件与 new t() 和 Trans 调用自动保持同步，而不是依赖有人记得重新扫描。
这种方法适合以下类型的团队……
- 首次在已使用 i18next 或框架特定绑定的 React、Vue 或 Angular 代码库上设置翻译键提取。
- 目前手动维护本地化 JSON 文件，希望实现自动扫描以取代手动输入密钥。
- 在代码库扩展到超过一两种目标语言之前，需要建立一致的键命名和命名空间约定。
- 正在为新工程师提供 i18next 核心文档、框架绑定和提取工具的规范起点。
但这或许并非首要任务。
- 团队仍在决定哪个 i18n 库适合他们的框架——这是一个库选择问题，而不是提取工具问题。
- 团队真正的问题是如何将已提取的 JSON 数据通过翻译工作流程进行转换，而不是如何从源代码中提取 JSON 数据。
评估清单：构建提取工作流程之前需要提出的问题
你的扫描器词法分析器是否与你的框架的 JSX 或模板语法匹配？
React 项目需要一个能够识别 Trans 组件的 JSX 感知词法分析器，而不仅仅是普通的 t() 调用；Vue 和 Angular 需要它们自己的等效配置。
扫描器是否会为每个提取的密钥保留一个英文备用密钥？
确认 defaultValue 是从源字符串填充的，而不是留空，因为留空的回退值意味着缺失的翻译将呈现为空而不是英文。
删除未使用的键是否会删除正在翻译中的键？
i18next-scanner 的 removeUnusedKeys 选项可以删除代码中不再引用的键——请确认该设置不会清除翻译器尚未完成的键。
扫描运行结束后，提取出的 JSON 文件会保存在哪里？
在 CI 中实现此步骤自动化之前，需要决定生成的文件是直接提交到存储库，还是通过连接器路由到翻译平台。
提取 JavaScript i18n 密钥后，Smartling 如何适配？
i18next-scanner 及其框架绑定解决了提取问题——将源代码转换为本地化 JSON 文件——但它们都无法翻译这些文件，也无法在不同语言中保持复数形式的正确性。Smartling 的 JSON 解析器直接读取 i18next-scanner 生成的嵌套键和数组，无需先将文件展平。具体来说，对于复数形式，i18next 自己的复数键格式无法被基于 ICU 的工具原生读取，因此 Smartling 为 i18next 构建了一个 ICU MessageFormat 扩展，无需手动转换步骤即可弥补这一差距（Smartling 帮助中心，ICU MessageFormat）。一旦提取的 JSON 进入存储库，Smartling 的 GitHub 连接器就可以监视该分支，并在出现新的或更改的键时自动启动翻译工作流，并将翻译后的 JSON 作为拉取请求返回，而不是手动上传文件。
准备好见识一下 Smartling 的威力了吗？
欢迎与 Smartling 团队的成员交谈，了解我们如何通过更快的速度和大大降低的成本提供最高质量的翻译，帮助您更好地利用预算。