管理多语言课程库，让译文始终跟上英文原文

## 只改课程、文章和译文，不碰应用代码 你维护的是一个纯内容型仓库：教学课程、文章及其译文。渲染这些内容的发布应用位于别处，不属于本仓库。你的工作对象是文字、结构和元数据，而不是应用程序代码。 需要遵守的范围边界： - 不要在这里添加应用源代码、构建工具或运行时配置。如果某项变更需要站点表现出不同的行为，请明确说明，并描述发布应用中需要配套进行的改动，而不是在这里临时凑合一个实现。 - 用于报告内容自身状况的小型维护脚本（例如翻译状态报告）是合理的，编辑之前应当先使用它们，而不是把它们替换掉。 - 把每一个文件都当作日后需要由人工译者遵循的对象。对你而言方便、却破坏翻译工作流的改动，就是糟糕的改动。 - 当某项请求没有说清楚针对的是源语言还是译文时，先询问再动笔。猜错会在无声无息中破坏后文所述的过期状态跟踪。 ## 各语言的文件夹结构保持一致，先改英文原文 内容库采用可预期的镜像式目录结构。课程文件位于 lessons 目录下，接着是以 ISO 语言代码命名的文件夹，然后是分类文件夹，最后才是文档本身。博客文章统一放在单个 posts 目录中，文件名以日期前缀开头，后接用连字符分隔的 slug，这样仅凭文件名就能看出时间顺序。 每种语言下的分类集合是固定的，且在所有语言中完全一致。常见分类包括基础、进阶、高级、存储、测试、数据处理、特定框架相关内容，以及一个杂项分类。不要只在某一种语言里新造分类；要么所有语言都加，要么都不加。 有一种语言（通常是英语）是唯一的事实来源。其他所有语言目录存放的都是它的译文。 由此衍生的规则： - 实质性改动先在源语言中完成，再传播到各译文。绝不要仅在译文中引入新的事实、示例或章节。 - 只有出于翻译质量方面的原因，才可以单独修改译文：误译、语法、排版格式或本地化惯例。 - 如果你发现译文中的某个错误在源文中同样存在，先修正源文，再把译文作为后续任务处理。 ## 按改动大小提升版本号，并复制到译文中 每篇文档开头都有一个结构化的元数据块，以一行分隔线结束。该块至少包含版本字符串、标题，以及用一两句话概括文档的简短摘要。文章类内容还额外包含作者姓名、作者链接、标签和发布日期。 版本字段不是装饰，它是供程序读取的。译文要原样照抄其所依据的源文档版本号。工具随后会把每篇译文的版本与源文当前版本进行比较，据此判定该译文是最新的、轻微过期的，还是严重过期的。 按改动幅度提升源文版本号： - 主版本：文档基本被重写。译者必须重做翻译。 - 次版本：增删了句子、段落或示例。译者必须复查并补丁式修订。 - 修订号：仅有拼写和排版方面的修正。译文仍可继续使用。 绝不要在没有做出相应改动的情况下提升版本号，也绝不要做了实质性改动却不提升版本号。这两种错误都会摧毁过期状态报告的准确性，而这份报告是让译文库保持诚实的唯一机制。 编辑译文时，只有在你确实已经让它与更新后的源文内容保持一致之后，才更新它的版本号。 ## 用“我们”的口吻，先举例再解释 除非某种语言的本地化指南另有规定，否则所有内容都应遵循以下惯例。 - 使用包含读者在内的第一人称复数。读者是与你并肩协作的伙伴，而不是被说教的学生。在"我们"读起来自然的地方，避免使用"你必须"这类表达。 - 先展示，后解释。可运行的示例排在解释之前；读者先看到事物本身，再读到关于它的说明。 - 段落要短。当信息变得密集时，把它改写成项目符号列表或示例块，而不是一大段长文字。 - 使用主动语态。在英文中一致地使用缩写形式，而不是展开的正式写法。 - 不使用表情符号。不写套话，不写祝贺式的填充内容，也不写仅仅为了引出下一句而存在的句子。 - 使用系列逗号。 - 标题层级：主要章节用二级标题，子章节用三级标题。绝不要在正文内容中使用一级标题，那个层级属于文档标题。 - 每个示例块都要声明其语言标识符，以便渲染器正确进行语法高亮。 删掉所有不具教学价值的内容。篇幅长度本身不是优点；一篇较短、译者能够忠实转译的文档，价值高于一篇较长却容易走样的文档。 ## 每篇课程按概述、示例、相关主题的顺序编排 教学类文档遵循固定的叙述结构： 1. 简要概述本文档涵盖的内容。 2. 动机——为什么这件事重要——最多用两三句话说明。要克制住扩写这一节的冲动；这里是最容易堆积填充内容的地方。 3. 核心内容，以具体示例驱动，每个示例之后紧跟解释。 4. 向外的关联：本主题与读者已经看过或接下来将会看到的相邻材料之间有何关系。 在核心内容内部，按从最简单可用的情形到较复杂的变体来编排材料，并且在依赖某个术语之前先介绍它。如果一篇文档扩张到涵盖两个明显可以分开的主题，就把它拆开，而不是任其蔓延——两篇聚焦的文档更易于翻译，而且各自独立地变得过期。 元数据块中的摘要应当仅凭概述一节就能写出来。如果你没办法用一两句话概括这篇文档，说明这篇文档承担的内容太多了。 ## 新增课程或语言，并说明网站端需要的注册 新增源文档：在源语言目录下正确的分类中创建文件，并配上完整的元数据块，其中包含初始版本号。然后明确说明发布应用中是否需要配套改动来登记这篇新文档以供展示。不要想当然地认为它会自动出现。 新增译文：把源文件复制到目标语言目录中相同的分类路径与文件名下，翻译正文，并翻译标题、摘要等供人阅读的元数据值。结构性的字段名和版本值保持原样不动——版本必须与源文完全一致。 新增语言：在新的语言代码下创建完整的分类目录集合，使其结构与其他所有语言互为镜像，添加最初的一批译文文档，并在发布应用中登记该语言。一个存在却未登记的语言文件夹，只会产生没人能访问到的内容。 在动笔翻译之前，如果该语言有对应的本地化风格说明，先读它。本地化说明涵盖术语选择、技术名词的音译、标点符号和敬语语体，在与通用行文规范冲突时以本地化说明为准。如果你被要求翻译的语言还没有本地化说明，请提议先创建一份，而不是悄悄自创一套惯例。 ## 用状态报告，先更新最过时的译文 译文漂移是多语言内容库默认会出现的失效模式。要有意识地加以管理。 开始任何一次翻译工作时，先对整个内容库运行状态报告，而不是手动浏览目录。把它过滤到你负责的语言以及真正重要的严重程度等级——完全缺失的文档和被标记为严重过期的文档排在最前，轻微漂移次之，修订级别的漂移排在最后，甚至可以不处理。 工作规则： - 不要把一篇文档翻译到一半，却让版本号与源文保持一致。一篇半成品译文却自报为最新状态，比明显缺失的译文更糟糕。 - 如果你必须中途停下，就把版本号保留为原先的值，好让报告继续标记这个文件。 - 不要用机器翻译直接交付，而不对照本地化说明进行审校。 - 如果你开始之后源文发生了变更，收尾之前重新核对差异；要以你最终实际记录的那个版本为准来完成工作。 - 结束时报告你让哪些文档变为最新、你有意跳过了哪些以及原因——下一位贡献者要据此进行分诊。