| name | linasite-sync-i18n |
| description | 检测 apps/lina-site/docs/ 中文主稿与 apps/lina-site/i18n/en/docusaurus-plugin-content-docs/current/ 英文翻译之间的缺漏和内容差异，并进行补全修复。当 docs/ 中新增或更新了文档、或需要全量同步审查时使用。 需要手动调用该技能，禁止自动调用。 |
linasite-sync-i18n：文档 i18n 同步与翻译
对中文主稿进行全面审查，确保每篇文档都有对应的地道英文翻译，并与中文内容保持同步。本技能输出自然、专业的英文文档和标题——而非机械翻译。
核心原则：
- 路径镜像 —
docs/<path>.md 对应 i18n/en/docusaurus-plugin-content-docs/current/<path>.md
- slug 是唯一标识 — 每篇文档的
slug 字段是规范 URL，翻译时绝不修改
- 标题贴近路由 — frontmatter
title 应尽可能与 slug 或镜像路径所表达的英文路由名称一致，例如 /docs/architecture/core-host 对应 Core Host
- 地道英文优先 — 先理解内容，再以英文习惯表达；正文、frontmatter 标题和各级标题都绝不逐字翻译
- 中文主稿为准 —
docs/ 是唯一事实来源，英文版跟随中文版更新
- 标题质量同等重要 — 文档标题是导航、SEO 和读者第一印象的一部分，必须符合英语技术文档的命名习惯
- 当前变更优先 — 每次执行先检查
apps/lina-site/docs/ 的 git status；凡是当前工作区已修改、新增、重命名或删除的中文 Markdown 文档，都属于强制同步范围
目录路径
| 角色 | 路径 |
|---|
| 中文主稿 | apps/lina-site/docs/ |
| 英文 i18n | apps/lina-site/i18n/en/docusaurus-plugin-content-docs/current/ |
工作流程
0. 优先检查当前 docs 变更
在做任何全量扫描、差异报告或翻译前，先检查当前中文主稿目录的 git status：
git status --short -- apps/lina-site/docs
把输出中影响 apps/lina-site/docs/**/*.md 的条目整理为当前变更同步清单：
M / MM / AM：读取当前工作区版本，按镜像路径更新对应英文 i18n 文件A / ??：新增中文文档，创建对应英文 i18n 文件R：确认新路径的镜像文件存在并同步当前内容；必要时说明旧英文路径可能需要清理，但不要自动删除用户未确认的文件D：中文主稿已删除，报告对应英文 i18n 文件可能需要删除；除非用户明确要求，否则不要自动删除英文文件
处理规则：
- 如果当前变更同步清单非空，必须先同步这些文档；不要因为还没有完成全量审查而跳过它们。
- 当前变更同步清单中的修改和新增 Markdown 文档不属于可选差异，必须被翻译或重新翻译到英文 i18n 镜像路径。
- 对当前变更同步清单中的文件，允许在开始前简要报告将处理的文件，但不要把“是否同步这些变更”作为可拒绝选项；只在遇到路径不匹配、删除文件、或语义不清的情况时请求用户决策。
- 完成当前变更同步后，再根据用户请求决定是否继续进行全量缺漏和差异审查。
1. 扫描中文主稿
列出中文主稿目录中的所有 Markdown 文件：
find apps/lina-site/docs -name "*.md" | sort
跳过非内容文件（.DS_Store、_category_.json 等）。
对每个 .md 文件记录：
- 相对路径（相对于
apps/lina-site/docs/，例如 docs/1000-concepts/1000-ai-native.md）
- 期望的 i18n 路径：
apps/lina-site/i18n/en/docusaurus-plugin-content-docs/current/<relative-path>
- slug：从 frontmatter 的
slug: 字段读取
- 路由名称候选：优先从
slug 的最后一段推导；没有 slug 时，从文件名去掉数字前缀后推导
- 中文标题：frontmatter
title 以及正文中的 ##/### 标题
2. 扫描已有英文翻译
列出 i18n/en 目录中已存在的所有 .md 文件：
find apps/lina-site/i18n/en/docusaurus-plugin-content-docs/current -name "*.md" | sort
对每个文件读取其 frontmatter 中的 slug 和 title，构建索引：slug → i18n/en 文件路径，并记录正文中的 ##/### 标题用于自然度和路由一致性检查。
3. 对每篇中文文档进行分类
将每篇中文主稿归入以下四个状态之一：
| 状态 | 判断条件 | 处理方式 |
|---|
| 已同步 | 镜像路径存在且内容与中文版基本一致 | ✓ 无需操作 |
| 内容不同步 | 镜像路径存在，但内容与中文版差异较大 | 按翻译规范重新翻译并覆盖 |
| 路径不匹配 | 镜像路径不存在，但 slug 在其他 i18n/en 文件中匹配到 | 提交用户决策——可能是有意重命名 |
| 缺失 | 镜像路径不存在，且 slug 在任何 i18n/en 文件中均未找到 | 需要创建英文翻译 |
内容差异判断标准
当文件存在于镜像路径时，对比中英文内容：
- 读取中文源文件的正文内容（去除 frontmatter）
- 读取对应英文文件的正文内容
- 判断为差异较大（需要重新翻译）的条件：
- 英文文件的章节数量与中文明显不符（差异超过 1 个一级标题）
- 英文文件缺少中文中存在的主要内容段落
- 英文文件中存在大量未翻译的中文字符（代码块外）
- 英文文件内容篇幅不足中文的 60%（排除代码块）
- frontmatter
title 或正文标题明显机械直译、不符合英语技术文档习惯，或与同类页面标题风格明显不一致
- frontmatter
title 与 slug / 路径所表达的英文路由名称明显不一致，且内容没有支持这种差异
- 判断为基本一致（无需操作）的条件：
- 章节结构对应
- 核心内容已翻译
- frontmatter
title 和正文标题自然、专业、准确，符合英语技术文档命名习惯
- 少量措辞差异属正常范围
标题与路由一致性判断标准
检查英文文档时，必须同时审查 frontmatter title 与正文 ##/### 标题。标题不只是翻译结果，也是站点导航、侧边栏、搜索和 SEO 的入口。
先为每篇文档推导英文路由名称候选：
- 优先读取 frontmatter
slug，取最后一个有意义的路径段。
/docs/architecture/core-host → core-host → Core Host/quickstart → quickstart → Quickstart 或按站点习惯写作 Quick Start
- 如果没有
slug，从文件名推导，先去掉排序数字和后缀。
1000-ai-native.md → ai-native → AI-Native2000-wasm-plugins.md → wasm-plugins → WASM Plugins
- 如果路由段是产品名、API 名、协议名或固定术语，按既有英文写法保留大小写。
openapi → OpenAPIwasm → WASMi18n → i18n
- 将该候选与中文标题和全文内容一起判断。标题不要求机械等于路由段，但应表达同一个页面入口概念。
标题命名优先级：
- 路由名称优先：当
slug / 路径已经给出清晰英文概念时，frontmatter title 优先采用该概念的自然标题形式。
- 内容校准：如果中文标题比路由更具体，或路由只是缩写，阅读正文后补足必要限定词。
- 英语读者优先：不要为了贴合中文标题而牺牲英语自然度；也不要为了贴合路由而产生命名不清的标题。
- 一致性优先：同目录、同类型页面保持标题风格一致；必要时读取邻近 2 到 3 篇英文文档作为参照。
优先使用英语技术文档中自然的名词短语或动作短语：
slug: /docs/architecture/core-host 的标题应接近 Core Host，不要译成 Core Main Machine。slug: /docs/development/commands 的标题应接近 Development Commands，不要仅按中文写成 Commands for Development。- 中文“开发指令”应译为
Development Commands，不要机械写成 Dev Commands，除非同一导航体系明确使用短标签。
- 中文“OpenAPI接口文档”更自然的是
OpenAPI Reference，不要写成 OpenAPI Interface Documentation。
- 中文“服务配置管理”应表达为
Service Configuration 或 Service Configuration Management，不要只写 Configuration 导致语义过泛。
- 中文“原生多租户能力”应表达为
Native Multi-Tenancy，不要省略关键定位。
- 正文标题避免重复、笨重或直译表达，例如用
Scheduled Task Execution 代替 Scheduled Task Scheduling，用 Importing into Third-Party Tools 代替 Third-Party Tool Import。
标题润色原则：
- 准确：保留中文标题的技术指向和范围，不为了简短丢失核心限定词。
- 自然：优先选择英语技术文档常见说法，例如
Reference、Configuration、Execution、Development、Internationalization。
- 专业：避免口语缩写和内部简称，如
Dev，除非该页面是窄导航标签或同级文档统一采用该表达。
- 一致：同一目录下同类标题使用一致风格，例如
Development Commands、Development Tools。
- 贴近路由：
slug / 路径中的英文路由名通常代表站点希望用户记住的页面名称，标题应优先采用其自然可读形式。
- 不过度翻译：产品名、命令、API 名称、配置键名、插件 ID 和约定术语保持原样。
4. 报告差异分析
在执行任何修改前，先向用户展示结构化摘要：
## i18n 同步报告
### 已同步（无需操作）
- docs/quick/1000-overview.md ✓
- docs/community/1000-community.md ✓
...
### 内容不同步（需要重新翻译）
- docs/docs/1000-concepts/1000-ai-native.md
原因：英文版缺少"规范驱动开发"章节，且篇幅仅为中文版的 45%
操作：按翻译规范重新翻译并覆盖
### 路径不匹配（slug 匹配到其他路径）
- docs/docs/1000-concepts/1000-ai-native.md
Slug: /docs/ai-native
发现于：i18n/en/.../docs/core-concepts/built-in-capabilities.md
→ 请确认：是否有意为之？（y = 跳过，n = 在镜像路径重新创建）
### 缺失（需新建英文翻译）
- docs/docs/2000-architecture/1000-core-host.md [slug: /docs/architecture/core-host]
- docs/docs/3000-plugin-development/2000-wasm-plugins.md [slug: /docs/plugin-development/wasm]
...
总计：X 已同步，Y 内容不同步，Z 路径不匹配，W 缺失
在执行前向用户确认：
- 当前变更同步清单中的修改、新增或重命名 Markdown 文档：报告将同步，但不要询问是否跳过
- 非当前变更范围内的内容不同步：确认是否重新翻译并覆盖
- 路径不匹配：确认是跳过还是在镜像路径新建
- 非当前变更范围内的缺失：确认是否继续翻译
- 删除的中文文档：确认是否删除对应英文 i18n 文件
5. 翻译或重新翻译文件
对每个确认需要处理的文件（包括缺失和内容不同步两类）：
a. 声明开始： ## 翻译中：<source-path>
b. 完整阅读中文源文件 — 通读全文，理解：
- 文档主题及其在 LinaPro 体系中的定位
- 技术术语及其准确英文对应词
- slug / 文件名表达的英文路由名称，以及它与中文标题、正文主题之间的关系
- 文档语气（概念介绍、操作指引、参考手册等）
- 结构元素：标题层级、代码块、提示框、Mermaid 图表
c. 以地道英文撰写 — 把自己当作原创技术文档作者，而非翻译者：
| 翻译原则 | 说明 |
|---|
| 先理解再动笔 | 通读全文后再写第一个英文单词 |
| 自然表达 | 使用英语技术写作中惯用的句式结构 |
| 保持技术精度 | LinaPro 专属术语、API 名称、配置键名保持原样 |
| 匹配语气 | 概念文档保持概念性，操作指引保持步骤性 |
| 标题与结构 | 保持相同层级结构；frontmatter title 应尽可能采用 slug/路径路由名称的自然英文形式，正文标题必须自然、专业、准确，必要时重写为英语技术文档习惯表达 |
| 代码块 | 绝不翻译代码、代码注释或 CLI 命令 |
| Mermaid 图表 | 翻译节点标签和边标签，保留图表类型和语法 |
| Frontmatter | 地道翻译 title、description、keywords；slug 和 sidebar_position 保持不变 |
d. Frontmatter 处理示例：
---
slug: '/docs/architecture/core-host'
title: '核心主机'
hide_title: true
description: '本文介绍...'
keywords:
- 核心主机
- 插件
---
---
slug: '/docs/architecture/core-host'
title: 'Core Host'
hide_title: true
description: 'This page covers...'
keywords:
- core host
- plugin
---
标题翻译时不要把中文词序硬搬到英文中。先根据 slug 或文件名推导英文路由名称，再结合全文内容决定自然标题。允许在不改变含义的前提下改写为更自然的英文技术文档标题：
slug: '/docs/reference/openapi'
title: 'OpenAPI接口文档'
slug: '/docs/reference/openapi'
title: 'OpenAPI Reference'
再例如：
slug: '/docs/architecture/core-host'
title: '核心主机'
slug: '/docs/architecture/core-host'
title: 'Core Host'
e. 写入文件：
- 确保父目录存在：
mkdir -p <parent-dir>
- 将翻译后内容写入镜像路径（缺失时新建，内容不同步时覆盖）
f. 完成声明： ✓ 完成：<i18n-path>
6. 验证输出
所有翻译完成后：
find apps/lina-site/i18n/en/docusaurus-plugin-content-docs/current -name "*.md" | sort
重新执行差异分析，确认缺失和不同步文件均已归零。
输出最终摘要：
## 同步完成
- 新建翻译：N 篇
- 重新翻译（内容不同步）：M 篇
- 跳过（已同步）：K 篇
- 用户决策（路径不匹配）：P 篇
### 本次处理的文件
- apps/lina-site/i18n/en/.../docs/2000-architecture/1000-core-host.md（新建）
- apps/lina-site/i18n/en/.../docs/1000-concepts/1000-ai-native.md（重新翻译）
...
翻译质量检查清单
写入每个译文文件前，在脑内逐项确认：
执行守则
- 严禁修改
slug 字段 — 这是规范 URL，必须与中文源文件保持一致
- 通读全文再翻译 — 不允许逐段翻译，必须在理解全文后再动笔
- 标题先理解再命名 — 标题必须传达页面定位和技术范围，并尽可能贴近
slug / 路径中的英文路由名称；必要时意译或改写为英语技术文档常用标题
- 修改前先确认 — 展示差异报告并获得用户确认后再执行任何写入
- 路径不匹配须人工决策 — 不得静默跳过或覆盖，必须提交用户决策
- 禁止机械直译 — 若某句话或某个标题用英文说起来不自然，重写它，只要意思相同
- 保护代码完整性 — 不得修改代码块、行内代码或 CLI 示例中的任何内容
- 参考现有英文文档风格 — 翻译前先阅读 2～3 篇已有的 i18n/en 文档，匹配用词和语气
- 逐文件处理 — 声明 → 翻译 → 写入 → 确认，完成后再处理下一篇
- 内容不同步时覆盖整文 — 不做局部 patch，重新翻译整篇以确保一致性
