Introduce a new header entry field 'Language'.

5 files changed, 80 insertions, 0 deletions

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index e4cb4f6..3f2421f 100644
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,10 @@
+2007-12-24  Bruno Haible  <bruno@clisp.org>
+
+	* gettext.texi (Header Entry): Document the 'Language' field.
+	* msgcat.texi: Document the --lang option.
+	* msgen.texi: Likewise.
+	* msgmerge.texi: Likewise.
+
 2007-12-02  Bruno Haible  <bruno@clisp.org>
 
 	* gettext.texi (Plural Forms): Put Turkish under nplurals=2.
diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 3905ff6..0c3a2dd 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -2913,6 +2913,58 @@ list.  The up-to-date list of teams can be found at the Free Translation
 Project's homepage, @uref{http://translationproject.org/}, in the "Teams"
 area.
 
+@item Language
+@c The purpose of this field is to make it possible to automatically
+@c - convert PO files to translation memory,
+@c - initialize a spell checker based on the PO file,
+@c - perform language specific checks.
+Fill in the language code of the language.  This can be in one of three
+forms:
+
+@itemize -
+@item
+@samp{@var{ll}}, an @w{ISO 639} two-letter language code (lowercase).
+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
+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,
+@samp{de_AT} is used for Austria, and @samp{pt_BR} for Brazil.  The country
+code serves to distinguish the dialects. See @ref{Language Codes} and
+@ref{Country Codes} for the lists of codes.
+
+@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 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}.
+@end itemize
+
+The naming convention @samp{@var{ll}_@var{CC}} is also the way locales are
+named on systems based on GNU libc.  But there are three important differences:
+
+@itemize @bullet
+@item
+In this PO file field, but not in locale names, @samp{@var{ll}_@var{CC}}
+combinations denoting a language's main dialect are abbreviated as
+@samp{@var{ll}}.  For example, @samp{de} is equivalent to @samp{de_DE}
+(German as spoken in Germany), and @samp{pt} to @samp{pt_PT} (Portuguese as
+spoken in Portugal) in this context.
+
+@item
+In this PO file field, suffixes like @samp{.@var{encoding}} are not used.
+
+@item
+In this PO file field, variant designators that are not relevant to message
+translation, such as @samp{@@euro}, are not used.
+@end itemize
+
+So, if your locale name is @samp{de_DE.UTF-8}, the language specification in
+PO files is just @samp{de}.
+
 @item Content-Type
 @cindex encoding of PO files
 @cindex charset of PO files
diff --git a/gettext-tools/doc/msgcat.texi b/gettext-tools/doc/msgcat.texi
index 20e6b53..07e07ad 100644
--- a/gettext-tools/doc/msgcat.texi
+++ b/gettext-tools/doc/msgcat.texi
@@ -115,6 +115,12 @@ Specify encoding for output.
 Use first available translation for each message.  Don't merge several
 translations into one.
 
+@item --lang=@var{catalogname}
+@opindex --lang@r{, @code{msgcat} option}
+Specify the @samp{Language} field to be used in the header entry.  See
+@ref{Header Entry} for the meaning of this field.  Note: The
+@samp{Language-Team} and @samp{Plural-Forms} fields are left unchanged.
+
 @item --color
 @itemx --color=@var{when}
 @opindex --color@r{, @code{msgcat} option}
diff --git a/gettext-tools/doc/msgen.texi b/gettext-tools/doc/msgen.texi
index 7923cd7..6686c83 100644
--- a/gettext-tools/doc/msgen.texi
+++ b/gettext-tools/doc/msgen.texi
@@ -68,6 +68,13 @@ Assume the input file is a NeXTstep/GNUstep localized resource file in
 @c --no-escape and --escape omitted on purpose.  They are not useful.
 
 @table @samp
+@item --lang=@var{catalogname}
+@opindex --lang@r{, @code{msgcat} option}
+Specify the @samp{Language} field to be used in the header entry.  See
+@ref{Header Entry} for the meaning of this field.  Note: The
+@samp{Language-Team} and @samp{Plural-Forms} fields are not set by this
+option.
+
 @item --force-po
 @opindex --force-po@r{, @code{msgen} option}
 Always write an output file even if it contains no message.
diff --git a/gettext-tools/doc/msgmerge.texi b/gettext-tools/doc/msgmerge.texi
index 874ecae..e924d4f 100644
--- a/gettext-tools/doc/msgmerge.texi
+++ b/gettext-tools/doc/msgmerge.texi
@@ -155,6 +155,14 @@ Assume the input files are NeXTstep/GNUstep localized resource files in
 @c --no-escape and --escape omitted on purpose.  They are not useful.
 
 @table @samp
+@item --lang=@var{catalogname}
+@opindex --lang@r{, @code{msgcat} option}
+Specify the @samp{Language} field to be used in the header entry.  See
+@ref{Header Entry} for the meaning of this field.  Note: The
+@samp{Language-Team} and @samp{Plural-Forms} fields are left unchanged.
+If this option is not specified, the @samp{Language} field is inferred, as
+best as possible, from the @samp{Language-Team} field.
+
 @item --force-po
 @opindex --force-po@r{, @code{msgmerge} option}
 Always write an output file even if it contains no message.