企业官网建设流程全解析

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 Stack：Markdown、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 个核心术语的奠基术语表，可以归为四类：

1. 核心概念词：skills→技能、repository→仓库、bundles→捆绑包、workflows→工作流、agents→代理、plugin→插件、marketplace→市场；
2. 保留英文的品牌/工具名：Claude、Cursor、Gemini、GitHub、MCP、npm、CLI（注明“代码中保持 CLI 原样”）；
3. 通用开发词：installation→安装、configuration→配置、deployment→部署、testing→测试、security→安全、development→开发、documentation→文档、version→版本、release→发布；
4. 角色与文档体裁词：contributor→贡献者、maintainer→维护者、guide→指南、tutorial→教程、example→示例、community→社区、feedback→反馈、terminal→终端、directory→目录、categories→类别、integration→集成、features→功能。

一个关键决策是“英文保留原则”：技术品牌词（如 “Claude Code”）不做硬译（不译成“克劳德代码”），只有存在官方中文名时才翻译——这是设计文档 Key Design Decisions 中明确写出的规则。

2.4 术语表的真实演化轨迹

从仓库当前实际产物看，术语表按计划持续生长：

也就是说，翻译完成之后术语表仍在随后续文档维护继续增补，从 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）：

分层逻辑与翻译状态文件 translation-status.md 完全对应：该文件记录了每一批（Batch 1-5）的完成打勾，并在顶部用 2026-09-06 的一致性更新声明“完成标记记录翻译历史，不表示所有页面与当前实现同步”，体现了翻译产物需要随英文源持续漂移修复的维护现实。

3.1 单个文件的翻译执行单元

以 Priority 1 的四个文件为例，计划为每个文件规定了完全一致的 5 步执行模式（Task 3-6）：

1. Step 1: Read source file—— 先读英文原文（如docs/users/faq.md）理解结构与内容；
2. Step 2: Translate—— 在docs_zh-CN/对应路径创建中文译文，翻译规则为：保留全部 Markdown 结构；翻译标题、列表与说明文字；代码块、命令、文件路径保持英文；专名保留英文（Claude Code、GitHub、npm）；术语表术语全文一致；链接文字翻译但 URL 不变；
3. Step 3: Extract and add new terms—— 把翻译中遇到的新术语回填进docs_zh-CN/.glossary.json；
4. Step 4: Update translation status—— 在状态文件中把对应 checkbox 从- [ ]改为- [x]，并更新 Completed/Remaining 计数（如 “Priority 1: 1/4 complete”）；
5. 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 文本。

不翻译（Don't translate）：代码块与行内代码；命令与文件路径；URL 与链接目标；专名（Claude、GitHub、npm）。

视上下文（Context-dependent）：UI 元素（原文带引号则保留引号）；代码中的技术注释（解释性的如# 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.txt：

1. JSON 合法性：jq empty先验证语法；
2. 元数据一致性：抽取metadata.version / created / last_updated，并交叉核对metadata.total_terms与.terms对象实际条目数（ACTUAL_TERM_COUNT），两者不一致直接判失败——这正是 2.1 节提到的total_terms字段在工程上的用途；
3. 字段完整性：逐条检查每个术语必须是含非空translation字符串的对象，缺失即报告Missing translation: <key>；
4. 重复键检查：jq -r '.terms | keys[]' | sort | uniq -d检测重复术语键；
5. Top 10 术语展示：按字母序输出前 10 条“英文词: 中文译法”便于人工抽查；
6. 退出码：校验失败返回 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.md：68 个文件按 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 ✓"

实测质量指标（最终报告中的验收表）：

translation-status.md 的最终汇总亦与此一致：68/68 文件完成、168 词术语表（v1.0.14）、零断链、Markdown lint 通过、“READY FOR CHINESE USER REVIEW”。随后 Task 74 按模板创建了 Pull Request，PR 描述模板内置了 Summary / Changes / Translation Quality / Test Plan 四段式结构与中文审阅人复核清单，使“机器产出 → 人类终审”的交接有据可依。

七、可复用的方法论小结

从这份计划及其产物可以提炼出一套可迁移到任意多语言文档工程的模式：

1. 术语表先行，先小后大：从 35 个奠基词起步，每译一篇回填新词，最终 199 词；metadata.total_terms与实际条目数的强一致性由脚本强制，防止元数据漂移；
2. 依赖顺序分批：先译“设定基调”的核心用户文档并锁定术语表，再译依赖术语的工具指南、进阶文档、贡献者文档、维护者文档；每批独立验证、独立提交；
3. 三文件追踪体系：status（进度与术语统计）、issues（问题台账与统一问题格式）、glossary（术语真相源）分离职责，各自可被脚本校验；
4. 确定性校验脚本：链接脚本剥离代码围栏后做路径感知解析并以退出码接入 CI；术语脚本做 JSON 合法性、元数据交叉核对、字段完整性、重复键四重检查；
5. 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