From b147f89713702b54ee25ad2101366f3927766d3b Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Thu, 17 Oct 2024 23:53:17 +0200 Subject: [PATCH] doc: Clarify locale names and language names. Reported by Arfrever at . * gettext-runtime/doc/nls.texi (INSTALL Matters, Using This Package): Mention ll_CC as alterntive to ll, and that ll can be a 3-letter code. * gettext-tools/doc/gettext.texi (Locale Names, Header Entry, Installers): Likewise. --- gettext-runtime/doc/nls.texi | 42 ++++++++++++++++++++++++++-------- gettext-tools/doc/gettext.texi | 42 ++++++++++++++++++++++++++++------ 2 files changed, 68 insertions(+), 16 deletions(-) diff --git a/gettext-runtime/doc/nls.texi b/gettext-runtime/doc/nls.texi index 5208d9eb0..b763d64d6 100644 --- a/gettext-runtime/doc/nls.texi +++ b/gettext-runtime/doc/nls.texi @@ -1,5 +1,5 @@ @c This file is part of the GNU gettext manual. -@c Copyright (C) 1995-2023 Free Software Foundation, Inc. +@c Copyright (C) 1995-2024 Free Software Foundation, Inc. @c See the file gettext.texi for copying conditions. @node The original ABOUT-NLS @@ -68,14 +68,28 @@ library and will decide to use it. If not, you may have to to use the look for it. Internationalized packages usually have many @file{po/@var{ll}.po} -files, where @var{ll} gives an @w{ISO 639} two-letter code -identifying the language. Unless translations have been forbidden +or @file{po/@var{ll}_@var{CC}.po} +files, where + +@itemize @bullet +@item +@var{ll} gives an @w{ISO 639} two-letter code identifying the language. +For some languages, +a two-letter code does not exist, and a three-letter code is used instead. +@item +The optional @var{CC} is an @w{ISO 3166} two-letter code of a country or +territory. +@end itemize + +@noindent +Unless translations have been forbidden at @code{configure} time by using the @samp{--disable-nls} switch, all available translations are installed together with the package. However, the environment variable @code{LINGUAS} may be set, prior -to configuration, to limit the installed set. @code{LINGUAS} should -then contain a space separated list of two-letter codes, stating -which languages are allowed. +to configuration, to limit the installed set. +@code{LINGUAS} should then contain a space separated list of locale names +(of the form @code{@var{ll}} or @code{@var{ll}_@var{CC}}, +stating which languages or language variants are allowed. @node Using This Package @subsection Using This Package @@ -90,9 +104,19 @@ only have to set the @code{LANG} environment variable to the appropriate @samp{@var{ll}_@var{CC}} combination. If you happen to have the @code{LC_ALL} or some other @code{LC_xxx} environment variables set, you should unset them before setting @code{LANG}, otherwise the setting of @code{LANG} will not -have the desired effect. Here @samp{@var{ll}} is an -@w{ISO 639} two-letter language code, and @samp{@var{CC}} is an -@w{ISO 3166} two-letter country code. For example, let's suppose that you +have the desired effect. Here + +@itemize +@item +@samp{@var{ll}} is an @w{ISO 639} two-letter language code. +For some languages, +a two-letter code does not exist, and a three-letter code is used instead. +@item +@samp{@var{CC}} is an @w{ISO 3166} two-letter code of a country or territory. +@end itemize + +@noindent +For example, let's suppose that you speak German and live in Germany. At the shell prompt, merely execute @w{@samp{setenv LANG de_DE}} (in @code{csh}), @w{@samp{export LANG; LANG=de_DE}} (in @code{sh}) or diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi index 6a644b127..fe7d71572 100644 --- a/gettext-tools/doc/gettext.texi +++ b/gettext-tools/doc/gettext.texi @@ -1255,8 +1255,18 @@ prompt, merely execute @subsection Locale Names A locale name usually has the form @samp{@var{ll}_@var{CC}}. Here -@samp{@var{ll}} is an @w{ISO 639} two-letter language code, and -@samp{@var{CC}} is an @w{ISO 3166} two-letter country code. For example, + +@itemize +@item +@samp{@var{ll}} is an @w{ISO 639} two-letter language code. +For some languages, +a two-letter code does not exist, and a three-letter code is used instead. +@item +@samp{@var{CC}} is an @w{ISO 3166} two-letter code of a country or territory. +@end itemize + +@noindent +For example, for German in Germany, @var{ll} is @code{de}, and @var{CC} is @code{DE}. You find a list of the language codes in appendix @ref{Language Codes} and a list of the country codes in appendix @ref{Country Codes}. @@ -3554,10 +3564,13 @@ forms: @itemize - @item @samp{@var{ll}}, an @w{ISO 639} two-letter language code (lowercase). +For some languages, +a two-letter code does not exist, and a three-letter code is used instead. See @ref{Language Codes} for the list of codes. @item @samp{@var{ll}_@var{CC}}, where @samp{@var{ll}} is an @w{ISO 639} two-letter +or three-letter language code (lowercase) and @samp{@var{CC}} is an @w{ISO 3166} two-letter country code (uppercase). The country code specification is not redundant: Some languages have dialects in different countries. For example, @@ -3567,7 +3580,9 @@ code serves to distinguish the dialects. See @ref{Language Codes} and @item @samp{@var{ll}_@var{CC}@@@var{variant}}, where @samp{@var{ll}} is an -@w{ISO 639} two-letter language code (lowercase), @samp{@var{CC}} is an +@w{ISO 639} two-letter +or three-letter +language code (lowercase), @samp{@var{CC}} is an @w{ISO 3166} two-letter country code (uppercase), and @samp{@var{variant}} is a variant designator. The variant designator (lowercase) can be a script designator, such as @samp{latin} or @samp{cyrillic}. @@ -9879,12 +9894,25 @@ produces programs totally unable to translate messages. @vindex LINGUAS@r{, environment variable} Internationalized packages have usually many @file{@var{ll}.po} -files. Unless -translations are disabled, all those available are installed together +or @file{@var{ll}_@var{CC}.po} files, where + +@itemize @bullet +@item +@var{ll} gives an @w{ISO 639} two-letter code identifying the language. +For some languages, +a two-letter code does not exist, and a three-letter code is used instead. +@item +The optional @var{CC} is an @w{ISO 3166} two-letter code of a country or +territory. +@end itemize + +@noindent +Unless translations are disabled, all those available are installed together with the package. However, the environment variable @code{LINGUAS} may be set, prior to configuration, to limit the installed set. -@code{LINGUAS} should then contain a space separated list of two-letter -codes, stating which languages are allowed. +@code{LINGUAS} should then contain a space separated list of locale names +(of the form @code{@var{ll}} or @code{@var{ll}_@var{CC}}), +stating which languages or language variants are allowed. GNU @code{gettext} uses *.its and *.loc files (@pxref{Preparing ITS Rules}) from other packages, provided they are installed in -- 2.47.3