mirror of
https://github.com/tldr-pages/tldr.git
synced 2024-08-16 15:30:24 +03:00
CONTRIBUTING: document the directory structure (#12314)
* CONTRIBUTING: document the directory structure * CONTRIBUTING: rename the subtitle "Pages directory" to "Directory structure" * CONTRIBUTING: fix casing of platforms list * CONTRIBUTING: use plural form of "directory" Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com> * CONTRIBUTING: remove "valid reason" * CONTRIBUTING: change platform directory listing for a numbered list format * CONTRIBUTING: apply suggestions from code review Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com> --------- Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com> Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
This commit is contained in:
parent
a609b14c83
commit
d77ae17016
@ -48,6 +48,30 @@ Use proper judgement, keeping simplicity and user-friendliness as the top priori
|
||||
|
||||
When in doubt, have a look at a few existing pages :).
|
||||
|
||||
## Directory structure
|
||||
|
||||
The English pages directory is called `pages`, under which the platform directories are present. Language-specific directories must follow the pattern `pages.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>[_<country>]`, where:
|
||||
|
||||
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
|
||||
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
|
||||
|
||||
The `<country>` code is optional and should only be added when there is a substantial difference between a language (`ll`) and its regional dialects (`ll_CC1`, `ll_CC2`, etc.). For example, both `fr_FR` and `fr_BE` should fall under the same `pages.fr` directory since there virtually is no difference in writing between standard French and Belgian French.
|
||||
|
||||
### Platform directories
|
||||
|
||||
The `pages` directory and `pages.*` language-specific directories contain the platform directories, if they have at least one page of that platform.
|
||||
|
||||
1. If the command is available for **two or more** platforms, put it **under the `common` directory**.
|
||||
2. If the command is **only** available for **one** platform, these are the available directories followed by their right platform:
|
||||
- `android`: Android
|
||||
- `freebsd`: FreeBSD
|
||||
- `openbsd`: OpenBSD
|
||||
- `osx`: OSX/Mac OS/macOS (will be replaced by `macos`)
|
||||
- `linux`: any Linux distro
|
||||
- `netbsd`: NetBSD
|
||||
- `sunos`: SunOS
|
||||
- `windows`: Windows
|
||||
|
||||
## Markdown format
|
||||
|
||||
As a quick reference, the format of each page should match the following template:
|
||||
@ -140,17 +164,10 @@ See these examples for reference:
|
||||
|
||||
## Translations
|
||||
|
||||
Translation of pages can be done by simply creating the corresponding page within the appropriate language-specific directory, creating that as well if it does not already exist.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Translations of pages should be done based on the English (US) page in the `pages` directory. If the English pages don't exist for the command, it should be added first in a PR before creating a translation.
|
||||
|
||||
Language specific directories must follow the pattern `pages.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>[_<country>]`, where:
|
||||
|
||||
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
|
||||
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
|
||||
|
||||
The `<country>` code is optional and should only be added when it is needed. In other words, only when there is a valid reason to distinguish between a language (`ll`) and its regional dialects (`ll_CC1`, `ll_CC2`, etc.). For example, both `fr_FR` and `fr_BE` should fall under the same `pages.fr` directory since there virtually is no difference in writing between standard French and Belgian French.
|
||||
Translation of pages can be done by simply creating the corresponding page within the appropriate [language-specific directory](#pages-directory), creating that as well if it does not already exist.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> When adding a new language to `tldr`, it is suggested to add it to the [translation templates](contributing-guides/translation-templates) along with any page additions.
|
||||
|
Loading…
Reference in New Issue
Block a user