From 30c23ddfdf7b59d92a83b42ae83f257f0381d5ab Mon Sep 17 00:00:00 2001 From: Ein Verne Date: Thu, 9 May 2024 04:13:33 +0900 Subject: [PATCH] style-guide.zh: translate more guide line from English (#12659) --- contributing-guides/style-guide.zh.md | 329 +++++++++++++++++++++++--- 1 file changed, 296 insertions(+), 33 deletions(-) diff --git a/contributing-guides/style-guide.zh.md b/contributing-guides/style-guide.zh.md index 5273b0c87..39d801a43 100644 --- a/contributing-guides/style-guide.zh.md +++ b/contributing-guides/style-guide.zh.md @@ -6,22 +6,22 @@ ## 排版 -首先，你的页面应该看起来像这样： +首先，你的页面应该看起来像这样，并且最多只能包含 8 个示例： ```md # 命令名称 -> 短小精悍的描述。 +> 简短、精炼的描述。 > 描述最好只有一行；当然，如果需要，也可以是两行。 > 更多信息：. - 命令描述： -`命令 -选项1 -选项2 -参数1 {{参数的值}}` +`命令 -选项 1 -选项 2 -参数 1 {{参数的值}}` - 命令描述： -`命令 -选项1 -选项2` +`命令 -选项 1 -选项 2` ``` 当你将自己的贡献提交 pull request 时，一个脚本会自动检查你的贡献是否符合上面的格式。 @@ -38,43 +38,306 @@ tldr-lint {{page.md}} 如果你用 tldr-pages 的 Node.js 客户端，你可以在命令后加 `-f` (`--render`) 来在本地预览自己的页面： ```sh -tldr --render {{page.md}} +tldr --render path/to/tldr_page.md ``` -## 占位符（token）语法 +### PowerShell 特定规则 +在记录 PowerShell 命令时，请注意以下命名约定。 -当命令涉及用户自己提供的值时，请用 `{{token}}` 语法来使 `tldr` 客户端自动高亮它们： +- 文件名必须以小写形式书写，例如 `invoke-webrequest.md` 而不是 `Invoke-WebRequest.md`。 +- 页面标题/标题必须按照原样书写（与 Microsoft 或 PowerShell 模块作者意图一致），例如 `Invoke-WebRequest` 而不是 `invoke-webrequest`。 +- 示例中的命令名称和选项也应按原样书写，例如 `Command-Name {{input}} -CommandParameter {{value}}` 而不是 `command-name {{input}} -commandparameter {{value}}`。 -`tar -cf {{目标.tar}} {{文件1}} {{文件2}} {{文件3}}` +由于[各种兼容性差异](https://learn.microsoft.com/powershell/scripting/whats-new/differences-from-windows-powershell)和在 PowerShell 6.x 中删除的特定于 Windows 的命令，确保命令在 PowerShell 5.1（即安装在 Windows 10 和 11 中的“传统 Windows PowerShell”）和 最新版本的跨平台 PowerShell（以前称为 PowerShell Core）之间可用。如果命令或其选项在每个版本之间不可用或包含不同的行为，请在描述中注明。例如， + +```md +# Clear-RecycleBin + +> 清空回收站中的项目。 +> 此命令仅适用于 PowerShell 版本 5.1 及以下版本，或 7.1 及以上版本。 +> 更多信息： . +``` + +## 别名 +如果一个命令可以通过其他名称调用（例如 `vim` 可以通过 `vi` 调用），可以创建别名页面将用户引导到原始命令名称。 + +```md +# command_name + +> 此命令是 `original-command-name` 的别名。 +> 更多信息： . + +- 查看原始命令的文档： + +`tldr original_command_name` +``` + +示例： + +```md +# vi + +> 这是 `vim` 命令的一个别名。 + +- 原命令的文档在： + +`tldr vim` +``` + +预先翻译好的别名模板见[这里](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md)。 + +### PowerShell 特定别名 +某些 PowerShell 命令可能会引入别名，这些别名可以分为以下三类： + +1. 替代现有的 Windows 命令提示符 (`cmd`) 命令，例如 `cd` 别名为 `Set-Location`，但带有不同的命令选项。在这种情况下，将以下别名注释添加到原始命令提示符命令的 tldr 描述的第二行中，例如： + +```md +# cd + +> 显示当前工作目录或移动到其他目录。 +> 在 PowerShell 中，此命令是 `Set-Location` 的别名。本文档基于命令提示符 (`cmd`) 版本的 `cd`。 +> 更多信息： . + +- 原命令的文档在： + +`tldr set-location` +``` + +> [!TIP] +> “查看等效 PowerShell 命令的文档”的示例是可选的，如果页面已经具有 8 条示例，则可以省略。 + +2. 提供一个新的别名，但只能在 PowerShell 中执行，例如 `ni` 代表 `New-Item`。在这种情况下，使用[标准别名模板](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md)，但添加说明“在 PowerShell 中”，或表示该命令仅限于 PowerShell。例如， + +```md +# ni + +> 在 PowerShell 中，此命令是 `New-Item` 的别名。 +> 更多信息： . + +- 查看原始命令的文档： + +`tldr new-item` +``` + +3. 与其他程序冲突时 PowerShell 会提供一个新的别名，最为突出的是将 `curl` 和 `wget` 作为 `Invoke-WebRequest` 的别名（带有不兼容的命令选项集）。请注意，此类别的 PowerShell 系统别名通常仅限于 Windows。 + +在这种情况下，提供一个说明，并提供一种方法来确定命令当前是否引用了 PowerShell 命令（通过别名）或其他程序。例如， + +```md +# curl + +> 在 PowerShell 中，当原始的 `curl` 程序 () 未正确安装时，此命令可能是 `Invoke-WebRequest` 的别名。 +> 更多信息： . + +- 通过打印其版本号来检查 `curl` 是否已正确安装。如果此命令导致错误，则 PowerShell 可能已将此命令替换为 `Invoke-WebRequest`： + +`curl --version` + +- 查看原始 `curl` 命令的文档： + +`tldr curl -p common` + +- 查看 PowerShell 的 `Invoke-WebRequest` 命令的文档： + +`tldr invoke-webrequest` +``` + +## 选项语法 + +- 对于常用命令（例如 `grep`、`tar` 等），我们更推荐在占位符中使用简短选项以及[助记符](#short-option-mnemonics)。 +- 对于在命令中同时突出长选项和短选项（而不是使用助记符），将它们组合在占位符中，即 `{{-o|--output}}`。 +- 为了用户友好，在 `common` 目录下的页面中，当它们在跨平台（在多个平台上都可以正常工作）时，我们更推荐使用**GNU 风格的长选项**（例如 `--help` 而不是 `-h`)。 +- 在记录 PowerShell 命令时，使用**PowerShell 风格的长选项**（例如 `-Help` 而不是 `-H`）。 +- 我们更推荐使用空格而不是等号 (`=`) 来分隔选项和其参数（即使用 `--opt arg` 而不是 `--opt=arg`），除非程序不支持此方法。 + +### 短选项助记符 + +短选项助记符是可选的提示，可以添加以帮助用户理解这些短选项的含义。分配的助记符应与命令的官方文档（例如来自 `man` 或 `Get-Help`）中的内容相匹配。例如： + +```md +- [d]isplay the ins[t]allation [i]D for the current device. Useful for offline license activation: + +`slmgr.vbs /dti` + +Display the current license's e[xp]i[r]ation date and time: + +`slmgr.vbs /xpr` +``` + +请注意，在第一个示例中，`[d]`、`[t]` 和 `[i]` 字符被方括号括起来，以指示命令的 `/dti` 选项分别是 "display"、"installation" 和 "ID" 的组合。连续的助记符字符可以在同一方括号下进行分组，例如 `e[xp]i[r]ation` 而不是 `e[x][p]i[r]ation`。 + +**助记符字符必须以区分大小写的方式编写**，即使它放在句子的第一个字符位置（例如使用 `[d]isplay` 而不是 `[D]isplay`）。这是为了避免与 GNU 风格命令选项产生冲突，GNU 风格命令选项可能会以不同于小写的方式解释大写选项，例如 `-v` 用于显示命令的 `[v]ersion` 号码，而 `-V` 则用于以 `[V]erbose` 模式运行命令。 + +选项助记符也可以在翻译中使用，只要突出显示的单词与命令所用语言（通常为英语）中的单词具有相似的含义即可。例如，英语中的 `[d]ownload` 可以翻译为西班牙语中的 `[d]escargar`，英语中的 `[i]nstall` 可以翻译为德语中的 `[i]nstallieren`，而英语中的 `[a]pp` 可以翻译为印尼语和马来语中的 `[a]plikasi`。 + +可选地，在翻译和特定页面中，助记符及其包含的术语可以用括号与描述的其余部分分开（即 `([a]ll)`），以提供额外的上下文或提及描述中不存在的单词。 + +> [!NOTE] +> 在翻译的单词中如果缺少字符，您可以在等效词的前面或旁边突出显示选项，或您可以在括号内的翻译旁边添加英文单词。例如，英语中的 `E[x]tract` 可以翻译为印尼语中的 `[x] ekstrak` 或 `ekstrak [x]` 或 `ekstrak (E[x]tract)`。 + +## 占位符语法 + +当命令涉及用户自己提供的值时，请用 `{{token}}` 语法来使 `tldr` 客户端能自动高亮它们： + +`tar -cf {{目标.tar}} {{文件 1}} {{文件 2}} {{文件 3}}` 翻译时，请尽量翻译原文中的西文占位符。下面是命名占位符的规则： -1. 占位符需要短小精悍， +1. 占位符需要短小精悍， 例如 `{{源文件}}` 或者 `{{钱包.txt}}` 2. 如果占位符是西文，请用 [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) 来分词。 -3. 当占位符涉及文件路径时，请用 `{{目录/子目录/<占位符>}}` 的格式。 - 例如：`ln -s {{目录/子目录/源文件}} {{目录/子目录/链接}}` +3. 当占位符涉及文件路径时，请用 `{{目录/子目录/《占位符》}}` 的格式。 + 例如：`ln -s {{目录/子目录/源文件}} {{目录/子目录/链接}}` 如果占位符提到的文件也可能是目录，请用 `{{目录/子目录/文件或目录}}` -4. 除非文件是特定的，上述 `{{目录/子目录/<占位符>}}` 的文件路径格式应用于所有包含路径的命令。 -5. 如果命令需要的文件扩展名是固定的，请在占位符里加上文件格式。 - 例如：`unrar x {{压缩包.rar}}` - 如果文件 **必须** 有一个扩展名，请用 `{{.ext}}` 。 - 例如，在 `find {{起始目录}} -name '{{*.ext}}'` 的例子里， - 这样做简单地演示了查找一个特定文件扩展名的方法。 +4. 除非文件是特定的，上述 `{{目录/子目录/《占位符》}}` 的文件路径格式应用于所有包含路径的命令。 +5. 如果命令需要的文件扩展名是固定的，请在占位符里加上文件格式。 + 例如：`unrar x {{压缩包.rar}}` + 如果文件 **必须** 有一个扩展名，请用 `{{.ext}}` 。 + 例如，在 `find {{起始目录}} -name '{{*.ext}}'` 的例子里， + 这样做简单地演示了查找一个特定文件扩展名的方法。 但是，在 `wc -l {{file}}` 的例子里，用不加扩展名的 `{{file}}` 就足够了。 -6. 如果用实际的值比描述这个占位符更加明了，请举一个值做例子。 +6. 如果用实际的值比描述这个占位符更加明了，请举一个值做例子。 例如：`iostat {{2}}` 比 `iostat {{以秒为单位的间隔}}` 更清晰。 -7. 如果一个命令可能对文件系统或设备造成不可逆的影响，请在示例命令中注意改写，使其不能被盲目复制粘贴运行。 - 例如，`ddrescue --force --no-scrape /dev/sda /dev/sdb` 被盲目复制粘贴时可能对系统造成毁灭性的打击；`ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` 则更安全。 +7. 如果一个命令可能对文件系统或设备造成不可逆的影响，请在示例命令中注意改写，使其不能被盲目复制粘贴运行。 + 例如，`ddrescue --force --no-scrape /dev/sda /dev/sdb` 被盲目复制粘贴时可能对系统造成毁灭性的打击；`ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` 则更安全。 因此，请用 `{{/dev/sdXY}}` 而不是 `{{/dev/sda1}}` 来表示一个 **块设备** 。 占位符应该尽可能简单明了，让人一眼就能看出应该替换它的值。 +### 路径 + +- 当只期望文件名时，请使用 `{{filename}}`。 +- 对于文件或目录路径的任何引用，请使用格式 `{{path/to/}}`，除非位置是隐含的。 +- 当路径不能是相对路径，而必须从文件系统的根目录开始时，请使用斜杠作为前缀，例如 `get {{/path/to/remote_file}}`。 +- 如果可能引用文件或目录，请使用 `{{path/to/file_or_directory}}`。 + +> [!NOTE] +> 如果命令专用于 Windows，请使用反斜杠（`\`），例如 `{{path\to\file_or_directory}}`。驱动器号（如 `C:`）是可选的，除非命令输入要求绝对路径或特定的驱动器号范围，例如 `cd /d {{C}}:{{path\to\directory}}`。 + +### 扩展名 + +- 如果文件有特定的扩展名，请写出来。 + 例如，`unrar x {{path/to/compressed.rar}}`。 +- 如果需要通用的扩展名，请使用 `{{.ext}}`，但**只有**在需要扩展名时才使用。 + 例如，在 `find.md` 的示例“按扩展名查找文件”中（`find {{path/to/root}} -name '{{*.ext}}'`）， + 使用 `{{*.ext}}` 可以解释命令而不必过于具体； + 而在 `wc -l {{path/to/file}}` 中，使用 `{{path/to/file}}`（不带扩展名）就足够了。 + +### 分组占位符 + +- 如果命令可以接受相同类型的 0 个或多个参数，请使用省略号：`{{placeholder1 placeholder2 ...}}`。 + 例如，期望多个路径，则可以使用 `{{path/to/directory1 path/to/directory2 ...}}`。 +- 如果命令可以接受不同类型的 0 个或多个参数，请使用竖线和省略号：`{{placeholder1|placeholder2|...}}`。 + 如果可能值超过 5 个，则可以在最后一项后面使用 `|...`。 +- 无法通过省略号限制占位符的最小或最大数量。 + +### 特殊情况 + +- 如果一个命令可能对文件系统或设备进行不可逆转的更改， + 请以一种不会被轻易复制粘贴的方式编写每个示例。 + 例如，不要写成 `ddrescue --force --no-scrape /dev/sda /dev/sdb`， + 而是写成 `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}`， + 并且对于*块设备*，使用 `{{/dev/sdXY}}` 占位符，而不是 `/dev/sda1`。 + +通常情况下，占位符应尽可能直观，以便于理解如何使用命令并填入相应的值。 + 在命令描述中，如果出现了技术性的专有名词，请用 `反引号` 括起来： -1. 路径，例如 `package.json`，`/etc/package.json`. -2. 扩展名，例如 `.dll`. -3. 命令，例如 `ls`. +- 路径，例如 `package.json`，`/etc/package.json`。 +- 扩展名，例如 `.dll`。 +- 命令，例如 `ls`。 +- 标准流：`stdout`，`stdin`，`stderr`。**不要**使用完整的名称（例如标准输出）。 +- 压缩算法，例如 `zip`，`7z`，`xz`。 + +## 描述 + +### 祈使句 + +- **所有描述必须以祈使句表达。** + +如果你担心命令在不同平台或操作系统之间可能不同（例如 Windows 对比 macOS），大多数 [tldr 页面客户端](https://github.com/tldr-pages/tldr/wiki/tldr-pages-clients) 将选择最适合的命令版本。 + +在这种情况下，默认将显示 Windows 版本的 `cd` 信息（存储在 `pages/windows/cd.md` 中）给 Windows 用户，并为 Linux、macOS 和其他平台显示一个通用版本（存储在 `pages/common/cd.md` 中）。 + +在为命令示例编写描述时，**检查任何语法错误**。例如，应该使用 `前往指定目录` 而不是： + +- `正前往指定目录`（不应使用现在分词形式） +- `该命令将前往指定目录`（很明显此示例适用于 *此* 命令） +- `让我们前往指定目录！` +- `目录被更改为`（如果可能，应使用主动形式而不是被动形式） + +例如，可以使用 `列出所有文件：` 的描述，下面是示例的描述可以使用 `列出所有文件：`。 + +```md +- 列出所有文件： + +`ls` +``` + +### 措辞 + +- 所有描述**必须简洁**。 +- 避免在描述中使用页面标题（例如，使用 `为数字艺术家设计的素描和绘画程序`，而不是 `Krita 是为数字艺术家设计的素描和绘画程序`），除非程序名称与可执行文件名称不同（例如 `rg` 和 Ripgrep）。 +- 避免提及程序是在命令行上使用的（例如，使用 `Ripgrep 是一个递归的面向行的搜索工具`，而不是 `Ripgrep 是一个递归的面向行的 CLI 搜索工具`）。 +- 例如，在为 `cd` 编写文档时，一个用于在终端或命令提示符中更改当前工作目录的工具，**不要**写出像这样冗长的描述： + +```md +> `cd` 是一个系统工具，在 Windows、macOS 和 Linux 中可用，用于在命令提示符、终端和 PowerShell 中更改当前工作目录以完成任务。 +``` + +它应该简化以使每个人都能更轻松地阅读： + +```md +> 更改当前工作目录。 +``` + +### 格式 + +- 在描述中，应该对专有名词进行大写（例如，使用 `用于与 Git 仓库交互的工具。`，而不是 ``用于与 `git` 仓库交互的工具。``）。 +- 首字母缩写（即协议、工具等）在没有本地同类物时不应进行翻译。 +- 当编写包含键盘按键或键盘快捷键时，建议将它们用反引号括起来，以突出显示在描述中（即 ``打印给定文件的最后几行，并一直读取直到按下 `Ctrl + C`：``）。 或者，您可以将它们记录为单独的命令，然后选择性地将它们突出显示为占位符（即 `:wq{{Enter}}` 或 `:wq` 或 `:wq(Enter)`）。 + +## 斜体和粗体 + +请不要在页面上使用 *斜体*、**粗体** 或任何其他文本样式。这些样式被用于客户端对占位符的修饰。 + +## 更多信息链接 + +- 在`更多信息`链接行上，我们更推荐链接到作者提供的命令行参考文档或 man 手册。如果没有提供，请使用 作为所有系统（除 `osx` 和除了 FreeBSD 之外的 BSD 平台）的默认链接。或者，如果命令没有文档页面，您也可以链接到作者的网站或教程页面。 + +- 对于 `osx`：苹果在 Xcode 中分发内置的 man 手册 [在这里](https://developer.apple.com/documentation/os/reading_unix_manual_pages)。对于那里记录的命令，我们建议使用 https://keith.github.io/xcode-man-pages/, 这是 Xcode 捆绑的所有苹果 man 手册的 HTML。 + +- **所有链接必须放在尖括号（`<` 和 `>`）中，以便在客户端中正确呈现。** + +- 我们更倾向于在翻译页面中直接使用英文页面的更多信息链接。 + +### 版本化链接 + +当一个应用程序或发行版的包具有版本化链接时，我们更倾向于链接到文档的最新版本（即 `latest`），或者如果网站自动重定向到文档的最新版本，则不用链接到任何版本。 + +例如，使用： + +- 而不是 。 +- 而不是 。 + +### Microsoft Learn 链接 + +当链接到 Microsoft Learn 页面时，请删除地址中的语言环境，因为网站会自动重定向到读者的首选语言环境。例如，使用 而不是 。 + +此外，如果链接与 PowerShell 命令文档相关，请删除**文档版本指示符**（即文档来源的 PowerShell/module 版本），即地址中以 `?view=` 开头的部分。 + +- 使用 而不是 。 +- 使用 而不是 。 + +## 帮助和版本命令 + +- 通常我们将帮助命令和版本命令**按照这个顺序**放在页面的**最后两个**示例中，以突出页面开头更实用的命令。如果需要，它们可以被替换为其他有用的示例。 +- 为了保持一致性，我们更推荐使用通用的术语 `显示帮助` 和 `显示版本` 来描述这些命令。 +- 如果命令在 Windows 等平台中使用了不同的标志，建议记录下帮助和版本示例。 + +## 特定语言规则 + +以下部分包含了用于翻译页面的额外的特定语言规则： ## 中西文混排规则 @@ -82,19 +345,19 @@ tldr --render {{page.md}} 以下规则适用于中文（zh）和繁体中文（zh_TW）： -1. 在西文单词和数字前后放置一个空格。 - 例如：`列出所有 docker 容器` 而不是 `列出所有docker容器`。 - 例如：`宽度为 50 个字` 而不是 `宽度为50个字`。 -2. 除了度数和百分比，在数字和单位之间留一个空格。 - 例如：`容量 50 MB` 而不是 `容量 50MB`。 +1. 在西文单词和数字前后放置一个空格。 + 例如：`列出所有 docker 容器` 而不是 `列出所有 docker 容器`。 + 例如：`宽度为 50 个字` 而不是 `宽度为 50 个字`。 +2. 除了度数和百分比，在数字和单位之间留一个空格。 + 例如：`容量 50 MB` 而不是 `容量 50MB`。 对于度数和百分比：使用 `50°C` 和 `50%` 而不是 `50 °C` 和 `50 %`. -3. 不要在全角标点符号前后放置空格。 +3. 不要在全角标点符号前后放置空格。 例如：`开启 shell，进入交互模式` 而不是 `开启 shell ，进入交互模式`。 -4. 除了西文长句，一律使用全角标点符号。 - 例如：`嗨，你好。` 而不是 `嗨, 你好.`。 -5. 当最句子最后一个字符是半角时，使用半角标点符号来结束句子。 +4. 除了西文长句，一律使用全角标点符号。 + 例如：`嗨，你好。` 而不是 `嗨，你好.`。 +5. 当最句子最后一个字符是半角时，使用半角标点符号来结束句子。 例如：`将代码转化为 Python 3.` 而不是 `将代码转化为 Python 3。`。 -6. 使用精准的专有名词，不要使用非官方的中文缩写。 +6. 使用精准的专有名词，不要使用非官方的中文缩写。 例如：`Facebook` 而非 `facebook`、`fb` 或 `脸书`。 为保持可读性和一致性，将页面翻译成中文时，请尽可能遵守以上 6 条规则。