From 01cf9d824bc6a33abe53e5a427232734253cceb7 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Thu, 11 Jun 2020 15:27:10 +0100 Subject: [PATCH 01/14] CLIENT-SPECIFICATION: clarify fallback to english --- CLIENT-SPECIFICATION.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 150fd572bc8d3..8b7ef4047cde8 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -1,6 +1,6 @@ # tldr-pages client specification -**Current Specification Version:** 1.2 +**Current Specification Version:** 1.3 This document contains the official specification for tldr-pages clients. It is _not_ a specification of the format of the pages themselves - only a specification of how a user should be able to interface with an official client. For a list of previous versions of the specification, see the [changelog section](#Changelog) below. @@ -179,6 +179,8 @@ The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/ht The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. In absence of `LANG` and if this environment variable is present, a client MUST use the defined priority list to decide on the language of pages to display. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). +Regardless of the language selected through the above environment variables, clients SHOULD always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). + The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead. **Note that** it is highly RECOMMENDED to give precedence to the platform first, and then the language. In other words, look for a platform under each language, before falling back to the next preferred language. This ensures a meaningful and correct page resolution. @@ -201,7 +203,10 @@ Caching SHOULD be done according to the user's language configuration (if any), ## Changelog - - [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md) (#3168) + - [v1.3, June 11th 2020]() + - Clarified fallback to english in the language resolution algorithm. + + - [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/524d44eb13ff6c0ff70089bd152b075418fc71b2/CLIENT-SPECIFICATION.md) (#3168) - Addition of a new `-L, --language` recommended command-line option. - Rewording of the language section also encouraging the use of configuration files for language. - Shift from BCP-47 to POSIX style locale tags, with consequent **deprecation of previous versions of the spec**. From 14508cfc13e9275ab8978cc394df5caf9f3cd4b0 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Thu, 11 Jun 2020 15:29:38 +0100 Subject: [PATCH 02/14] Update CLIENT-SPECIFICATION.md --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 8b7ef4047cde8..1b6c2c600342f 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -203,7 +203,7 @@ Caching SHOULD be done according to the user's language configuration (if any), ## Changelog - - [v1.3, June 11th 2020]() + - [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md) (#4101) - Clarified fallback to english in the language resolution algorithm. - [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/524d44eb13ff6c0ff70089bd152b075418fc71b2/CLIENT-SPECIFICATION.md) (#3168) From e69a64e605da3b77a6258450a1d64f422e721124 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zlatan=20Vasovi=C4=87?= Date: Fri, 19 Jun 2020 13:00:15 +0200 Subject: [PATCH 03/14] Update CLIENT-SPECIFICATION.md command line -> command-line when used as an adjective --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 1b6c2c600342f..0a0b3610588ca 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -179,7 +179,7 @@ The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/ht The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. In absence of `LANG` and if this environment variable is present, a client MUST use the defined priority list to decide on the language of pages to display. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). -Regardless of the language selected through the above environment variables, clients SHOULD always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). +Regardless of the language selected through the above environment variables, clients SHOULD always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead. From c22a3dea2dc3da23ddb2d04c3096256c8a79a7bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zlatan=20Vasovi=C4=87?= Date: Fri, 19 Jun 2020 13:00:49 +0200 Subject: [PATCH 04/14] english -> English --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 0a0b3610588ca..68041167aadfb 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -204,7 +204,7 @@ Caching SHOULD be done according to the user's language configuration (if any), ## Changelog - [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md) (#4101) - - Clarified fallback to english in the language resolution algorithm. + - Clarified fallback to English in the language resolution algorithm. - [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/524d44eb13ff6c0ff70089bd152b075418fc71b2/CLIENT-SPECIFICATION.md) (#3168) - Addition of a new `-L, --language` recommended command-line option. From d19c315c02ba9319c603a3e93c2db532bc4782ab Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sun, 21 Jun 2020 21:35:14 +0100 Subject: [PATCH 05/14] client-spec: make english fallback a MUST --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 68041167aadfb..a57e73506bb8e 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -179,7 +179,7 @@ The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/ht The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. In absence of `LANG` and if this environment variable is present, a client MUST use the defined priority list to decide on the language of pages to display. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). -Regardless of the language selected through the above environment variables, clients SHOULD always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). +Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead. From ebeb655e6b0019de478553b4cfae267c17d1aabf Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 23 Jun 2020 20:26:51 +0100 Subject: [PATCH 06/14] client-spec: add example table. Co-authored-by: Matthew Peveler --- CLIENT-SPECIFICATION.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index a57e73506bb8e..37fefdf75626e 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -180,7 +180,15 @@ The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/ht The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. In absence of `LANG` and if this environment variable is present, a client MUST use the defined priority list to decide on the language of pages to display. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). - +LANGUAGE | LANG | Result +---------|------|------- +it,cz,de | cz | it,cz,de,en +it,de,fr | cz | it,de,fr,cz,en + -- | it | it,en +it,cz | -- | en + -- | -- | en + +Note: `LANG` or `LANGUAGE` may contain a value of `C` or `POSIX` and this should be treated as ignored. The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead. **Note that** it is highly RECOMMENDED to give precedence to the platform first, and then the language. In other words, look for a platform under each language, before falling back to the next preferred language. This ensures a meaningful and correct page resolution. From 2019aec33818321ee7a7c644619fa3f04b531bef Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sat, 27 Jun 2020 21:08:13 +0100 Subject: [PATCH 07/14] client-spec: update language wording fo initial paragraph Co-authored-by: Matthew Peveler --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 37fefdf75626e..ba24f863232c1 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -177,7 +177,7 @@ Pages can be written in multiple languages. If a client has access to environmen The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html), if present, MUST be used to determine the language of pages to display. -The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. In absence of `LANG` and if this environment variable is present, a client MUST use the defined priority list to decide on the language of pages to display. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). +The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. The `LANG` environment variable MUST be present for `LANGUAGE` to be used, and then `LANGUAGE` takes precendence over `LANG`. If `LANG` is set to a language not in `LANGUAGE`, then `LANG` should be appended to the end of the priority list. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). LANGUAGE | LANG | Result From b7c93cff4b3c44f2edd82c9e7d27ed1f0a686a6e Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sat, 27 Jun 2020 21:08:48 +0100 Subject: [PATCH 08/14] Update CLIENT-SPECIFICATION.md Co-authored-by: Marco Bonelli <14198070+mebeim@users.noreply.github.com> --- CLIENT-SPECIFICATION.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index ba24f863232c1..0de9cd5baea8f 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -179,7 +179,8 @@ The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/ht The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. The `LANG` environment variable MUST be present for `LANGUAGE` to be used, and then `LANGUAGE` takes precendence over `LANG`. If `LANG` is set to a language not in `LANGUAGE`, then `LANG` should be appended to the end of the priority list. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). -Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients REALLY SHOULD tell the user that the page does not exist in their requested language however if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients OUGHT TO notify the user that a page is available in other languages if present). +Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients SHOULD tell the user that the page does not exist in their requested language if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients MAY notify the user that a page is available in other languages if present). + LANGUAGE | LANG | Result ---------|------|------- it,cz,de | cz | it,cz,de,en From e83929fb3b53329fe49bb8100f7b9c59ad23914d Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sat, 27 Jun 2020 21:09:14 +0100 Subject: [PATCH 09/14] Update CLIENT-SPECIFICATION.md Co-authored-by: Marco Bonelli <14198070+mebeim@users.noreply.github.com> --- CLIENT-SPECIFICATION.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 0de9cd5baea8f..701b49838c4ef 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -189,7 +189,8 @@ it,de,fr | cz | it,de,fr,cz,en it,cz | -- | en -- | -- | en -Note: `LANG` or `LANGUAGE` may contain a value of `C` or `POSIX` and this should be treated as ignored. +Note: `LANG` or `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored. + The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead. **Note that** it is highly RECOMMENDED to give precedence to the platform first, and then the language. In other words, look for a platform under each language, before falling back to the next preferred language. This ensures a meaningful and correct page resolution. From ec855f96ee515e29d86973e8664c49db34867ac0 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sat, 27 Jun 2020 21:09:36 +0100 Subject: [PATCH 10/14] Update CLIENT-SPECIFICATION.md Co-authored-by: Marco Bonelli <14198070+mebeim@users.noreply.github.com> --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 701b49838c4ef..d81641a41d9f7 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -183,7 +183,7 @@ Regardless of the language selected through the above environment variables, cli LANGUAGE | LANG | Result ---------|------|------- -it,cz,de | cz | it,cz,de,en +`it:cz:de` | `cz` | `it`, `cz`, `de`, `en` it,de,fr | cz | it,de,fr,cz,en -- | it | it,en it,cz | -- | en From 99a340249744d165233ec97ac20133d886bc336f Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sat, 27 Jun 2020 21:13:10 +0100 Subject: [PATCH 11/14] client-spec: fix table & update changelog --- CLIENT-SPECIFICATION.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index d81641a41d9f7..ce0c3ddf1939e 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -181,13 +181,13 @@ The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manua Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients SHOULD tell the user that the page does not exist in their requested language if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients MAY notify the user that a page is available in other languages if present). -LANGUAGE | LANG | Result ----------|------|------- -`it:cz:de` | `cz` | `it`, `cz`, `de`, `en` -it,de,fr | cz | it,de,fr,cz,en - -- | it | it,en -it,cz | -- | en - -- | -- | en +LANGUAGE | LANG | Result +------------|-------|---------- +`it:cz:de` | `cz` | `it`, `cz`, `de`, `en` +`it:de:fr` | `cz` | `it`, `de`, `fr`, `cz`, `en` +-- | `it` | `it`, `en` +`it,cz` | -- | `en` +-- | -- | `en` Note: `LANG` or `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored. @@ -215,6 +215,7 @@ Caching SHOULD be done according to the user's language configuration (if any), - [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md) (#4101) - Clarified fallback to English in the language resolution algorithm. + - Update `LANG` and `LANGUAGE` environment variable to conform to the GNU spec. - [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/524d44eb13ff6c0ff70089bd152b075418fc71b2/CLIENT-SPECIFICATION.md) (#3168) - Addition of a new `-L, --language` recommended command-line option. From 35fc27b716adbc08a4b7b9475cd38aa99d510bce Mon Sep 17 00:00:00 2001 From: Marco Bonelli <14198070+mebeim@users.noreply.github.com> Date: Sat, 27 Jun 2020 22:46:14 +0200 Subject: [PATCH 12/14] Update CLIENT-SPECIFICATION.md --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index ce0c3ddf1939e..2b1ef43176e59 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -186,7 +186,7 @@ LANGUAGE | LANG | Result `it:cz:de` | `cz` | `it`, `cz`, `de`, `en` `it:de:fr` | `cz` | `it`, `de`, `fr`, `cz`, `en` -- | `it` | `it`, `en` -`it,cz` | -- | `en` +`it:cz` | -- | `en` -- | -- | `en` Note: `LANG` or `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored. From ea538a95f5c4fb6e516ffb5281a78f45c72beea1 Mon Sep 17 00:00:00 2001 From: Marco Bonelli Date: Mon, 13 Jul 2020 19:12:08 +0200 Subject: [PATCH 13/14] Client spec: clarify usage of language env vars. --- CLIENT-SPECIFICATION.md | 42 ++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 2b1ef43176e59..16c9a6f86bcc7 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -173,29 +173,37 @@ If multiple versions of a page were found for different platforms, then a client ## Language -Pages can be written in multiple languages. If a client has access to environment variables, several standard ones exist to specify the language in which a client should operate. If not, then clients MUST make reasonable assumptions based on the information provided by the environment in which they operate (e.g. consulting `navigator.languages` in a browser, etc.). If possible, it is RECOMMENDED to also make language configurable, as to not only rely on the environment. Clients SHOULD therefore offer options to configure or override the language using configuration files or command line options (like `-L, --language` as suggested in the [arguments section](#arguments) above). +Pages can be written in multiple languages. If a client has access to environment variables, it MUST use them derive the preferred user language as described in the next paragraphs. If not, then clients MUST make reasonable assumptions based on the information provided by the environment in which they operate (e.g. consulting `navigator.languages` in a browser, etc.). -The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html), if present, MUST be used to determine the language of pages to display. +The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) specifies the user preferred locale (in the form `ll[_CC][.encoding]`). The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of locales (in the form `l1:l2:...`) that can be used if the locale defined by `LANG` is not available. Both `LANG` and `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored. -The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of languages that a user wishes to read in. The `LANG` environment variable MUST be present for `LANGUAGE` to be used, and then `LANGUAGE` takes precendence over `LANG`. If `LANG` is set to a language not in `LANGUAGE`, then `LANG` should be appended to the end of the priority list. If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable, and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). +In order to determine the display language, a client MUST: -Regardless of the language selected through the above environment variables, clients MUST always attempt to fallback to English if the page does not exist in the requested languages. In this case clients SHOULD tell the user that the page does not exist in their requested language if it was not English. If the client supports a command-line argument for language, the client MUST only attempt to show the page in that language (clients MAY notify the user that a page is available in other languages if present). +1. Check the value of `LANG`. +2. Extract the priority list from `LANGUAGE`. If not set, start with an empty priority list. +3. Append the value of `LANG` to the priority list. +4. Follow the priority list in order and use the first available language. +5. Fall back to English if none of the languages are available. -LANGUAGE | LANG | Result -------------|-------|---------- -`it:cz:de` | `cz` | `it`, `cz`, `de`, `en` -`it:de:fr` | `cz` | `it`, `de`, `fr`, `cz`, `en` --- | `it` | `it`, `en` -`it:cz` | -- | `en` --- | -- | `en` +Examples: -Note: `LANG` or `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored. + LANG | LANGUAGE | Result +-------|-----------|----------------------------- + `cz` |`it:cz:de` | `it`, `cz`, `de`, `en` + `cz` |`it:de:fr` | `it`, `de`, `fr`, `cz`, `en` + `it` |unset | `it`, `en` + unset |`it:cz` | `en` + unset |unset | `en` + +Regardless of the language determined through the environment, clients MUST always attempt to fallback to English if the page does not exist in the user preferred language. Clients MAY notify the user when a page in their preferred language cannot be found (optionally including a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)). + +It is also RECOMMENDED to make the language configurable, as to not only rely on the environment. Clients SHOULD offer options to configure or override the language using configuration files or even command line options (like `-L, --language` as suggested in the [arguments section](#arguments) above). If such a command-line option is specified, a client must strictly adhere to its value, and MUST NOT show pages in a different language, failing with an appropriate error message instead. The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead. -**Note that** it is highly RECOMMENDED to give precedence to the platform first, and then the language. In other words, look for a platform under each language, before falling back to the next preferred language. This ensures a meaningful and correct page resolution. +**Note that** for page lookup it is highly RECOMMENDED to give precedence to the platform over the language. In other words, look for a platform under each language, before checking the next preferred language. This ensures a meaningful and correct page resolution. -Here's an example of how the lookup should be done on `linux` having set `LANGUAGE="it:fr:en"`: +Here's an example of how the lookup should be done on `linux` having set `LANG=it` and `LANGUAGE="it:fr:en"`: 1. pages.it/linux/some-page.md -> does not exist 2. pages.fr/linux/some-page.md -> does not exist @@ -206,15 +214,15 @@ Here's an example of how the lookup should be done on `linux` having set `LANGUA ## Caching -If appropriate, it is RECOMMENDED that clients implement a cache of pages. If implemented, clients MUST download the archive either from **[http://tldr.sh/assets/tldr.zip](http://tldr.sh/assets/tldr.zip)** or [https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/master/assets/tldr.zip](https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/master/assets/tldr.zip) (which is pointed by the first link). +If appropriate, it is RECOMMENDED that clients implement a cache of pages. If implemented, clients MUST download the archive either from **[http://tldr.sh/assets/tldr.zip](http://tldr.sh/assets/tldr.zip)** or [https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/master/assets/tldr.zip](https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/master/assets/tldr.zip) (which is pointed to by the first link). -Caching SHOULD be done according to the user's language configuration (if any), as to not waste unneeded space for unneeded languages. Additionally, clients MAY automatically update the cache on a regular basis. +Caching SHOULD be done according to the user's language configuration (if any), as to not waste unneeded space for unused languages. Additionally, clients MAY automatically update the cache on a regular basis. ## Changelog - [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md) (#4101) - - Clarified fallback to English in the language resolution algorithm. + - Clarified fallback to English in the language resolution algorithm. - Update `LANG` and `LANGUAGE` environment variable to conform to the GNU spec. - [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/524d44eb13ff6c0ff70089bd152b075418fc71b2/CLIENT-SPECIFICATION.md) (#3168) From ccdcdb4141385ed26b0e796288f4f2086ad1309a Mon Sep 17 00:00:00 2001 From: Marco Bonelli <14198070+mebeim@users.noreply.github.com> Date: Sat, 18 Jul 2020 10:46:13 +0200 Subject: [PATCH 14/14] Update CLIENT-SPECIFICATION.md Co-authored-by: Starbeamrainbowlabs --- CLIENT-SPECIFICATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 16c9a6f86bcc7..13c00c9e4f511 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -179,7 +179,7 @@ The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/ht In order to determine the display language, a client MUST: -1. Check the value of `LANG`. +1. Check the value of `LANG`. If not set, then skip to step 5. 2. Extract the priority list from `LANGUAGE`. If not set, start with an empty priority list. 3. Append the value of `LANG` to the priority list. 4. Follow the priority list in order and use the first available language.