AutoI18n - One click update NextJs project i18n

1- 介绍

2- 什么是 AutoI18n For NextJs？

AutoI18n For NextJs 是一款桌面应用程序，旨在一键完成 Next.js 项目的国际化处理。

它支持集成next-intl库、重构代码结构、自动解析标签生成国际化 JSON 文件、多语言翻译、编辑现有 JSON 文件，并支持增量处理代码的国际化。

3- 解决的问题

1. 1- 手动集成多语言时间长，容易出错

手动集成多语言通常耗时且容易失败，原因是对用法不熟悉或者细节繁多。

1.1 1.1- 手动过程：

  1. 查阅next-intl库文档，学习如何集成。
  2. 在项目中手动添加必要的配置。
  3. 确保每个组件正确使用国际化方法。
  4. 处理潜在的错误和冲突。

1.2 1.2- 工具的解决方式：

  • 自动集成：通过勾选集成next-intl选项，工具自动完成集成，无需学习额外 API 或配置。

2. 2- 多语言维护费时低效

新增标签时，手动过程繁琐，容易出错。需要手动找到 JSON 文件，创建唯一 key，复制内容，更改组件代码并翻译各语言内容。

2.1 2.1- 手动过程：

  1. 找到默认语言的 JSON 文件。
  2. 创建新标签的唯一 key。
  3. 将内容复制到 key 的 value 中。
  4. 修改组件代码，使用t函数引用新 key。
  5. 为其他语言复制并翻译新 key 和 value。

2.2 2.2- 工具的解决方式：

  • 自动解析和翻译：工具通过代码解析和翻译引擎自动处理所有繁琐流程，只需点击“提交”。

3. 3- 修改过程繁琐，易出错

调整界面文案时，手动复制粘贴、翻译容易出错，特别是文本量多时。

3.1 3.1- 手动过程：

  1. 手动查找并修改 JSON 文件内容。
  2. 复制并翻译内容到各语言文件。
  3. 保存并验证所有修改是否正确。

3.2 3.2- 工具的解决方式：

  • 编辑器功能：提供以默认语言 JSON 文件为基础的编辑器，批量修改内容，确认后自动翻译并更新，避免手动操作的错误。

4- 优势

  1. 快速集成多语言：无需研究手动集成引起的错误，一瞬间集成即可使用。
  2. 高效率开发：自动解析和翻译代码，无需手动更改标签和翻译内容。
  3. 高效率维护：通过 JSON 编辑器功能，自动处理各国语言的翻译和存储，避免手动操作引起的错误。
  4. 零耦合：项目完全基于next-intl库，无任何封装处理，可以安全放心使用。

5- 原理

AutoI18n For NextJs 通过nodejs的文件读取库、babel解析库以及第三方翻译 API（如 Azure Translate、Google Translate、DeepL 等）实现自动化处理代码和翻译内容。

6- 使用方法

工具安装完成后开箱即用，无需额外设置。可以参考下文，有对各个功能的概述和介绍。由于更新原因，描述和功能可能有些许出入，请以应用最新版的功能为准。

4. 1- 首页配置

5. 2- 选择项目

选择项目路径

首先，请选择项目的根目录。选择后，工具会检查项目是否已有配置文件。

5.1 2.1- 注意事项：

  • 在选择项目之前，请确保代码已本地保存或提交，以便回滚。
  • 选择的项目需基于 Next.js 框架的 App Router 版本，其他项目暂不支持。
  • 确保项目未集成其他国际化库（如 react-i18next、React-intl-universal、react-intl），支持手动集成 next-intl 的项目。

9- 语言选项

6. 1- 选择默认语言

选择默认语言

根据项目的实际默认语言进行选择。默认语言是代码中包含的文案语言，选择错误将导致翻译失效。

注意： 未使用自动推测功能是因为文案可能包含多种语言，手动选择更为准确。

7. 2- 勾选需要的多语言

配置多语言

根据项目需求勾选多语言。初次勾选时请不要选择过多语言，因为翻译 API 有速率和文本量限制，文本量大时可能会翻译失败或被限速。建议初次翻译只选择一个额外语言，后续再增加。

8. 3- 品牌词

品牌词

将品牌词填入此处，翻译时会跳过这些词，确保品牌词的准确性和一致性。

9. 4- 无需移动的文件或文件夹

无需移动的文件

如果有些文件的访问路径不想变成/en/lib/foo，只想保留/lib/foo，将这些文件夹名称填入此栏。初次集成 next-intl 并移动文件夹时会跳过这些文件夹。默认已忽略 api 目录，无需填写。

10- 翻译选项

翻译选项

目前有三个选项：

  • 选择：只翻译在“编辑器”中勾选过的内容或有所改动的内容。
  • 增量（默认）：处理新增的标签或组件，不重复翻译已存在内容。
  • 全部：对所有内容进行全覆盖式翻译，不推荐文本量大时使用，以避免触发 API 限制。

11- 集成选项

集成选项

集成选项用于初期配置和调试 next-intl 多语言阶段。正常使用后无需再次集成。

  • 重新集成 NextIntl：初期配置或配置混乱时使用，手动集成的项目请勿勾选。
  • 启用静态渲染：确保服务端渲染时，多语言也能静态渲染，详情见官方文档。
  • 启用子页面 locale 跳转：推荐开启，例如访问/about 将跳转至/en/about，详情见官方文档。
  • 禁用默认语言跳转：默认语言情况下不加/en 前缀，保持 SEO 数据不变，详情见官方文档。

12- 提交

提交提示

注意： 请务必保存或提交代码，避免问题无法回滚。

点击提交按钮，工具将自动处理配置内容。初次提交时会生成一个名为"auto-i18n-config.json"的配置文件，声明当前项目的多语言配置，可随版本控制系统提交。

10. 1- 提交运行结果展示

提交结果

提交完成后，会展示处理日志。

11. 2- 提交出现错误

错误反馈

出现错误时，如果错误信息可以修复，则根据提示修复。如果无法修复或怀疑是工具问题，可点击Click Me, Feedback The Error提交错误给开发者。如果已登录 http://autoi18n.dev ，错误信息和邮箱会自动携带；未登录则需手动填写邮箱和名称后提交。

12. 3- 界面预览

点击后自动打开浏览器并访问：http://localhost:3000 。

13. 4- 默认语言 JSON 编辑器

13.1 4.1- 选择性翻译

可以多选想要重新翻译的内容。勾选行前面的框即可。在界面最下方点击“确认选择或编辑”进行暂存。

13.2 4.2- 修改标签或内容

通过 JSON 编辑器可以编辑项目的默认语言 JSON： 编辑界面

编辑时可进行如下操作：

  • 撤销、重做、重置
  • 通过搜索快速定位需要更改的内容

完成修改后，在界面最下方点击“确认选择或编辑”进行暂存。只有提交后才会真正开始处理，回到首页提交时，所有更改或勾选过的内容将重新进行自动代码处理和翻译。

16- 其他

14. 1- 常见问题

应用中的 FAQ 界面描述了常见问题及解决方法。建议使用前浏览查看。

15. 2- 关于

应用中的关于界面包含当前应用信息、版本信息及其他信息。可手动检查更新，并找到联系方式和反馈选项。