Skip to content

快速入门 ​

本页指导单语言项目生成其首批翻译文件。它适用于 JS/TS 应用、Python 应用、.NET 应用、网站或文档站点,或存储库 README 和其他 Markdown 文件。它假设:

  • Node.js >=22.16.0,或 独立可执行文件(适用于 Python 或 .NET 项目)。
  • LLM 提供商的 API 密钥,或本地 Ollama 安装。
  • 项目处于版本控制中,因此您可以查看工具写入的内容。

不同项目之间有两个差异:工具如何找到您的文本,以及您的应用如何加载结果。下方的选择您的路径部分会将您引导至相应的指南。

可运行示例 ​

想先看看已完成的项目吗?无需克隆仓库即可复制一个:

bash
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync

将 console-app 替换为任何其他 Node.js 示例。Python 和 .NET 示例没有 package.json;请以相同方式复制它们。四个 Python 示例也位于 GitHub Release 的 ai-i18n-tools-python-examples.zip 中,两个 .NET 示例位于 ai-i18n-tools-dotnet-examples.zip 中。包含每个示例所展示内容的完整列表,请参见示例页面。

安装 ​

bash
pnpm add -D ai-i18n-tools

npm install --save-dev ai-i18n-tools 和 yarn add --dev ai-i18n-tools 也适用。Python 和 .NET 项目安装独立可执行文件,无需 Node.js。Linux 和 macOS:curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash。Windows PowerShell:irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex。其他安装选项:安装。

提供商和 API 密钥 ​

每个调用 LLM 的命令(translate-ui、translate-docs、translate-json、translate-svg 和 sync)都需要以下两项:

  1. 至少一个提供程序在 ai-i18n-tools.config.json 中:一个带有 translationModels 的 providers.<name> 块,以及当配置了多个提供程序时,一个顶层 provider 键。init -P <provider> 会搭建该预设。要添加提供程序,请参阅 LLM 提供程序。要选择模型列表,请参阅 AI 模型。
  2. 您的环境中匹配的 API 密钥,或者当未设置提供程序 API 密钥时,在 ai-i18n-tools.config.json 旁边的 .env / .env.local 中。每个内置预设都会从 预设表 中读取一个命名变量,例如 OPENROUTER_API_KEY 搭配 -P openrouter,或 OPENAI_API_KEY 搭配 -P openai。Ollama 使用本地端点,无需密钥。
bash
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

extract、status 以及其他不调用 LLM 的命令则两者都不需要。有关环境文件和 PATH 的更多信息:安装。

选择您的路径 ​

找到您拥有的项目类型,运行其对应块中的命令,然后继续阅读链接的指南。

JS/TS 应用 ​

您的按钮和消息在源代码中仍然是纯文本,因此工具目前还找不到任何内容。必须先将它们用 t() 包装起来,并且应用需要一个小的 i18next 配置文件。

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --apply

然后遵循向 JS/TS 应用添加 i18n指南。该指南在介绍 extract 和 translate-ui 之前,会先介绍包装步骤,并提供一个代理提示。

Python 应用 ​

bash
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --apply

然后按照 将 i18n 添加到 Python 应用。

Django 应用、使用 Flask-Babel 目录的 Flask 应用,或已调用 gettext 的应用会保留这些调用。而是使用 ui-python-django、ui-python-flask 或 ui-python-gettext 进行脚手架搭建,然后按照 将 i18n 添加到 Django / Python gettext 应用。

一个 .NET 应用 ​

bash
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --apply

然后按照 将 i18n 添加到 .NET 应用。已使用 ResourceManager 或 IStringLocalizer 的应用则改用 ui-dotnet-resx,然后按照 将 i18n 添加到 .NET ResourceManager 应用。migrate-dotnet-i18n 将 T($"…") 重写为带编号的 {0} 调用。--wrap 审计未标记的 XAML 和 C# 标签。报告会列出命名的 resx 键(例如 Resources.LoginButton)作为建议,并且不编辑这些行。

网站或文档站点 ​

为您的框架选择模板:

您的站点模板
Astro Starlightui-starlight
Docusaurusui-docusaurus
VitePressui-vitepress
Nextraui-nextra
Fumadocsui-fumadocs
纯 Astro 网站ui-astro-website
纯 HTML 页面ui-plain-html 或 docs-plain-html
bash
ai-i18n-tools init -t ui-vitepress -P openrouter

然后按照 将 i18n 添加到网站或文档站点。它的代理提示会启用框架的 i18n 路由。审阅该工作后,运行 sync。

README 或 Markdown 文档 ​

大多数仓库希望将其与应用程序放在一起:默认的 ui-markdown 模板已包含一个扁平的 README 块。对于任何其他模板,请添加 --with-readme。一个只有 Markdown 的仓库使用 docs-markdown。

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouter

然后按照 将 i18n 添加到您的 README 和 Markdown 文档。将语言列表标记粘贴到 README.md 中,在 sync 之前。如果有应用路径,它仍然是 将 i18n 添加到 JS/TS 应用、将 i18n 添加到 Python 应用 或 将 i18n 添加到 .NET 应用。

其他情况 ​

包含所有 init 选项的完整模板列表位于 CLI 设置参考 中。

运行和检查 ​

当您的项目准备就绪时:

bash
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools status

doctor 会检查配置、路径、提供程序和环境是否已准备就绪。除非您传递 --local,否则它还会验证提供程序中的模型 ID。sync 会按顺序运行配置启用的每个步骤。status 会显示每个区域设置中已翻译的内容。如果工具无法在项目中看到文本,则首次运行会无错误完成,但不会写入任何有用的内容,因此如果 status 未显示任何字符串,请返回到您路径的指南。

suggest-models 根据已发布的基准测试对活动提供商的聊天模型进行排名。suggest-models --apply 会替换 translationModels,但保留 uiModels 和 localeModels 不变。相同的排名位于仪表板的 模型 选项卡上。有关排名工作原理以及列表为何包含多个模型的信息,请参阅:AI 模型。命令参考:suggest-models。

保持翻译更新 ​

每当源文本发生更改时,请重新运行 sync。SQLite 缓存意味着只有新的或更改的文本会发送到模型,因此重新运行的成本很低。在 CI 中运行 sync 可以防止翻译出现偏差。ai-i18n-tools dashboard 会打开 翻译仪表板 以审查和编辑缓存的翻译。

推荐的 package.json 脚本 ​

在本地安装该软件包后,脚本会从 node_modules/.bin 解析 ai-i18n-tools,无需额外的 shell 设置。对于交互式 shell,请先配置 PATH:请参阅使用 CLI。

json
{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:status": "ai-i18n-tools status",
  "i18n:statistics": "ai-i18n-tools statistics",
  "i18n:dashboard": "ai-i18n-tools dashboard",
  "i18n:cleanup": "ai-i18n-tools cleanup"
}

首选 sync,而不是链接各个翻译脚本。仅当需要单独执行一个步骤时,才使用单步脚本。

要以其他语言显示 CLI 输出和仪表板,请传递 -L <code> 或设置 AI_I18N_LANG:请参阅 工具 UI 语言。

要翻译多种内容,例如同时翻译应用字符串和文档网站?请参阅合并管道。

下一步:请参阅选择您的路径中适合您的指南。

基于 MIT 许可证发布。