Manim 文档国际化i18n参与指南基于 Crowdin 的翻译协作全流程【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim本文是 ManimManimCommunity 社区维护版数学动画框架文档国际化贡献的完整操作指南。围绕仓库内 docs/source/contributing/internationalization.rst 展开系统讲解如何注册翻译平台账号、参与投票与直接翻译、遵循翻译规范、申请成为校对者Proofreader以及如何报告源文本错误同时结合仓库中真实的 i18n 目录、Crowdin 配置与 Sphinx gettext 构建流程帮助读者理解 Manim 文档翻译从源文档提取到多语言落地的全链路。读完本文你可以直接上手参与 Manim 任意语言文档的翻译、投票与质量审核工作。一、先理解 Manim 文档国际化的整体架构Manim 的官方文档基于 Sphinx 构建其国际化遵循经典的 gettext 工作流英文源文档.rst通过 Sphinx 的 gettext 模式提取为 POT 模板文件再由第三方翻译管理平台 Crowdin 承接众包翻译最终各语言产出 PO 文件并被 Sphinx 编译为对应语言的文档页面。这套流程在仓库中有完整的落地证据翻译源模板全部 POT 文件位于 docs/i18n/gettext 目录按文档章节分目录组织如contributing/、guides/、installation/、reference/、tutorials/等还包括index.pot、installation.pot、reference.pot等顶层文件各语言翻译结果语言代码目录如fr、hi、pt、sv下统一存放于LC_MESSAGES/子目录例如 docs/i18n/fr/LC_MESSAGES/installation.po 就是法语版安装指南Crowdin 平台映射配置crowdin.yml 只有两条规则清晰定义了源文件与译文文件的对应关系files: - source: /docs/i18n/gettext/**/*.pot translation: /docs/i18n/%two_letters_code%/LC_MESSAGES/**/%file_name%.po即仓库内所有gettext目录下的.pot文件作为翻译源Crowdin 会按两字母语言代码生成对应的LC_MESSAGES目录并把每个 POT 转成同名的.po翻译文件。这也是下文所有在 Crowdin 上翻译操作背后真实的文件流转逻辑。从 docs/source/contributing.rst 可以看出Translating documentation and docstrings翻译文档与 docstring被明确列为 Manim 社区贡献的重要方式之一。因此翻译工作与代码开发、文档撰写、测试一样都是官方认可的贡献形式。二、注册账号进入 Manim 的翻译项目参与翻译的第一步是在 Crowdin 上注册账号。官方指南见 internationalization.rst 的 Signing up 一节给出的步骤是打开 Manim 翻译项目的项目主页翻译平台的管理首页点击右上角的Sign up注册按钮按照页面引导完成账号创建注册完成后返回项目主页点击Manim项目即可开始为主库文档贡献翻译。补充社区欢迎任何人参与本地化工作虽然不强制但官方鼓励加入 Manim 社区 Discord 服务器以便与其他译者交流这不是硬性要求。需要说明的是注册与翻译动作都发生在 Crowdin 平台上仓库本身是只读的——翻译成果会由平台侧的同步机制写回docs/i18n/语言代码/LC_MESSAGES/下的.po文件。三、开始贡献投票与直接翻译官方指南在 Contributing 一节开头用醒目的提示important块强调了参与翻译前必须了解的现实Manim 仍处于持续开发中教程和文档随时可能变化。开发者实现新功能时并不会被强制要求同步更新已有翻译这意味着部分翻译内容可能随着时间推移而过时。但这并不意味着翻译工作没有价值改进文档、提升可访问性始终是被鼓励的。即使某个翻译日后过时你或其他译者也可以随时修正它付出的努力不会白费。翻译的贡献方式分为两种投票审核Voting与直接翻译Translations。3.1 投票审核用众包保证译文质量为保证翻译质量Manim 使用众包投票机制来择优录取、淘汰劣译。当前译文被接受的投票门槛是 3 票官方说明该阈值可能随社区活跃度与译文质量的变化而调整。在 Crowdin 上执行投票的具体操作路径点击你想要帮助的语言点击Translate all全部翻译按钮进入翻译编辑器在搜索栏旁边找到漏斗状图标并点击选择Need to Be Voted待投票选项筛选出需要投票的译文在左侧边栏选择一条字符串string在底部查看各译者提交的翻译通过 与 - 图标分别为好译文与差译文投票。这套流程的实质是任何译者都可以提交译文而社区成员通过投票共同把关质量达到阈值目前 3 票的译文才会被采纳。3.2 直接翻译贡献自己的译文如果你希望直接提交翻译操作同样简单按上面 3.1 的步骤进入翻译编辑器除了 Translate all 之外你也可以点击某个具体文件只翻译该文件中的字符串Crowdin 内置的屏幕教程会引导你完成整个翻译过程。进阶说明直接翻译的本质是填写.po文件中的msgstr字段。以仓库中法语版安装指南 docs/i18n/fr/LC_MESSAGES/installation.po 为例其典型条目形如#: ../../source/installation.rst:2 msgid Installation msgstr Installationmsgid是英文源字符串msgstr是目标语言译文。翻译在 Crowdin 编辑器中完成后会被回写到仓库对应语言的.po文件中。四、翻译规范遵循目标语言的技术写作惯例官方在 Translation guidelines 一节给出了两条核心准则遵循目标语言的技术写作惯例。可以参考同语言高质量技术文档的风格例如该语言版本的 Python 官方文档作为措辞与行文风格的参照代码块、代码字面量、名称与笔名必须保持原样不做翻译。这包括内联代码、命令行片段、类名/函数名、变量名等防止破坏文档的可执行性与可检索性。这条代码不译原则也体现在仓库的预处理脚本中Sphinx 生成的 POT 中大量包含:ref:、:mod:、:class:、:func:等 Sphinx 交叉引用指令的条目本不需要人工翻译。仓库提供了 docs/i18n/stripUntranslatable.sh 与 docs/i18n/stripUntranslatable.awk用 awk 正则如匹配:ref:xxx、manim.xxx等模式自动把这些不可翻译的条目从上传到 Crowdin 的 POT 中剥离只保留真正需要翻译的正文文本从而大幅降低译者的无效工作量。五、申请成为校对者Proofreader对于社区内使用人数较多的语言Manim 在众包投票之外还会增加一道校对Proofreading环节进一步保证译文质量。校对者是受信任的社区成员负责通读译文并给出最终批准。如果你希望成为校对者请发送邮件至translationsmanim.community并在邮件中回答以下 8 个问题你的 Crowdin 用户名是什么你的 Discord 用户名是什么可选你的 GitHub 用户名是什么可选列出你会说的语言及各自的熟练程度。你申请为哪种/哪些语言担任校对者你之前有翻译经验吗如果有请提供更多细节。如果成为校对者你将如何保证翻译质量官方特别说明担任校对者不要求必须有翻译经验只需要有维护高质量翻译的承诺与责任心即可。六、发现错误如何报告源文本问题如果你在翻译过程中发现源字符串msgid本身有错误官方指南 Errors → Source errors 一节的建议是在 GitHub 上为源字符串错误提交 issue通过项目的 issue 新建入口创建在问题解决之前先不要翻译该字符串以免把错误内容扩散到各语言版本。这一约定保证了先修源、再翻译的正确顺序避免基于错误源文本的翻译被投票通过后造成返工。七、仓库侧的全链路技术支撑以上所有流程都能在仓库中找到对应的实现支撑理解它们有助于你判断某个翻译文件的来龙去脉。7.1 文档国际化目录结构仓库根目录下 docs/i18n 是国际化的核心目录内部结构如下docs/i18n/ ├── gettext/ # Sphinx gettext 提取出的英文源模板POT │ ├── contributing/ │ ├── guides/ │ ├── installation/ │ ├── reference/ │ ├── tutorials/ │ ├── index.pot │ ├── installation.pot │ └── ... ├── fr/LC_MESSAGES/*.po # 法语翻译 ├── hi/LC_MESSAGES/*.po # 印地语翻译 ├── pt/LC_MESSAGES/*.po # 葡萄牙语翻译 ├── sv/LC_MESSAGES/*.po # 瑞典语翻译 ├── readyForTranslation # 待翻译标记文件 ├── stripUntranslatable.awk # 剥离不可翻译条目的 awk 脚本 └── stripUntranslatable.sh # 批量清理脚本以本文对应的文档为例其英文源模板位于 docs/i18n/gettext/contributing/internationalization.pot里面按#: ../../source/contributing/internationalization.rst:行号标注了每条msgid的来源位置——这正是从源文档提取翻译条目的直接证据。7.2 Sphinx 构建配置与 i18n 生成目标在 docs/source/conf.py 中可以看到国际化相关的三项关键配置locale_dirs [../i18n/] gettext_compact False gettext_last_translator gettext_language_team locale_dirs指向../i18n/即 Sphinx 编译多语言文档时读取翻译文件的目录gettext_compact False表示按原文档路径结构逐文件生成 POT而不是合并压缩这正是gettext/目录下与源文档一一对应的.pot文件布局的由来。在 docs/Makefile 中还有一个专门的i18n构建目标完整展示了从英文源文档生成待翻译模板的自动化流程i18n: (cd source; $(SPHINXBUILD) -M gettext $(SOURCEDIR) ../i18n/ -t skip-manim $(SPHINXOPTS) $(O);cd ../i18n;bash stripUntranslatable.sh)即先用sphinx-build -M gettext把source下的.rst全部提取为 POT-t skip-manim标签用于跳过 Manim 相关渲染内容紧接着运行stripUntranslatable.sh清理掉无需人工翻译的条目——两条命令串联构成了翻译模板生成的标准流水线。构建完成后Crowdin 通过 crowdin.yml 的配置拉取 POT 分发翻译、回收 PO最终 Sphinx 再依据locale_dirs编译出各语言文档。八、参与翻译的最小行动清单总结官方指南与仓库实现一个完整的最小参与路径如下在 Crowdin 翻译平台注册账号并进入 Manim 项目对应 Signing up 一节选择语言点击 Translate all 或具体文件进入翻译编辑器若想审核他人译文点击漏斗图标 → 选择 Need to Be Voted → 用 /- 为译文投票目前阈值 3 票若想直接提交译文按目标语言技术写作惯例翻译保持代码、名称与交叉引用原样想深度参与某语言质量控制按第 5 节 8 个问题发邮件申请成为校对者发现源字符串错误先在 GitHub 提交 issue解决前不要翻译该字符串理解翻译文件的去向你的译文最终会进入仓库docs/i18n/语言代码/LC_MESSAGES/下的.po文件并经由 docs/source/conf.py 的locale_dirs配置被 Sphinx 编译成对应语言文档。无论你是想为母语社区填补文档空白还是想通过审校他人译文来精进技术写作Manim 文档国际化流程都是一条门槛低、反馈直接的参与路径——正如官方指南所说即使你的翻译日后过时也可以随时调整修正你的付出不会白费。【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考