ci-translate

Imported from CodeIgniter-Chinese/codeigniter4-user-guide (.claude/skills/ci-translate/SKILL.md). Install upstream with npx skills add CodeIgniter-Chinese/codeigniter4-user-guide --skill ci-translate. Copyright stays with the author.

CodeIgniter 用户指南（Sphinx + reStructuredText）翻译 skill。

工作流：备份英文原文 → 翻译 → guard → 审查 → 修订 → guard → 定稿 → 清理备份

使用方法

/ci-translate source/libraries/caching.rst

参数

• 只接受一个参数：待翻译的 .rst 文件路径
• 文件路径为 $ARGUMENTS
• 记作 FILE_PATH="$ARGUMENTS"

任务目标

1. 生成可直接提交的中文 .rst
2. 保持 reST/Sphinx 结构零破坏
3. 保证信息零遗漏、零增添、零篡改
4. 在退出前完成 guard + 审查闭环，而不是只翻译不验收

执行步骤

1. 备份英文原文

cp "$FILE_PATH" "$FILE_PATH.en.bak"

一律以 $FILE_PATH.en.bak 作为英文对照源；

2. 翻译并回写原文件

读取 $FILE_PATH.en.bak，将英文 .rst 翻译为中文后覆盖写回 $FILE_PATH。

翻译时遵守以下统一规则。

A. 格式零破坏（关键规则 + 示例）

以下内容只翻译可见中文内容，不改结构本身。

A1. reST 指令保持英文

❌ 错误：
.. 注意:: 此方法已弃用。

✅ 正确：
.. note:: 此方法已弃用。

指令名 .. note::、.. warning::、.. code-block::、.. deprecated::、.. versionadded::、.. php:method:: 等必须保持英文。

A2. 交叉引用保持英文

❌ 错误：详见 :文档:`incoming`。

✅ 正确：详见 :doc:`incoming`。

❌ 错误：使用 :方法:`find()`。

✅ 正确：使用 :meth:`find()`。

角色名 :doc:、:meth:、:class:、:func:、:ref: 等必须保持英文，反引号内的目标也保持英文。

A3. 段落结尾双冒号必须保留

❌ 错误：设置变量如下：
❌ 错误：设置变量如下：：

✅ 正确：设置变量如下::

RST 中 :: 表示后续缩进内容为代码块/文字块，严禁改为中文冒号。

A4. 其他保持原样的元素

• 显式目标、锚点：.. _label: 保持原样
• 替换标记：|substitution| 保持原样
• 缩进、空行、列表层级、表格对齐不要“顺手格式化”

B. 代码与字面量零翻译

以下内容一律保持英文原样。

B1. 代码块内容不翻译

❌ 错误：
.. code-block:: php

    $配置 = new 配置();  // 翻译了变量名和类名
    $配置->设置('键', '值');  // 翻译了方法和参数

✅ 正确：
.. code-block:: php

    $config = new Config();  // 完全保持英文
    $config->set('key', 'value');  // 完全保持英文

B2. 行内字面量不翻译

❌ 错误：调用 ``查找()`` 方法查询数据库。

✅ 正确：调用 ``find()`` 方法查询数据库。

B3. 类名、方法名、属性、常量不翻译

❌ 错误：会话类提供会话管理功能。

✅ 正确：Session 类提供会话管理功能。

❌ 错误：使用邮件类发送邮件。

✅ 正确：使用 Email 类发送邮件。

B4. 配置键、参数名、URL、文件路径不翻译

❌ 错误：设置 ``数据库.主机`` 为 ``本地主机``。

✅ 正确：设置 ``database.hostname`` 为 ``localhost``。

保持英文的完整清单：代码块、命令行示例、配置片段、日志输出、行内字面量 ... 内的内容、类名、方法名、属性、常量、配置键、命名空间、文件路径、URL、HTTP 头字段名、状态码、参数名。

C. 信息零遗漏（高危风险点）

翻译时必须逐项核对，严禁遗漏或弱化以下信息。

C1. 版本限定（Critical）

英文：This feature is only available in 4.3 or later.
❌ 错误：此功能在 4.3 版本可用。（遗漏了 only 和 or later）
✅ 正确：此功能仅在 4.3 或更高版本中可用。

英文：Before 4.0, use the legacy syntax.
❌ 错误：4.0 版本使用传统语法。（时间关系错误）
✅ 正确：4.0 之前请使用传统语法。

C2. 语气强度（Critical）

英文：You must set this parameter.
❌ 错误：你需要设置此参数。（must → 需要，弱化）
✅ 正确：你必须设置此参数。

英文：This is required.
❌ 错误：这是建议的。（required → 建议，严重弱化）
✅ 正确：这是必需的。

英文：Not allowed in production.
❌ 错误：不建议在生产环境使用。（not allowed → 不建议）
✅ 正确：不允许在生产环境使用。

C3. 条件与前提（Major）

英文：If configured, this feature will auto-enable.
❌ 错误：此功能将自动启用。（遗漏了 if configured 条件）
✅ 正确：如已配置，此功能将自动启用。

英文：When enabled, call this method.
❌ 错误：调用此方法。（遗漏了 when enabled 前提）
✅ 正确：启用后调用此方法。

英文：Unless specified, the default is used.
❌ 错误：使用默认值。（遗漏了 unless）
✅ 正确：除非另有指定，使用默认值。

C4. 技术细节（Critical）

英文：Returns null if not found.
❌ 错误：找不到返回空。（null 被模糊化）
✅ 正确：未找到时返回 null。

英文：Set timeout to 60 seconds.
❌ 错误：设置超时。（遗漏 60 seconds）
✅ 正确：设置 60 秒超时。

英文：The $id parameter (int) must be positive.
❌ 错误：参数 $id 必须为正数。（遗漏了 int 类型）
✅ 正确：参数 ``$id`` (int) 必须为正数。

信息遗漏检查清单：

• 版本/时间限定：4.3 or later、before 4.0、since 4.2
• 语气强度：must（必须）、should（应该）、only（仅）、required（必需）、not allowed（不允许）
• 条件与前提：if（如果）、when（当...时）、before（在...前）、after（在...后）、unless（除非）
• 安全警告与限制
• 数值、版本号、参数名、返回值、类型、配置键

不要补写原文没有的解释，也不要弱化或强化原意。

D. 中文表达规则

翻译腔是中文技术文档最常见的质量问题。以下规则的核心思路是：中文技术文档不需要明确主语时就不需要主语，不需要代词时就不用代词，不需要指示词时就不用指示词。

D1. 意义驱动重写

先理解原意，再用自然中文重写；不要逐句硬贴英文句式。

英文：When you need to validate user input before saving it to the database, you should use the Validation class which provides comprehensive validation rules and custom error messages that can be displayed to users.

❌ 直译腔：当你需要在使用数据库保存数据之前进行验证的时候，你应该使用 Validation 类，它提供了全面的验证规则和可以展示给用户的自定义错误消息。

✅ 重写：保存到数据库前如需验证用户输入，应使用 Validation 类。该类提供全面的验证规则和自定义错误消息。

D2. 消除冗余代词（最重要）

这是翻译腔的根源。英文习惯用代词指代，中文技术文档通常不需要。以下逐类列出常见模式。

D2a. 删除“你/你的/你们”

英文技术文档用“you”作为泛指读者，中文不需要这个代词。

D2b. 删除“它/它们/其”

英文用 it/they/its 指代前文提到的事物，中文技术文档通常省略或直接用名词。

D2c. 慎用“这/这个/这些/该”

“这/该”不是完全禁用，但每出现一次都要审视是否真的需要。

D2d. 删除冗余的“的”

中文技术文档中，“的”字经常被不必要地保留。

D3. 中英文间距

中文与英文/数字之间加半角空格；数字与单位不加空格。

❌ 错误：CodeIgniter4
✅ 正确：CodeIgniter 4

❌ 错误：HTTP请求
✅ 正确：HTTP 请求

❌ 错误：50 ms
✅ 正确：50ms

D4. 标点规范

中文句子使用全角标点。

D5. 拆分长句 + 主动语态 + 动词化

超长英文句（>25词）优先拆成 2–3 个中文短句；优先动词化表达，减少“进行……的……”和被动语态。

英文：Data is validated before being saved to the database.
❌ 被动：数据在被保存到数据库之前被验证。
✅ 主动：保存到数据库前先验证数据。

D6. 恰当处理英文后置定语与从句（防范长句嵌套）

英文常使用 that/which/who/where 引导的后置定语从句。翻译时应根据从句长度灵活处理：

• 短从句：可自然转化为中文的前置定语，保持句子紧凑。
• 长从句或嵌套从句：严禁直译为冗长的“……的”前置定语。应将其拆分为并列短句，或转化为条件状语。

英文：It returns an array that contains all the user profiles.
❌ 翻译腔（带多余代词）：它返回一个包含了所有用户信息的数组。
❌ 错误拆分（太零碎）：返回一个数组，包含所有用户信息。
✅ 地道中文（短定语）：返回一个包含所有用户信息的数组。

英文：The push() method is used to push a new value onto a session value that is an array.
❌ 翻译腔（长/生硬定语）：将新值推入为数组的 Session 值中。
✅ 地道中文（转条件）：如果 Session 值是数组，可使用 push() 方法追加新值。
✅ 地道中文（拆分）：push() 方法用于向数组类型的 Session 值中添加新元素。

E. 术语与译名

优先遵循项目现有中文用户指南；同一文档内必须保持一致。翻译时遇到以下术语必须使用标准译法：

核心框架术语（强制一致）

补充约束：

• CodeIgniter 类名、方法名、常量、配置键一律保留英文
• library 不做单一死板映射：优先沿用当前章节或现有文档的既有译法；若无既有上下文，再按项目约定判断
• 类名翻译时与中文字符间加空格：Session 类、Config 实例

F. 翻译执行步骤（在心里执行，不输出过程）

步骤 1：通读理解

• 先完整阅读整段/整节，理解核心语义和逻辑关系。

步骤 2：抽取信息点

• 标记所有必须保留的信息：版本限定、条件、限制、步骤、例外、警告、数值、参数名。

步骤 3：中文重组

• 用自然中文重新组织，不要硬贴英文句式。
• 遇到 that is... / which is... 等后置定语，坚决拆分为短句或转化为条件句，拒绝超长前置定语。
• 删除冗余代词，优先主动语态和动词化表达。

步骤 4：格式保护

• 确保 reST 指令、角色、代码块、字面量等原样保留。

步骤 5：逐项核对

• 对照英文原文，检查“条件、限制、版本限定”是否遗漏，代码、字面量是否被误译。

步骤 6：消除翻译腔（关键步骤）

• 逐句检查是否有“你/你的/它/它们/这/这个/这些”。
• 遇到“这允许/这意味着/这将”改为“可/即/将”。
• 遇到“你可以/你应该”删除“你”；遇到“它会/它返回”删除“它”。
• 删除不必要的“的”字（“X的配置”→“X配置”）。

步骤 7：术语和排版检查

• 确认标准术语、中英文空格、全角标点、标题装饰线长度。

3. 运行 guard

翻译完成后立即运行：

python3 "${CLAUDE_SKILL_DIR}/scripts/validate-rst.py" --no-build "$FILE_PATH"

如果失败，先修复格式问题，再重复执行，直到 guard 通过。

4. 进行静态审查

审查目标不是“只生成一份报告”，而是驱动修订并最终定稿。审查必须以 $FILE_PATH.en.bak 为英文对照源。

审查重点与检查方法：

快速问题定位模式：

# 格式破坏（Critical）
grep -n "\.\. 注意::\|\.\. 警告::" "$FILE_PATH"        # 中文指令
grep -n "：文档：\|：方法：" "$FILE_PATH"              # 中文角色
grep -n "：：$\|：$" "$FILE_PATH"                      # 冒号错误

# 翻译腔扫描（Major，重点扫描）
grep -n "你可以\|你应该\|你的\|你要\|你将" "$FILE_PATH"      # 你/你的
grep -n "它会\|它返回\|它提供\|它们\|它的" "$FILE_PATH"       # 它/它们
grep -n "这允许\|这意味着\|这将\|这是因为" "$FILE_PATH"      # 这...
grep -n "为.*的\|是一个.*的" "$FILE_PATH"                # 潜在的直译长定语/从句嵌套

5. 审查报告格式

以 Markdown 输出，必须包含：总体结论、Critical 风险、Major 风险、Minor 风险、术语快照、格式扫描摘要。 每条具体问题需给出：位置、原文、译文、问题、建议、影响。

6. 按报告修订并复验

• 只要还有 Critical 或 Major，就必须继续修订 $FILE_PATH
• 每轮修订后都要重新运行 guard 并再次审查，直到无严重问题。

7. 定稿与收尾

定稿条件：guard 通过，审查无 Critical / Major，译文术语一致、表达自然无长定语嵌套。 完成后删除备份：rm -f "$FILE_PATH.en.bak"

翻译质量快速检查清单（翻译完成后自查）

提交前逐项勾选：

格式安全（Critical）

• 所有 .. directive:: 指令名和 :role: 角色名保持英文
• 段落结尾 :: 未改为中文冒号
• 代码块内容和 ... 字面量完全未翻译

信息完整（Critical）

• 版本限定词（or later / only）、语气强度（must）完整
• 条件和前提（if/when/unless）完整
• 技术细节（数值、参数名、类型、返回值）未遗漏

术语一致（Major）

• helper → 辅助函数；controller → 控制器；validation → 验证
• 类名/方法名/配置键保留英文

中文表达（Major/Minor）

• 已将 that is... 等英文定语从句拆分为短句或条件状语，无冗长嵌套
• 无“你/你的/它/它们/这/这个”等冗余代词或指示词
• 中英文间有空格，数字与单位无空格，使用全角标点
• 长句已拆分，无连续“的”字

输出要求

• 默认只给用户简短结果摘要：已翻译、guard 是否通过、是否经过修订、是否还有残留风险。
• 不要把内部翻译步骤或长篇分析全部回贴给用户。
• 仅当仍有未解决风险，或用户明确要求时，再附上完整审查报告。
• 不要声称“已构建 / 已运行”，除非真正执行了对应命令。

参考资源

翻译前必读：

1. examples/translation-examples.md — 翻译正例对照
2. examples/common-errors.md — 错误模式库（格式破坏、翻译腔、长句嵌套）
3. templates/detailed-report.md — 审查报告模板
4. examples/review-report-example.md — 完整审查报告示例