文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载当某个命令只是另一个命令的别名如vi是vim的别名时tldr 并不重复编写一套文档而是创建一种特殊的「别名页」将用户导向原命令。本文以 contributing-guides/translation-templates/alias-pages.md 为核心完整讲解别名页的结构规范、覆盖 40 种语言的官方翻译模板、如何在贡献中创建与同步别名页并结合仓库中的 set-alias-page.py 脚本源码剖析其自动化生成机制。阅读完本文你将能根据任一语言的模板亲手撰写并校验符合社区规范的别名页。什么是别名页在 tldr 仓库中绝大多数页面是对某个命令的完整速查文档包含描述、示例和「更多信息」链接。但存在一类特殊命令它们本身没有独立的功能只是另一个命令的别名。典型如vi之于vim、gsum之于 GNUsum。若为这类命令重复编写整套文档会造成维护负担和信息冗余。社区为此在 PR #5368 中讨论并确定了「别名页」模板别名页只做一件事——声明「本命令是 X 的别名」然后给出一条跳转到原命令文档的命令tldr X。仓库的 style-guide.md 中「Aliases」一节给出了别名页的定义依据If a command can be called with alternative names (likevimcan be called byvi), alias pages can be created to point the user to the original command name.可见别名页的存在目的是「引导用户找到原命令」它本身不承载示例、占位符或「更多信息」链接结构被刻意保持极简。英文模板结构拆解alias-pages.md 中每个语言小节都提供一段可直接套用的 Markdown 模板以英文为例# example This command is an alias of example. - View documentation for the original command: tldr example模板由四个要素构成标题行H1# example即别名命令本身的名称需与页面文件名一致文件名必须小写描述行Blockquote This command is an alias ofexample.声明别名关系反引号中的example指代原命令示例描述- View documentation for the original command:采用祈使语气这是 tldr 全仓库的统一写作要求示例命令tldr example指向原命令的文档。模板中的example只是占位符实际使用时会被替换为真实命令名。关键替换逻辑在 set-alias-page.py 的generate_alias_page_content()中实现template_command example result template_content.replace(template_command, page_content.title, 1) result result.replace(template_command, page_content.original_command, 1) result result.replace(template_command, page_content.documentation_command)三次替换分别对应标题第 1 个example、描述中反引号内的原命令第 2 个example、以及tldr命令行的目标其余example。各语言模板速查alias-pages.md 共收录 41 个语言小节的模板并提供了从#en到#zh_tw的锚点导航目录。这些模板由各语言维护者翻译与校对可直接复制使用。以下是核心语言模板对照语言描述行模板示例描述en This command is an alias of \example.|- View documentation for the original command:de Dieser Befehl ist ein Alias von \example.|- Zeige die Dokumentation für den originalen Befehl an:es Este comando es un alias de \example.|- Vea la documentación del comando original:fr Cette commande est un alias de \example.|- Affiche la documentation de la commande originale :ja このコマンドは \example のエイリアスです。|- オリジナルのコマンドのドキュメントを表示する:ko 이 명령은 \example의 별칭입니다.|- 자세한 내용은 원본 명령을 참고하세요:ru Эта команда — псевдоним для \example.|- Смотри документацию для оригинальной команды:zh 此命令为 \example 的别名。|- 查看原命令的文档zh_TW 此命令為 \example 的別名。|- 檢視原命令的文件其余语言ar、bg、bn、bs、ca、cs、da、el、fa、fi、hi、id、it、lo、ml、nb、ne、nl、no、pl、pt_BR、pt_PT、ro、si、sr、sv、ta、th、tr、uk、uz 等的描述行与示例描述均以各自母语给出完整文本请直接查阅原文档。值得注意的细节法文模板在冒号前保留了一个空格commande originale :这是遵循 style-guide 中「法语描述中特殊字符前后需有单一空格」的专项规则葡语pt_BR / pt_PT模板的动词使用了第三人称单数现在时例如Veja ...符合 style-guide 的葡萄牙语专项规则中文模板使用全角标点、。符合中文排版规范由于这些模板行会被 set-alias-page.py 的get_locale_alias_pattern()通过正则.*example 提取为「别名特征行」因此模板中描述行的写法必须严格保持反引号包裹原命令的形态。仓库中的真实别名页示例实际提交的别名页与模板一一对应。英文与中文对照示例pages/en/common/vi.mdvi.md# vi This command is an alias of vim. - View documentation for the original command: tldr vimpages.zh/common/vi.mdvi.md# vi 此命令为 vim 的别名。 - 查看原命令的文档 tldr vim再如 macOS 平台上的 GNU 工具别名页 gsum.md描述行会带上「GNU」以消除歧义# gsum This command is an alias of GNU sum. - View documentation for the original command: tldr sum可以看到即使描述行加入了限定词如 GNU其反引号结构依然与模板兼容自动化脚本仍能正确识别。仓库中已有大量此类页面pages.zh下匹配「的别名」的页面即达数十个如brew-abv、bun-i、bzcat、bye、c等均可作为翻译参考。用 set-alias-page.py 自动创建与同步别名页除了手工套用模板仓库提供了 set-alias-page.py 一键生成/同步别名页。脚本支持以下参数参数作用-p, --page PAGE以platform/alias_command.md格式指定别名页启动交互式向导创建/更新-S, --sync读取英文别名页并同步到各语言翻译若对应翻译页已存在-l, --language LANGUAGE限定语言格式为ll或ll_CC如fr、pt_BR-s, --stage将修改过的页面git add暂存需仓库为 Git 仓库-n, --dry-run只显示将要发生的改动不实际写入文件-i, --inexact忽略精确模板匹配识别非标准形式的别名页典型用法# 交互式创建新别名页以 osx/gsum 为例 python3 scripts/set-alias-page.py -p osx/gsum # 将英文别名页同步到全部语言翻译 python3 scripts/set-alias-page.py -S # 仅同步巴西葡萄牙语翻译 python3 scripts/set-alias-page.py -S -l pt_BR # 同步并暂存改动便于提交 PR python3 scripts/set-alias-page.py -Ss # 先预览将发生的变化不写文件 python3 scripts/set-alias-page.py -Sn脚本采用交互式提示而非位置参数目的是避免含短横线的命令名如pacman -S在参数解析时报错并在页面创建前完成输入校验。向导会依次询问页面标题、原命令必填不可为空、文档命令默认等于原命令预览将要生成的页面后再确认是否继续。底层实现原理从 set-alias-page.py 与 _common.py 的源码可以看到完整的自动同步链路模板加载get_templates()_common.py扫描contributing-guides/translation-templates/alias-pages.md按###语言小节切分提取每个markdown代码块作为该语言的模板文本语言识别get_locale()_common.py根据页面路径中pages.xx的目录名推断语言无语言后缀视为en别名页识别get_alias_command_in_page()set-alias-page.py读取页面校验其是否具备「描述行含别名特征 恰好一条tldr命令」的结构并从描述行反引号中提取原命令、从tldr X中提取文档命令内容生成generate_alias_page_content()按前述三次替换逻辑将模板中的example替换为真实命令名差异比对set_alias_page()set-alias-page.py通过剥离标题与命令文本的方式将现存页面与模板做「归一化比较」只有确实不一致时才覆盖写入避免无意义改动同步入口get_english_alias_pages()set-alias-page.py遍历pages目录下各平台目录找出所有英文别名页再由sync_alias_page_to_locale()逐个语言目录扩散。脚本还内置了若干单元测试如test_ignore_files、test_get_locale、test_get_status等可直接运行验证python3 scripts/set-alias-page.py # 无参数时打印帮助信息另外注意脚本将tldr.md与aria2.md加入IGNORE_FILES忽略清单set-alias-page.py避免误将这两个特殊页面识别为别名页。编写别名页的注意事项结合 alias-pages.md、style-guide.md 与脚本实现总结实践要点页面文件名必须小写且与标题一致——lintertldr-lint会自动校验描述行必须声明别名关系这是脚本识别别名页的关键特征行get_locale_alias_pattern()会提取 ...example 形态的行用于比对命令行固定为tldr 原命令反引号内是用户要查找的原命令名不要添加「更多信息」链接别名页的目的是跳转而非重复说明中文页面注意排版英文与数字两侧留一个空格、使用全角标点如模板所示「example的别名」翻译对齐英文结构若英文页面的描述行带有限定词如 GNU翻译时保持对应的反引号包裹结构确保同步脚本能正确提取原命令。结语别名页是 tldr 中「以最小成本维护大量命令入口」的设计一套极简模板、40 种语言翻译、配合set-alias-page.py的批量同步让vi、gsum、bzcat这类命令在一行说明之后即可引导用户直达完整文档。无论是手工照模板编写还是用脚本-S -l 你的语言批量同步掌握本文所述的模板结构与底层替换逻辑都能让你在贡献别名页时既快又准。如需进一步了解相邻概念可参阅 style-guide.md含别名、消歧义页、分组命令等页面类型规范以及本仓库的其他翻译模板如 common-arguments.md、see-also-mentions.md。赞分享文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载相关推荐tldr 项目 More information 链接多语言模板全解析从规范到自动化维护tldr 项目 More information 链接多语言模板全解析从规范到自动化维护 tldr 是一个协作式的控制台命令速查手册仓库每一条命令页面都在描文档教程知识库Postgres Pro JSONB 实战指南从操作符、索引到性能优化的完整实践Postgres Pro JSONB 实战指南从操作符、索引到性能优化的完整实践 本指南以 claude skills 仓库中 postgres pro ht文档教程知识库tldr-pages语义分析自然语言处理应用tldr pages语义分析自然语言处理应用 在命令行工具的世界里用户常常被冗长复杂的 man pages 手册页困扰。以 tar 命令为例传统手册页文档教程知识库上一篇静态网站托管方案Instatic与Netlify、Vercel的无缝集成下一篇sc/sc信号处理安全崩溃回溯与优雅退出的完整实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考