CrewAI 文档多语言同步工作流从 docs/edge 英文源到 ar、ko、pt-BR 翻译的完整实践【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI本文以仓库根目录的 DOCS_TRANSLATIONS.md 为核心完整讲解 CrewAI 文档站的多语言同步机制如何用 git 命令定位docs/edge/en/下的变更、如何把每个英文页面映射到阿拉伯语、韩语、巴西葡萄牙语三个语言目录、翻译时必须遵守的 MDX/JSX 保留规则以及文档冻结freeze脚本如何把这套多语言目录结构固化为docs/vX.Y.Z/版本快照。读完本文你可以独立完成一次合规的文档翻译提交并理解翻译文件与 Mintlify 版本化导航docs/docs.json之间的底层关系。1. 多语言文档目录结构与同步范围CrewAI 的文档采用 Mintlify 组织位于docs/目录下语言维度分四层docs/edge/—— 滚动更新的Edge渠道源文件紧跟 main 分支 HEADdocs/v1.10.0/至docs/v1.15.18/—— 各历史版本的冻结快照当前仓库已包含约 30 个版本快照目录docs/docs.json—— Mintlify 导航与重定向配置navigation.languages下按语言组织版本选择器。每个语言目录edge/与各vX.Y.Z/快照内部结构一致包含lang/ api-reference/ concepts/ examples/ guides/ learn/ mcp/ observability/ snippets/ tools/ changelog.mdx index.mdx installation.mdx introduction.mdx quickstart.mdx skills.mdx telemetry.mdx enterprise-api.base.yaml enterprise-api.en.yaml / .ko.yaml / .pt-BR.yaml按 DOCS_TRANSLATIONS.md 的定义支持的翻译语言localesar阿拉伯语、ko韩语、pt-BR巴西葡萄牙语翻译源永远是更新后的英文文件docs/edge/en/path.mdx它是source of truth硬性边界只处理docs/edge/en/下的*.mdx文件绝不编辑docs/v*/快照目录——快照由冻结流程生成、只读保留这是由版本化脚本的布局假设所保证的见后文第 6 节。当前仓库中docs/docs.json的navigation.languages实际包含四个语言块en、pt-BR、ko、ar每块的versions[]数组首项是Edgetag: Edge其后是v1.15.18default: true、tag: Latest及更早的版本条目。这与翻译工作流的目录约定完全对应。2. Step 1 — 用 git 定位变更的英文文件同步的第一步是从仓库根目录执行 git 命令列出英文源目录下发生变更的文件。原文档给出三组命令覆盖三种典型场景# 未提交的变更暂存区或工作区 git diff --name-only HEAD -- docs/edge/en/ # 当前分支相对于 main 的全部变更 git diff --name-only main...HEAD -- docs/edge/en/ # 新添加的文件含未跟踪状态 git status --porcelain docs/edge/en/三点说明前两条git diff只能看到已跟踪文件的修改新增页面不会出现在git diff输出中所以必须配合git status --porcelain补齐新文件——这也是原文档把三条命令并列给出的原因。限定路径前缀-- docs/edge/en/保证输出只含英文源不会混入其他语言目录或源码目录lib/、scripts/等的变更。处理结果时只保留*.mdx文件且按规则不编辑docs/v*/下的任何快照。3. Step 2 — 把每个英文文件映射到三个语言目标映射规则是同构的对docs/edge/en/path.mdx更新或创建以下三个文件英文源文件翻译目标文件docs/edge/en/concepts/llms.mdxdocs/edge/ar/concepts/llms.mdxdocs/edge/ko/concepts/llms.mdxdocs/edge/pt-BR/concepts/llms.mdx相对路径必须逐段一致英文concepts/llms.mdx对应三个语言目录下完全相同的concepts/llms.mdx而不是翻译后的新文件名。新增页面的额外步骤如果英文侧是一个新页面对应语言目录此前没有同名.mdx除了创建三个语言文件还必须在 docs/docs.json 中为每个语言的导航结构添加对应条目。原因在于 Mintlify 只渲染导航中列出的页面——从冻结脚本的实现可以印证这一点lib/devtools/src/crewai_devtools/docs_versioning.py中的_prune_missing_pages会递归遍历导航树的pages/tabs/groups凡是解析不到磁盘上.mdx/.md文件的条目直接剔除连带为空的分组级联移除。反过来说文件存在但导航未收录时页面在站点上同样不可见。4. Step 3 — 翻译规则改什么、留什么翻译以更新后的英文文件为唯一事实来源。若语言文件已存在应应用相同的语义变更而不是重写无关章节。原文档给出的六条规则逐条展开如下规则含义与实操要点翻译正文与 frontmatter 值title、description、sidebarTitle等元数据一并翻译。以docs/edge/ar/concepts/llms.mdx为例其 frontmatter 中title: نماذج اللغة الكبيرة (LLMs)即为英文title: LLMs的阿拉伯语对应MDX/JSX 标签、代码块、URL、标识符保持不变CardGroup、Card title... icon...等组件标签、属性结构、围栏代码块内容、外链与技术标识符原样保留只翻译其中的自然语言关键术语保留英文在合适处保留 Agent、Crew、Task、Flow、LLM、API、CLI、MCP 等术语英文写法。从现有翻译文件看这一规则被严格执行阿拉伯语页面正文中 CrewAI 与 LLMs 均保留英文内部链接改写语言前缀/en/→/{lang}/即/ar/、/ko/、/pt-BR/。例如英文侧指向/en/concepts/files的内部链接韩语页面中应为/ko/concepts/filesdocs/edge/ko/下页面即如此引用不添加译者注释译文中不插入 translator notes语义变更优先已存在的语言文件只做对应段落的同步修改不做无关改写这里有一个容易被忽视的细节edge/下页面内部的相对导航链接使用的是站点绝对路径 语言前缀的写法如/ko/concepts/files因此翻译时改前缀、不改路径即可不要引入../一类的相对写法。5. Step 4 — 校验与提交原文档将校验列为可选步骤cd docs mintlify broken-links该命令由 Mintlify CLI 提供用于检出文档站中的断链。结合仓库中脚本的注释可以推断其重要性lib/devtools/src/crewai_devtools/docs_versioning.py的_update_redirects明确指出 Mintlifys link checker resolves each redirect independently and does not chain through them——即 Mintlify 的链接检查不跟随重定向链任何依赖二次跳转的目标都会被判定为断链。因此翻译中改写的/{lang}/前缀链接必须直接命中真实存在的页面。提交要求英文文件与三个语言文件必须合并在同一次提交中Commit English and locale files together保证任何提交点上四语言文档处于一致的版本状态。6. 为什么不能动docs/v*/翻译边界背后的冻结机制Do not editdocs/v*/ 这条规则不是风格建议而是由仓库的文档版本化机制决定的。相关实现可从源码结构确认lib/devtools/src/crewai_devtools/docs_versioning.py核心freeze(version, docs_root)函数把docs/edge/下的en、pt-BR、ko、ar四个语言目录及enterprise-api.*.yaml复制到docs/vX.Y.Z/随后把快照内所有 MDX 的openapi:引用改写为指向快照自己的 YAML再向docs/docs.json每个语言的versions[]插入新版本条目克隆自 Edge 导航、标记defaultLatest、降级旧默认最后刷新/lang/:slug*→/vnew/lang/:slug*的通配重定向。该模块的布局假设明确写着docs/edge/是滚动源匹配 main HEADdocs/vX.Y.Z/是frozen, immutable snapshotsscripts/docs/freeze_current_edge.pydevtools release流程之外的一次性手动冻结入口用法python scripts/docs/freeze_current_edge.py 1.15.0幂等——快照目录与 docs.json 条目已存在时仅重跑迁移scripts/docs/freeze_historical_versions.py从 git 历史 tag1.10.0 至 1.14.7用git archive重建旧版快照同样幂等且支持--forcescripts/docs/prefix_version_paths.py一次性把docs.json的版本导航从共享docs/lang/迁移为按目录版本化并插入 Edge 条目与通配重定向。由此翻译工作流与发布流程形成清晰分工翻译者只在docs/edge/内工作发布冻结负责把 Edge含四语言整体复制进不可变快照。这也解释了为何docs/docs.json中当前存在四条通配重定向——/en/:slug*、/pt-BR/:slug*、/ko/:slug*、/ar/:slug*全部指向/v1.15.18/...旧版规范 URL 通过这层重定向稳定落到最新默认版本而每次冻结都会把这四个目标的目的地前移。7. 提交前检查清单原文档自带一份 checklist翻译提交前逐项确认- [ ] Git已列出变更的 docs/edge/en/*.mdx 文件 - [ ] ar已更新/创建对应文件 - [ ] ko已更新/创建对应文件 - [ ] pt-BR已更新/创建对应文件 - [ ] 内部链接使用 /{lang}/ 前缀代码块未被改动 - [ ] 若新增了英文页面docs/docs.json 已同步更新8. 示例一次完整的翻译同步以原文档给出的示例收尾。假设执行git diff --name-only HEAD -- docs/edge/en/后返回docs/edge/en/concepts/llms.mdx则本次同步需要更新或创建三个目标文件且相对路径与英文侧完全一致docs/edge/ar/concepts/llms.mdxdocs/edge/ko/concepts/llms.mdxdocs/edge/pt-BR/concepts/llms.mdx三个文件均以更新后的 docs/edge/en/concepts/llms.mdx 为源frontmatter 的title/description翻译为目标语言正文中 Agent、Task、LLM 等术语保留英文代码块与组件标签原样保留内部链接前缀分别改写为/ar/、/ko/、/pt-BR/。最后与英文文件一起提交如条件允许先跑mintlify broken-links校验即完成一次完整的文档翻译同步。【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考