# Longtext Translate

> 任意长度文本翻译、审校或精编流程。PDF、EPUB 等本地材料会先规范化为 Markdown 文件，再开始翻译。当用户表现出翻译或审校精编现有译稿的意图时触发，例如提及“翻译”、“优化／审校／润色 / 精编译文”、“改成中文／英文”等。

- Skill: `zlhhhh8901/longtext-translate` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zlhhhh8901/longtext-translate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zlhhhh8901/longtext-translate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zlhhhh8901 (https://skillmd.com/u/zlhhhh8901)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zlhhhh8901/longtext-translate

---


# 文本翻译

本技能提供三条翻译路径，根据文本规模和用户需求自动判断或由用户指定：

1. **普通翻译**：主 agent 在单一上下文中完成翻译。适合短文本和论证紧密、不宜分片的文章。
2. **长文本翻译**：先分片，再建立共享上下文并委派 subagent 并行翻译各分片，最后合并。适合可稳定拆分的长文。
3. **译稿审校/精编**：对已有译文进行审校或精编处理。既可承接前两种路径，也可在用户直接提供原文与译稿时独立执行。

## 前置准备

### 第 1 步：规范化源内容

翻译流程只接受 Markdown 输入。用户提供的原始内容都需先规范化为本地 Markdown 文件。后续的翻译、审校、分片和合并均以该 Markdown 文件作为唯一输入源（源文件）。

| 输入类型 | 动作 |
|------------|--------|
| 文本或 Markdown 文件 | 直接使用 |
| 内联文本 | 保存为 `translate/{slug}.md` |
| PDF/图片/Word 文档 | 按 `references/ingest/mineru.md` 处理 |
| EPUB 文件 | 按 `references/ingest/epub.md` 处理 |
| URL | 使用当前环境允许的网页访问能力抓取正文并整理；若无自然文件名，保存为 `translate/{slug}.md` |
| 只翻译部分内容 | 抽取指定章节、页码或标题范围 |

`{slug}` 根据内容主题生成 2–4 个词并采用 `kebab-case`。

PDF、图片、Word、EPUB 文档或 URL 输入经规范化后，向用户汇报提取结果和文件路径，并附上建议：“若内容无误，建议执行 `/clear` 或其他等效命令清空上下文，再从该 Markdown 文件重新进入翻译流程——干净的上下文能达到更好的翻译效果。” 汇报完成后即停止，等待用户确认，不进入第 2 步。

Markdown 或纯文本输入规范化后可直接进入第 2 步。

### 第 2 步：制定并确认翻译方案

**① 整理翻译偏好**

- **目标语言**：默认简体中文，用户可自行指定。
- **目标读者**：默认为希望准确、无障碍理解原文内容的读者，用户可自行指定。
- **用户术语约束**：用户显式提供的术语要求，例如术语表文件、命令中直接写出的术语映射、保留原文或指定译法等。非必须项；若有则完整收集并全程应用。若该约束是条目庞大的术语表文件（数百条以上），不要全量读入上下文，改按 `references/terminology.md` 的方式按需筛选出源文实际出现的子集再应用。

**② 决定翻译策略**

1. 选择任务类型
   - 用户提供原文与译稿并要求审校/精编：直接进入对应流程。
   - 其他情况：进入翻译流程。
2. 选择翻译方式
   - 用户已指定普通翻译或长文本翻译：直接采用。
   - 未指定：读取 `references/metadata.json`。若能识别当前模型且匹配到对应条目，使用该条目的 `chunkThreshold` 阈值；否则使用 `fallback`。估算待译文本词数。低于阈值采用普通翻译，高于阈值采用长文本翻译。

**③ 准备输出目录**

明确策略后，在源文件同级目录下创建输出目录，路径格式为 `{source-dir}/{source-basename}-{target-lang}/`。

示例：

- `posts/article.md` → `posts/article-zh/`
- `translate/ai-future.md` → `translate/ai-future-zh/`

复用现有输出目录时，至少确认以下条件一致：源文件相同、目标语言相同、当前任务属于同一轮翻译、同一轮审校或同一轮精编。满足这些条件时，直接沿用原有目录及其中间文件；否则路径改为 `{source-dir}/{source-basename}-{target-lang}-MMDD-HHmm/`，`MMDD-HHmm` 替换为当前日期和时间。

创建或复用输出目录后，检查源文件同级是否存在 `{source-basename}_images/` 目录。若存在且输出目录内尚无同名目录，则将其复制进去（`cp -r {source-dir}/{source-basename}_images/ {output-dir}/`），确保译文中的相对图片路径能正常解析。若输出目录内已有该目录则跳过。

**④ 生成分片预览（仅限长文本翻译模式）**

如采用长文本翻译模式，先执行以下命令：

```bash
python3 {baseDir}/scripts/chunk.py preview <file> [--max-words <chunk_max_words>] --output-dir <output-dir>
```

其中，`{baseDir}` 为本 `SKILL.md` 所在目录，`<chunk_max_words>` 使用前述阈值中的 `chunkThreshold`。依赖 `markdown-it-py>=4.0,<5`。

此命令将生成 `chunk-preview.html`，并自动启动本地预览服务，但不会立即创建 `chunks/` 文件夹。用户可通过命令返回的 `preview_url` 查看分片预览页面，按需调整分片边界。若用户在页面中确认方案，脚本会保存 `chunk-plan.json`；后续命令优先采用该方案。

**⑤ 声明翻译计划并等待确认**

正式执行前，向用户一次性说明：

- 当前任务入口：从原文生成译稿，或审校/精编已有译稿
- 翻译路径：普通翻译或长文本翻译，以及判断依据
- 目标语言、目标读者、用户术语约束、输出目录
- 长文本模式下的分片预览入口 `preview_url`

用户确认后开始正式执行。

## 翻译执行

### 第 1 步：理解内容并确定译法

基于确认后的策略、目标读者和术语约束，分析源材料并确定译法：

- **内容**：核心论点、作者背景或立场、写作语境、原文目的与预期受众。
- **术语**：识别需要全局统一的核心术语，与用户术语约束交叉核对，确定一致译法；对于未覆盖的专业术语，使用行业公认的标准译法。
- **语域锚定**：判断原文的正式度、口语度、情感强度和体裁风格，确定译文应保持的语域。
- **翻译难点**：识别隐喻、习语、双关、文字游戏、长难句等需要创造性处理的结构。

普通翻译模式下，分析只作为内部执行依据，无需生成中间文件或向用户输出。

长文本翻译模式下，将分析结果保存为两份共享文件：

1. `glossary.md`：提取术语维度的判断结果，列出每条术语的原文、推荐译法和简要理由。用户提供的术语约束也合并进，冲突时以用户约束为准。
2. `prompt.md`：按 `references/prompt-template.md` 的结构组装。内容、语域锚定和翻译难点三个维度的分析结果分别填入模板的对应槽位，同时写入目标语言、目标读者和翻译原则。

### 第 2 步：翻译正文

翻译时遵守以下原则：

- **重写，而不只是翻译**：在不改变原意的前提下，按目标语言习惯重组句式、信息顺序和段落节奏，就像母语写作者从零开始创作。
- **忠实原文**：完整保留原文事实、数据、观点、逻辑关系和论证结构。
- **语气与语域匹配**：等价再现原文的口语化程度、情感强度、讽刺、幽默和体裁风格。
- **保留 Markdown 结构**：标题、粗体、链接、图片、代码块、脚注等结构性标记须原样保留。
- **术语一致**：遵守用户提供的术语约束。未覆盖的专业术语使用行业公认的标准译法。专业术语/人名/书名首次出现时，在译文后用括号标注原文。
- **报告低争议修正**：原文存在拼写错误、明显 OCR 错字等低争议错误时，可在译文中直接修正，但译后必须向用户汇报。

#### 长文本翻译模式的执行流程

普通翻译模式直接由主 agent 按上述原则翻译并保存为 `translation.md`。长文本翻译模式需按如下步骤执行：

1. **执行命令将分片落地**：`python3 {baseDir}/scripts/chunk.py materialize <file> [--max-words <chunk_max_words>] --output-dir <output-dir>`
   - 脚本会优先读取 `chunk-plan.json`，否则采用默认分片方案。
   - 返回 JSON 中的 `chunk_index` 提供每个 chunk 的编号、词数和起始标题路径。
2. **委派 subagent 翻译**：为每个分块启动一个 subagent，按 `references/prompt-template.md` 的启动提示组织任务。每个 subagent 读取 `prompt.md` 获取共享上下文，接收分块位置信息，翻译自己的分块并保存为 `chunks/chunk-NN-draft.md`。
3. **合并**：所有 subagent 完成后，按顺序合并已翻译分块。若存在 `chunks/frontmatter.md` 则置于开头。保存为 `translation.md`。所有源分块与已翻译分块均保留在 `chunks/` 中。

### 第 3 步：质量门禁

回源抽查 `translation.md`，检查以下维度，发现问题直接修正：

- **准确性**：事实、数据、观点、逻辑关系和作者立场无偏移
- **完整性**：无漏译、增译、跳段或重复
- **语气**：情感强度和语域与原文匹配，口语、讽刺和幽默未被中性书面语抹平
- **术语**：用户指定术语正确应用，核心术语全文一致，专业术语首次出现标注原文
- **格式**：Markdown 结构完整可用，长文是否已按译法判断启用关键句加粗或小标题
- **可读性**：无病句和明显翻译腔，指代清楚，句长和信息密度符合目标语言习惯

### 第 4 步：增强路由与完成汇报

如果用户在最初的需求中已明确提出需要审校或精编，则直接进入对应流程。审校详见 `references/review.md`，精编详见 `references/polish.md`，双语版详见 `references/bilingual.md`。

如用户未提前说明，则：

1. 向用户简明汇报当前进度——译文的保存路径，以及是否修正了原文中的低争议问题。
2. 询问用户是否需要继续执行以下操作，列出带数字序号的选项，用户输入数字即是选择：
   1. 审校：逐段对照原文核查译文，形成结构化诊断报告并修订问题；修正完成后通读顺平译文，确保行文流畅自然。
   2. 精编：将译文作为独立的目标语言文章做最终打磨，提升阅读体验。可按需显化重点与结构、补充背景解释、统一中文排版与格式。
   3. 审校 + 精编：先审校修正问题，再精编提升阅读体验。
   4. 双语版：将原文与译文按段落交替排列，产出便于对照阅读的双语文件。

**注意**：无论双语版是用户预先指定还是通过选项选中，它始终在所有质量相关步骤（翻译、可选审校、可选精编）完成后才执行——它是格式化步骤，不介入翻译质量环节。

各流程结束后同样需要汇报完成情况，内容至少包括：产出的文件路径。

## 附录：参考文件

| 文件 | 适用场景 | 何时读取 |
|------|----------|----------|
| `references/metadata.json` | 翻译策略判断 | 决定翻译路径前，获取当前模型的 `chunkThreshold` 阈值 |
| `references/terminology.md` | 大型术语表 | 用户提供条目庞大的术语表文件时，按需筛选出源文实际出现的子集 |
| `references/prompt-template.md` | 长文本翻译 | 定义 `prompt.md` 与 subagent 启动提示的模板 |
| `references/review.md` | 审校 | 审校流程执行细节 |
| `references/polish.md` | 译文精编 | 精编流程执行细节 |
| `references/ingest/mineru.md` | PDF/图片/Word 文档输入 | 源材料为文档文件时，按流程规范化为 Markdown |
| `references/ingest/epub.md` | EPUB 输入 | 源材料为 EPUB 时，按流程规范化为 Markdown |
| `references/bilingual.md` | 双语版输出 | 产出原文与译文交替排列的双语版本的操作指南 |

## 附录：输出文件参考

| 文件 | 出现场景 | 说明 |
|------|----------|------|
| `translation.md` | 所有模式 | 最终译文 |
| `chunk-preview.html` | 长文本 | 分片预览页面；用户应通过 `preview_url` 打开 |
| `chunk-plan.json` | 长文本 | 用户在预览页面调整过分片并确认时才会生成；若未生成则按默认分片执行 |
| `glossary.md` | 长文本 | 供 subagent 共用的术语表 |
| `prompt.md` | 长文本 | 面向 subagent 的共享翻译提示 |
| `chunks/` | 长文本 | 分片目录。包含源分片 `chunk-NN.md`、译文分片 `chunk-NN-draft.md`，以及可能存在的 `frontmatter.md` |
| `draft.md` | 审校/精编 | 增强流程开始前的译稿快照 |
| `critique.md` | 审校 | 结构化、可证伪的独立审校报告 |
| `polish-preview.html` | 精编 | 中文排版与格式修正的预览页面；用户应通过 `preview_url` 打开 |
| `mapping.json` | 双语版 | 源文与译文的块级对齐映射，由 agent 分析两份 dump 输出后生成 |
| `bilingual.md` | 双语版 | 原文与译文按段落交替排列的双语输出文件 |