agentic-awesome-skills 中文文档翻译工程基于术语表的 68 篇文档优先级翻译流水线【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本文拆解 agentic-awesome-skills 仓库中一份面向 Agent 执行的文档翻译实施计划plans/2026-03-27-chinese-docs-translation.md它如何用一个持续演进的 JSON 术语表glossary驱动 68 篇英文文档的简体中文翻译通过 Priority 1-5 的依赖顺序分批推进并借助链接校验与术语一致性脚本做批量质量门禁。读完本文你可以掌握“术语表先行 按优先级批处理 每批验证提交”这一可复用的多语言文档本地化工程方法以及配套的校验脚本实现细节。一、背景与目标为什么需要术语表驱动翻译仓库的英文文档体系位于docs/而中文版位于docs_zh-CN/。翻译计划启动时2026-03-27中文目录缺失约 68 篇文档涵盖用户指南、贡献者规范和运维/维护者文档。直接逐篇翻译会导致同一个术语在不同文件中出现多种译法例如 “skills” 译为“技能”还是“技巧”、agent 译为“代理”还是“智能体”破坏跨文档阅读体验。计划的总体目标与架构在文档开头明确给出Goal目标使用顺序式术语表构建方法sequential glossary-building将 68 篇缺失文档从英文翻译为中文并保持术语一致。Architecture架构按依赖顺序Priority 1-5处理文件术语表增量构建每一批先验证、先提交再进入下一批。质量保证包含链接检查、Markdown lint 和术语一致性校验。Tech StackMarkdown、JSON 术语表、bash 校验脚本、git 版本控制。文档开头还有一段给 Agent 执行者的强制约束For agentic workers:REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.这说明该计划本身就是一个“Agent 可执行”的任务书每个 Step 用- [ ]checkbox 跟踪任务间有明确的 commit 检查点。与之配套的还有一份已批准的设计文档 specs/2026-03-27-chinese-docs-translation-design.md定义了 Glossary Manager、Translation Engine、Link Validator、Quality Validator 四个组件以及每文件的翻译流水线约 1-2 分钟文件分析 3-5 分钟翻译执行。二、术语表.glossary.json的结构设计与真实演化术语表是整个方案的“灵魂”一个位于docs_zh-CN/.glossary.json的 JSON 文件。2.1 初始结构计划 Task 1 要求先创建初始术语表骨架{ metadata: { version: 1.0.0, created: 2026-03-27, last_updated: 2026-03-27, total_terms: 0 }, terms: {} }metadata承担版本管理职责version随每次新增术语递增total_terms必须与terms对象实际条目数一致后文会看到校验脚本正是据此判断术语表是否健康。2.2 每条术语的字段规范进入 Task 2术语表奠基后每条术语包含三个字段skills: { translation: 技能, context: AI assistant capabilities - core concept, examples: [use skills, skill library, skill execution] }translation确定的中文译法全文档统一使用context该术语的语义场景说明用于消歧设计文档明确建议为多义术语加usage_context例如 agent 在“代理 vs 智能体”间二选一后记录理由examples英文原文中的出现示例方便译者对号入座。2.3 奠基术语表35 个核心词Task 2 的第一步是先用频率分析从 4 篇核心用户文档中提取高频技术词# Extract frequently occurring technical terms for file in docs/README.md docs/users/getting-started.md docs/users/usage.md docs/users/faq.md; do echo Analyzing $file cat $file | grep -oE \b[A-Z][a-z](\s[A-Z][a-z])?\b | sort | uniq -c | sort -rn | head -20 done第二步建立包含 35 个核心术语的奠基术语表可以归为四类核心概念词skills→技能、repository→仓库、bundles→捆绑包、workflows→工作流、agents→代理、plugin→插件、marketplace→市场保留英文的品牌/工具名Claude、Cursor、Gemini、GitHub、MCP、npm、CLI注明“代码中保持 CLI 原样”通用开发词installation→安装、configuration→配置、deployment→部署、testing→测试、security→安全、development→开发、documentation→文档、version→版本、release→发布角色与文档体裁词contributor→贡献者、maintainer→维护者、guide→指南、tutorial→教程、example→示例、community→社区、feedback→反馈、terminal→终端、directory→目录、categories→类别、integration→集成、features→功能。一个关键决策是“英文保留原则”技术品牌词如 “Claude Code”不做硬译不译成“克劳德代码”只有存在官方中文名时才翻译——这是设计文档 Key Design Decisions 中明确写出的规则。2.4 术语表的真实演化轨迹从仓库当前实际产物看术语表按计划持续生长阶段术语数依据奠基Task 235计划文档 Task 2Priority 1 完成后60v1.0.4priority1-validation-report.md全部翻译完成时168v1.0.14final-validation-report.md当前仓库状态199v1.0.14last_updated 2026-07-09直接读取 .glossary.json也就是说翻译完成之后术语表仍在随后续文档维护继续增补从 168 增至 199。当前术语表里可以看到更晚加入的通用技术词如suppress→抑制、adversarial→对抗性、manifest→清单、bootstrap→引导、lazy loading→延迟加载、overflow→溢出。术语表不是一次性冻结的产物而是随文档演进持续扩展的活文档——这正是计划中 “Glossary evolution: Starts with ~20 core terms, grows to ~100 terms” 设计意图的落地。三、优先级分层68 篇文档的依赖顺序计划将 68 篇待翻译文档按“谁设定术语基调、谁依赖术语”排成 5 个优先级共 74 个任务Task 1 基建 各批翻译 各批验证 最终验证 PR优先级内容文件数说明Priority 1核心用户文档4README.md、users/getting-started.md、users/usage.md、users/faq.md—— 设定术语基调Priority 2工具专属指南4users/claude-code-skills.md、users/cursor-skills.md、users/gemini-cli-skills.md、users/codex-cli-skills.mdPriority 3进阶用户文档15bundles、workflows、skills-vs-mcp-tools、agent-overload-recovery、windows-truncation-recovery、kiro-integration、local-config、security-skills、walkthrough、visual-guide、BUNDLES.md等Priority 4贡献者指南6contributors/quality-bar.md、contributors/security-guardrails.md、contributors/skill-anatomy.md、EXAMPLES.md、QUALITY_BAR.md、SKILL_ANATOMY.mdPriority 5维护者文档39maintainers/*.md、根级大写文档AUDIT.md、USAGE.md、VISUAL_GUIDE.md等与 integrations 文档分层逻辑与翻译状态文件 translation-status.md 完全对应该文件记录了每一批Batch 1-5的完成打勾并在顶部用 2026-09-06 的一致性更新声明“完成标记记录翻译历史不表示所有页面与当前实现同步”体现了翻译产物需要随英文源持续漂移修复的维护现实。3.1 单个文件的翻译执行单元以 Priority 1 的四个文件为例计划为每个文件规定了完全一致的 5 步执行模式Task 3-6Step 1: Read source file—— 先读英文原文如docs/users/faq.md理解结构与内容Step 2: Translate—— 在docs_zh-CN/对应路径创建中文译文翻译规则为保留全部 Markdown 结构翻译标题、列表与说明文字代码块、命令、文件路径保持英文专名保留英文Claude Code、GitHub、npm术语表术语全文一致链接文字翻译但 URL 不变Step 3: Extract and add new terms—— 把翻译中遇到的新术语回填进docs_zh-CN/.glossary.jsonStep 4: Update translation status—— 在状态文件中把对应 checkbox 从- [ ]改为- [x]并更新 Completed/Remaining 计数如 “Priority 1: 1/4 complete”Step 5: Commit individually—— 每篇文件独立提交commit message 遵循 conventional commits 风格例如git add docs_zh-CN/users/faq.md docs_zh-CN/.glossary.json docs_zh-CN/translation-status.md git commit -m feat(zh-CN): translate users/faq.md - Complete Chinese translation of FAQ - Add X new terms to glossary - Priority 1: 4/4 complete ✓ - Foundation glossary locked and ready for Priority 2每篇一个独立 commit 的价值在于术语表、译文、状态三者始终原子地同步演进任何一批出问题都可以精确回滚到批次边界。Priority 1 完成后计划还规定 “Foundation glossary locked”奠基术语表锁定后续批次只允许追加、不再回改已锁定的核心译法。四、翻译规则与边界情况处理设计文档specs 文档给出了明确的“可译 / 不可译 / 视上下文”三分法实施计划继承了这套规则翻译Translate说明性文字、标题、列表、散文代码示例中面向用户的注释图片 alt 文本。不翻译Dont translate代码块与行内代码命令与文件路径URL 与链接目标专名Claude、GitHub、npm。视上下文Context-dependentUI 元素原文带引号则保留引号代码中的技术注释解释性的如# Set up the client可译纯技术性的如// Initialize SDK保留。针对常见的边界情况计划给出了固定应对策略多义技术词在术语表中加 context 注记按领域选定唯一译法如 agent 在“代理/智能体/代理程序”中三选一并记录理由品牌与产品名一律保留英文仅当存在官方中文名才翻译指向未翻译文件的链接过渡期内允许中文文档链向英文文档并在链接后加(English)标注同时记录进状态文件跟踪混合内容表格列头翻译单元格内容非技术则翻译单元格内代码块保留截图与图图片本身不修改alt 文本改为中文并在文档中注明截图含可翻译 UI 文字。错误恢复策略也是显式定义的术语表冲突 → 停下来、解决、再继续断链 → 记录到 issues 文件、在文中打标、继续翻译错误 → 回滚该文件、修复、重新验证。五、质量门禁两个校验脚本的源码解析计划 Task 1 的基建部分创建了两个校验脚本对应仓库中的 scripts/validate-links.sh 和 scripts/validate-glossary.sh。当前仓库中的版本是“确定性deterministic”重写版比计划中的初版更有工程价值值得逐层拆解。5.1 链接校验validate-links.sh脚本用 bash 定位项目根目录后内嵌一段 Python 执行真正的校验逻辑扫描根README.md、docs/、docs_zh-CN/三个根下的全部.md文件并显式排除docs/maintainers/backups历史快照目录EXCLUDED_PATH_PARTS {(docs, maintainers, backups)}代码围栏剥离strip_code_fences()会先去掉 围栏内的内容避免把代码示例中的text误判为链接链接提取正则(?!!)\[[^\]]\]\(([^)])\)提取 Markdown 链接负向后行断言(?!!)排除图片语法![...]目标分类空目标、#锚点、http(s)://、mailto:视为外部或锚点链接跳过外部链接只抽样记录前 20 条不实际发起网络请求路径解析以/开头的目标按仓库根解析否则按源文件所在目录解析resolve_link再对 URL 编码做unquote、对#anchor做剥离报告输出写入docs_zh-CN/link-validation-report.txt包含检查链接总数、断链列表源文件 → 原始目标 → 解析后路径与外部链接抽样退出码发现断链返回 1否则 0 —— 可直接接入 CI 作为门禁。bash scripts/validate-links.sh # 输出示例 # Link validation complete. Report saved to: docs_zh-CN/link-validation-report.txt # Internal links checked: N # Broken internal links: 0最终验证报告 final-validation-report.md 记录了初版脚本的一个已知限制仅检查基本文件名、不解析完整相对路径曾把../../CATALOG.md这类链接误报为问题实际链接有效。当前仓库中的重写版已改为真正的路径感知解析这个“误报 → 脚本升级”的过程本身也是该翻译工程持续维护的实证。5.2 术语表一致性validate-glossary.sh该脚本依赖jq对docs_zh-CN/.glossary.json做结构级体检报告写入docs_zh-CN/glossary-consistency-report.txtJSON 合法性jq empty先验证语法元数据一致性抽取metadata.version / created / last_updated并交叉核对metadata.total_terms与.terms对象实际条目数ACTUAL_TERM_COUNT两者不一致直接判失败——这正是 2.1 节提到的total_terms字段在工程上的用途字段完整性逐条检查每个术语必须是含非空translation字符串的对象缺失即报告Missing translation: key重复键检查jq -r .terms | keys[] | sort | uniq -d检测重复术语键Top 10 术语展示按字母序输出前 10 条“英文词: 中文译法”便于人工抽查退出码校验失败返回 1同样可接 CI。bash scripts/validate-glossary.sh # 输出示例 # Glossary validation complete. Report saved to: # docs_zh-CN/glossary-consistency-report.txt # Summary: # Total Terms: 199 # Status: Valid ✓5.3 问题跟踪与批验证报告除脚本外基建还包含两个人工/半自动跟踪文件translation-status.md68 个文件按 5 个优先级逐项打勾的进度表 术语表统计 批次进度是全局的单一事实来源translation-issues.md分“断链 / 术语冲突 / 翻译歧义 / 边界情况”四节的问题台账并规定了统一的问题报告格式标题、文件、日期、严重级、描述、建议方案、状态。每一批翻译完成后运行“批量验证”对应计划 Task 7、Task 12 等跑链接校验 → 跑术语一致性校验 → 人工 Markdown 审查标题层级、代码块格式、表格格式、中文全角标点、避免英中混杂句式→ 产出一份该批的验证报告。仓库中实际存在 priority1-validation-report.md 至 priority4-validation-report.md 以及 final-validation-report.md与计划中“每批一份验证报告”的要求一一对应。以 Priority 1 报告为例它核对了 4 篇共 1,710 行译文、链接验证 PASS、术语表 v1.0.4 共 60 词并给出 “Proceed to Priority 2” 的放行结论——这就是“批与批之间设检查点”的落地形态。六、最终验证与质量指标计划的收尾Task 73-74定义了全量验证步骤实际执行结果记录在 final-validation-report.md全量验证命令计划 Task 73 原文# 验证翻译文件总数与术语表规模 echo Translated files: $(find docs_zh-CN -name *.md | wc -l) echo Total terms in glossary: $(jq .metadata.total_terms docs_zh-CN/.glossary.json) # 检查残留占位符 grep -r TODO\|TRANSLATE ME\|TBD docs_zh-CN/ || echo No placeholders found ✓实测质量指标最终报告中的验收表指标目标实际文件覆盖率100%100%68 篇核心 8 篇支撑文档术语一致性≥95%≥98%残留占位符00内部链接完整性100%100%1 个脚本误报无真实断链格式保持100%100%代码块保持英文translation-status.md 的最终汇总亦与此一致68/68 文件完成、168 词术语表v1.0.14、零断链、Markdown lint 通过、“READY FOR CHINESE USER REVIEW”。随后 Task 74 按模板创建了 Pull RequestPR 描述模板内置了 Summary / Changes / Translation Quality / Test Plan 四段式结构与中文审阅人复核清单使“机器产出 → 人类终审”的交接有据可依。七、可复用的方法论小结从这份计划及其产物可以提炼出一套可迁移到任意多语言文档工程的模式术语表先行先小后大从 35 个奠基词起步每译一篇回填新词最终 199 词metadata.total_terms与实际条目数的强一致性由脚本强制防止元数据漂移依赖顺序分批先译“设定基调”的核心用户文档并锁定术语表再译依赖术语的工具指南、进阶文档、贡献者文档、维护者文档每批独立验证、独立提交三文件追踪体系status进度与术语统计、issues问题台账与统一问题格式、glossary术语真相源分离职责各自可被脚本校验确定性校验脚本链接脚本剥离代码围栏后做路径感知解析并以退出码接入 CI术语脚本做 JSON 合法性、元数据交叉核对、字段完整性、重复键四重检查Agent 可执行的计划格式checkbox 步骤、每步的 Files 清单、可直接粘贴的命令与 commit 模板使计划本身就是任务书这也是该文件放在docs_zh-CN/superpowers/plans/而非普通 docs 的原因。需要说明的是translation-status.md 顶部的 2026-09-06 更新提醒读者翻译完成标记是历史快照中文文档后续需随英文源如package.json版本变更、发布/回滚流程更新做漂移修复。因此若在本仓库维护中文文档正确姿势是修改前查阅 skills_index.json 与英文docs/对应源文件翻译或修订后运行bash scripts/validate-links.sh与bash scripts/validate-glossary.sh两个门禁并按 translation-issues.md 的格式登记遇到的断链或术语冲突。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
