贡献文档国际化¶

备注

已有的文档

准备环境¶

假设你已经 fork 仓库并 clone 到了本地。

使用 cd JAnim 进入项目文件夹，然后安装必要的环境：

pip install -e .[gui,doc]

另外，需要确保已安装 GNU gettext

文档国际化的工作流程分为以下步骤：

大多数情况下，比如英文文档，翻译文件（后缀 .po）已经生成到了项目中。如果你只是想编辑已有的翻译文件，可以跳过此段，直接到进行文档翻译便可以开始翻译。

要创建新语言的翻译或更新现有翻译文件，使用以下命令：

python scripts update-po docs <language>

其中 <language> 是你要翻译的语言代码（例如 en 表示英文，ja 表示日语等）。

备注

zh_CN 是文档的源语言，因此不需要为其创建翻译文件。

完成后，你可以在相应的 doc/source/locales/<language>/LC_MESSAGES/ 目录中找到所有的 .po 文件。

在开始翻译或翻译过程中，你可以检查翻译的完成情况：

python scripts check-po docs <language>

该命令会扫描所有 .po 文件，并列出仍有未翻译（untranslated）或模糊（fuzzy）条目的文件。这有助于你了解还需要进行哪些翻译工作。

并且一些软件，比如 Poedit 的编目管理器也可以列出文件夹中的 .po 文件的翻译完成情况。

现在 doc/source/locales/<language>/LC_MESSAGES/ 中已经存放了翻译文件（后缀 .po）。

可以使用 Poedit 软件来编辑 .po 文件，或者用任何文本编辑器直接编辑。

备注

如果你有能力检查的话，使用 LLM Agent 翻译也无妨（但是记得校对哦）

示例提示词：

请完成 `<language>` 文档的翻译工作
工作规范以及工作流程请严格参考 `doc/source/development/contribute-to-doc-i18n.rst` 中的介绍

如果你是手动编辑了较多 .po 文件，建议在提交前执行一次：

python scripts format-po docs <language>

这个命令会统一 .po 的换行与排版策略，减少因为格式差异导致的无关 diff。

完成翻译后，提交你的更改，创建合并到 main 分支的 Pull Request。

要在本地预览你的翻译效果，可以构建文档：

python scripts build-docs <language>

其中 <language> 是你要构建的语言代码（例如 en 表示英文）。

该命令会在 doc/build/html_i18n/<language>/ 下生成网页文件，点击其中的 index.html 即可在浏览器中打开并查看文档。

或者在使用前述命令时加上 -o 参数，即可直接在构建完成后自动打开浏览器预览：

python scripts build-docs <language> -o

备注

构建文档时，会自动从 .po 文件编译产生 .mo 文件，无需提前手动生成。

假设你要为文档提供英文翻译，完整流程如下：