在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

tldr-pages/tldr

菜单

本地化系统

相关源文件

本文档记录了 tldr-pages 项目的翻译和本地化基础设施。它解释了多语言内容是如何组织的，翻译是如何管理的，以及用于维护跨语言版本质量的工具和流程。有关适用于所有页面的风格指南信息，请参阅页面风格指南。

概述

tldr-pages 项目维护多语言的命令行文档，以使命令行知识能够触及全球用户。本地化系统在保持一致结构和确保翻译与英文源页面保持同步的同时，实现了简化命令行文档的翻译。

来源: CLIENT-SPECIFICATION.md105-119 CONTRIBUTING.md55-64 README.md113-117

目录结构

tldr-pages 仓库通过结构化的目录层次，按语言和平台组织页面

每个翻译目录都遵循 pages.<locale> 的命名约定，其中 <locale> 是 POSIX 区域设置名称

  • <language> 是最短的 ISO 639 语言代码（例如，法语的 fr）
  • <country> 是可选的，使用两字母 ISO 3166-1 国家代码（例如，巴西葡萄牙语的 pages.pt_BR）

仅当区域方言存在显著差异时才包含国家代码。例如，巴西葡萄牙语（pt_BR）和欧洲葡萄牙语（pt_PT）有单独的目录，而法国和比利时的法语则共享 pages.fr 目录。

在每个语言目录内部，与英文页面保持相同的平台结构：common, linux, windows 等。

来源: CLIENT-SPECIFICATION.md105-119 CONTRIBUTING.md55-65

翻译流程

翻译流程遵循以下步骤

重要的翻译要求

  1. 翻译必须基于页面的英文原版
  2. 如果英文页面不存在，应首先创建
  3. 翻译者必须遵循特定语言的格式规则
  4. 每项翻译都应保持原页面的结构

贡献翻译的步骤

  • 在相应的语言目录中以与英文页面相同的名称创建文件
  • 保持相同的命令示例（带有翻译的描述）
  • 遵循通用风格指南和特定语言的规则

来源: CONTRIBUTING.md172-184 contributing-guides/style-guide.md508-564

特定语言指南

每种语言可能有特定的格式和风格规则。这些规则记录在风格指南中，以确保跨翻译的一致性。

语言特定规则示例

语言关键格式规则
中文（zh, zh_TW）- 中文字符与拉丁字母/数字之间添加空格
- 使用全角标点符号
- 当句子以拉丁字符结尾时，使用半角标点符号
印度尼西亚语（id）- 避免使用带前缀“ber-”和“me-”的动词形式
- 对技术术语使用特定的推荐形式
法语 (fr)- 使用第三人称单数现在时态
- 在某些标点符号前添加空格
葡萄牙语（pt_BR, pt_PT）- 描述以第三人称单数现在时动词开头

翻译者还应维护占位符语法（{{ 和 }} 之间的文本）并遵循风格指南中的通用格式规则。

来源: contributing-guides/style-guide.md508-564

翻译模板

项目提供标准化翻译模板用于常见元素，以确保一致性

  1. 别名页面：用于其他命令别名的页面模板

    This command is an alias of `original-command`.

  2. 通用参数：常用占位符的翻译，如 path/to/file 或 username

  3. 子命令提及：用于引用子命令的标准措辞

    Some subcommands such as `example command` have their own usage documentation.

这些模板提供多种语言版本，以保持翻译的一致性。

来源: contributing-guides/translation-templates/alias-pages.md contributing-guides/translation-templates/common-arguments.md contributing-guides/translation-templates/subcommand-mention.md

翻译工具

几个脚本有助于翻译管理和质量保证

关键翻译工具

  1. set-more-info-link.py：更新所有翻译的“更多信息”链接

    • 可以同步英文页面及其翻译之间的链接
    • 支持链接行的特定语言格式规则

  2. set-alias-page.py：帮助创建和维护多语言别名页面

    • 使用模板生成格式正确的别名页面
    • 可以跨翻译同步别名页面

  3. check-pr.sh：CI 管道的一部分，用于检查翻译

    • 检测过时的翻译
    • 识别缺失的英文页面
    • 报告需要解决的问题

来源: scripts/set-more-info-link.py scripts/set-alias-page.py scripts/check-pr.sh109-128

翻译管理

每种语言都有指定的维护者负责审查和维护翻译

.github/CODEOWNERS 文件将语言特定目录的所有权分配给特定的维护者，确保翻译的 PR 能够自动路由给相应的审阅者。例如：

/pages.ar/ @MachiavelliII
/pages.de/ @pixelcmtd @gutjuri
/pages.es/ @kant @tricantivu @ikks

MAINTAINERS.md 文件列出了所有维护者及其职责，包括特定语言的维护者。

来源: .github/CODEOWNERS1-45 MAINTAINERS.md

质量保证

项目通过自动化检查和人工审查来维护翻译质量

当发生以下情况时，翻译被视为过时：

  • 命令数量与英文原版不符
  • 命令内容与英文原版存在显著差异

CI 工作流程会自动检查翻译的以下方面：

  1. 缺失的英文源页面
  2. 与英文页面相比过时的内容
  3. 是否符合风格指南的格式
  4. “更多信息”链接的一致性

位于 https://lukwebsforge.github.io/tldri18n/ 的网站提供了一个动态更新的表格，显示所有翻译的状态，方便识别需要翻译或更新的页面。

来源: scripts/check-pr.sh109-128 CONTRIBUTING.md184-185 .github/workflows/ci.yml

翻译贡献步骤

对于希望添加或更新翻译的贡献者

  1. 首先检查英文页面是否存在
  2. 在相应的语言目录中创建/更新翻译
  3. 遵循特定语言的格式规则
  4. 使用翻译模板处理常见元素
  5. 提交 PR 以供语言维护者审查
  6. 解决 CI 检查或审阅者发现的任何问题

贡献流程遵循项目其他贡献相同的流程，并特别关注特定语言的要求。

来源: CONTRIBUTING.md172-197

结论

tldr-pages 的本地化系统使得文档能够以多种语言提供，同时保持质量和一致性。通过结构化的目录、特定语言的指南、自动化工具和专门的维护者，该项目确保命令行知识能够以用户喜欢的语言触达全球用户。