From fe59c6a93000d5fc48e3906a8647af9329966375 Mon Sep 17 00:00:00 2001 From: blueskyson Date: Sat, 31 Jul 2021 17:00:00 +0800 Subject: [PATCH 1/3] style-guide: add Chinese translation English version --- contributing-guides/zh/style-guide.en.md | 90 ++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 contributing-guides/zh/style-guide.en.md diff --git a/contributing-guides/zh/style-guide.en.md b/contributing-guides/zh/style-guide.en.md new file mode 100644 index 00000000000000..8085d30e59c533 --- /dev/null +++ b/contributing-guides/zh/style-guide.en.md @@ -0,0 +1,90 @@ +# Style guide + +When you are contributing to `tldr`, please follow the format specifications below. + +Please note that the following specifications only apply to the Chinese translation of the `tldr` page. + +## Layout + +First of all, Your page should look like: + +``` +# 命令名称 + +> 短小精悍的描述。 +> 描述最好只有一行；当然，如果需要，也可以是两行。 +> 更多信息：. + +- 命令描述： + +`命令 -选项1 -选项2 -参数1 {{参数的值}}` + +- 命令描述： + +`命令 -选项1 -选项2` +``` + +When you submit your contribution to a pull request, a script will automatically check whether your contribution conforms to the above format. + +You can also test your contributions locally before submitting them: + +``` +npm install tldr-lint +tldrl -f {{page.md}} +``` + +For other ways to use `tldrl`, such as checking the formats of an entire directory, [`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md) is your best place to go! + +If you use the Node.js client of tldr-pages, you can use `-f` (`--render`) option after the command to preview your page locally: + +``` +tldr --render {{page.md}} +``` + +## Chinese-Latin mix and format details + +In this section, **except for commands**, the text layout follows [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md). + +Brief summary: + +- A space must be added between Chinese and Latin words, numbers, and units. +- No spaces are added between full-width punctuations and other characters. +- Use full-width punctuations except for long Latin clauses. +- Use precise form for technical terms, and do not use Chinese-specific abbreviations. + +For more information and examples of Chinese-Latin mix, please check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md) and Pull request [#5420](https://github.com/tldr-pages/tldr/pull/5240). + +## Token syntax + +When the command involves the value provided by the user, please use the `{{token}}` syntax to make the `tldr` client highlight them automatically: + +`tar -cf {{目标.tar}} {{文件1}} {{文件2}} {{文件3}}` + +When translating, please translate tokens into Chinese as much as possible. The following are the rules for naming token: + +1. The token must be short and precise. + For example, `{{源文件}}` or `{{钱包.txt}}`. +2. If the token is written in Latin, use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens. +3. For any reference to paths to files or directories, use the format `{{目录/子目录/<占位符>}}`. + For example, `ln -s {{目录/子目录/源文件}} {{目录/子目录/链接}}`. + In case of a possible reference both to a file or a directory, use `{{目录/子目录/文件或目录}}` +4. Unless the file is specific, the path format of the above `{{目录/子目录/<占位符>}}` applies to all commands that include a path. +5. If the file extension required by the command is ascertained, please add the file extension in the token. + For example, `unrar x {{压缩包.rar}}`. + If the file **requires** to have an extension, use `{{.ext}}`. + For example, `find {{起始目录}} -name '{{*.ext}}'` using `{{*.ext}}` explains the command without being unnecessarily specific; + But in a command like `wc -l {{文件}}`, using token without extension `{{文件}}` is sufficient. +6. If the example is clearer with an actual value rather than a generic placeholder, please use a value in the example. + For example, `iostat {{2}}` is clearer than `iostat {{以秒为单位的间隔}}`. +7. If a command may have an irreversible impact on the file system or device, please rewrite the example carefully so that it cannot be copied, pasted and executed blindly. + For example, `ddrescue --force --no-scrape /dev/sda /dev/sdb` may cause a devastating impact to the system when blindly copied and pasted; + `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` is safer. + Thus, please use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`. + +Tokens should be as understandable as possible and make people know how to fill them with other value at first glance. + +If any technical term appears in a command description, please enclose it with `backquotes`: + +1. Paths, ex. `package.json`, `/etc/package.json`. +2. Extensions, ex. `.dll`. +3. Commands, ex. `ls`. \ No newline at end of file From 781876c851e19bb3d25b3738fe375e478139f87c Mon Sep 17 00:00:00 2001 From: blueskyson Date: Tue, 3 Aug 2021 18:49:21 +0800 Subject: [PATCH 2/3] Add Chinese-specific rules --- contributing-guides/style-guide.md | 25 +++++++ contributing-guides/zh/style-guide.en.md | 90 ------------------------ 2 files changed, 25 insertions(+), 90 deletions(-) delete mode 100644 contributing-guides/zh/style-guide.en.md diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index c1e7c9ab90c310..88553d7cea40a8 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -78,6 +78,7 @@ Use backticks on the following: 3. Commands, ex. `ls`. ## Serial Comma + When declaring a list of 3 or more items, use a [serial comma](https://en.wikipedia.org/wiki/Serial_comma), also known as the Oxford comma. When the serial comma is ommitted, it can create ambiguity. @@ -91,3 +92,27 @@ The example above does not use a serial comma, so this could mean one of two thi This can be resolved by inserting a comma before the "and" or "or" in the final element in the list. > Delete the Git branches, tags, and remotes. + +## Chinese-Specific Rules + +When Chinese words, Latin words and Arabic numerals are written in the same sentence, it takes more attention to copywriting. + +The following guidelines are applied to Chinese (zh) and traditional Chinese (zh_TW): + +1. Place one space before/after English words. + For example, use `列出所有 docker 容器` rather than `列出所有docker容器`. +2. Place one space before/after numbers. + For example, use `宽度为 50 个字` rather than `宽度为50个字`. +3. Place one space between numbers and units **except** degrees and percentages. + For example, use `容量 50 MB` rather than `容量 50MB`. + For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`. +4. No additional spaces before/after full-width punctuations. + For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式` +5. Use full-width punctuations except for long Latin clauses. + For example, use `嗨，你好。` rather than `嗨, 你好.` +6. Use precise form for technical terms, and do not use unofficial Chinese abbreviations. + For example, use `Facebook` rather than `facebook`, `fb` or `脸书`. + +In order to maintain readability and normalization, please comply the 6 rules above as much as possible when translating pages into Chinese. + +For more information and examples of Chinese-specific rules, check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md). \ No newline at end of file diff --git a/contributing-guides/zh/style-guide.en.md b/contributing-guides/zh/style-guide.en.md deleted file mode 100644 index 8085d30e59c533..00000000000000 --- a/contributing-guides/zh/style-guide.en.md +++ /dev/null @@ -1,90 +0,0 @@ -# Style guide - -When you are contributing to `tldr`, please follow the format specifications below. - -Please note that the following specifications only apply to the Chinese translation of the `tldr` page. - -## Layout - -First of all, Your page should look like: - -``` -# 命令名称 - -> 短小精悍的描述。 -> 描述最好只有一行；当然，如果需要，也可以是两行。 -> 更多信息：. - -- 命令描述： - -`命令 -选项1 -选项2 -参数1 {{参数的值}}` - -- 命令描述： - -`命令 -选项1 -选项2` -``` - -When you submit your contribution to a pull request, a script will automatically check whether your contribution conforms to the above format. - -You can also test your contributions locally before submitting them: - -``` -npm install tldr-lint -tldrl -f {{page.md}} -``` - -For other ways to use `tldrl`, such as checking the formats of an entire directory, [`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md) is your best place to go! - -If you use the Node.js client of tldr-pages, you can use `-f` (`--render`) option after the command to preview your page locally: - -``` -tldr --render {{page.md}} -``` - -## Chinese-Latin mix and format details - -In this section, **except for commands**, the text layout follows [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md). - -Brief summary: - -- A space must be added between Chinese and Latin words, numbers, and units. -- No spaces are added between full-width punctuations and other characters. -- Use full-width punctuations except for long Latin clauses. -- Use precise form for technical terms, and do not use Chinese-specific abbreviations. - -For more information and examples of Chinese-Latin mix, please check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md) and Pull request [#5420](https://github.com/tldr-pages/tldr/pull/5240). - -## Token syntax - -When the command involves the value provided by the user, please use the `{{token}}` syntax to make the `tldr` client highlight them automatically: - -`tar -cf {{目标.tar}} {{文件1}} {{文件2}} {{文件3}}` - -When translating, please translate tokens into Chinese as much as possible. The following are the rules for naming token: - -1. The token must be short and precise. - For example, `{{源文件}}` or `{{钱包.txt}}`. -2. If the token is written in Latin, use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens. -3. For any reference to paths to files or directories, use the format `{{目录/子目录/<占位符>}}`. - For example, `ln -s {{目录/子目录/源文件}} {{目录/子目录/链接}}`. - In case of a possible reference both to a file or a directory, use `{{目录/子目录/文件或目录}}` -4. Unless the file is specific, the path format of the above `{{目录/子目录/<占位符>}}` applies to all commands that include a path. -5. If the file extension required by the command is ascertained, please add the file extension in the token. - For example, `unrar x {{压缩包.rar}}`. - If the file **requires** to have an extension, use `{{.ext}}`. - For example, `find {{起始目录}} -name '{{*.ext}}'` using `{{*.ext}}` explains the command without being unnecessarily specific; - But in a command like `wc -l {{文件}}`, using token without extension `{{文件}}` is sufficient. -6. If the example is clearer with an actual value rather than a generic placeholder, please use a value in the example. - For example, `iostat {{2}}` is clearer than `iostat {{以秒为单位的间隔}}`. -7. If a command may have an irreversible impact on the file system or device, please rewrite the example carefully so that it cannot be copied, pasted and executed blindly. - For example, `ddrescue --force --no-scrape /dev/sda /dev/sdb` may cause a devastating impact to the system when blindly copied and pasted; - `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` is safer. - Thus, please use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`. - -Tokens should be as understandable as possible and make people know how to fill them with other value at first glance. - -If any technical term appears in a command description, please enclose it with `backquotes`: - -1. Paths, ex. `package.json`, `/etc/package.json`. -2. Extensions, ex. `.dll`. -3. Commands, ex. `ls`. \ No newline at end of file From 2c6846f7973d9166453a4381cf5cd03af533166c Mon Sep 17 00:00:00 2001 From: blueskyson Date: Thu, 5 Aug 2021 22:07:29 +0800 Subject: [PATCH 3/3] Combine rule 1 and rule 2 --- contributing-guides/style-guide.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index 88553d7cea40a8..b86566f2c2beb2 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -99,20 +99,19 @@ When Chinese words, Latin words and Arabic numerals are written in the same sent The following guidelines are applied to Chinese (zh) and traditional Chinese (zh_TW): -1. Place one space before/after English words. - For example, use `列出所有 docker 容器` rather than `列出所有docker容器`. -2. Place one space before/after numbers. +1. Place one space before/after English words and numbers. + For example, use `列出所有 docker 容器` rather than `列出所有docker容器`. For example, use `宽度为 50 个字` rather than `宽度为50个字`. -3. Place one space between numbers and units **except** degrees and percentages. +2. Place one space between numbers and units **except** degrees and percentages. For example, use `容量 50 MB` rather than `容量 50MB`. For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`. -4. No additional spaces before/after full-width punctuations. +3. No additional spaces before/after full-width punctuations. For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式` -5. Use full-width punctuations except for long Latin clauses. +4. Use full-width punctuations except for long Latin clauses. For example, use `嗨，你好。` rather than `嗨, 你好.` -6. Use precise form for technical terms, and do not use unofficial Chinese abbreviations. +5. Use precise form for technical terms, and do not use unofficial Chinese abbreviations. For example, use `Facebook` rather than `facebook`, `fb` or `脸书`. -In order to maintain readability and normalization, please comply the 6 rules above as much as possible when translating pages into Chinese. +In order to maintain readability and normalization, please comply the 5 rules above as much as possible when translating pages into Chinese. For more information and examples of Chinese-specific rules, check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md). \ No newline at end of file