Document the 'range:' flag syntax.

diff --git a/NEWS b/NEWS
index faa54a6ca4bc3282eb2f176e6c44a143f7adde9a..c59131ba37c90d0e9c6dd07d226d82a8c76e861d 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,14 @@ Version 0.18 - January 2008
   this field.  Additionally, msgmerge fills in this new field by looking at
   the 'Language-Team' field (if the --lang option is not given).
 
+* xgettext and PO file format:
+  For messages with plural forms, programmers can inform the translators
+  about the range of possible values of the numeric argument, like this:
+    /* xgettext: range: 0..15 */
+  This information 'range: 0..15' is stored in the PO file as a flag attached
+  to the message.  Translators can produce better translations when they know
+  that the numeric argument is small.
+
 * msgmerge is up to 10 times faster when the PO and POT files are large.
   This speedup was contributed by Ralf Wildenhues.
 

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 1431263cae8b3c7f54a375d700d332808504cf6b..40f142b64d4e00e547b364c8746fc19cb77dad71 100644 (file)
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,8 @@
+2008-10-04  Bruno Haible  <bruno@clisp.org>
+
+       * gettext.texi (PO Files): Mention the 'range:' flag syntax.
+       (Plural forms): Document how to produce 'range:' flags.
+
 2008-09-27  Bruno Haible  <bruno@clisp.org>
 
        * ISO_639-2: Update entry about Tamashek.

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 9484e962e4b2ee55abdb1b7a89e1b7d8f5bb842f..5f46761967954c7769d91734a422b1af0c97bd4f 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -1670,6 +1670,18 @@ msgstr[1] "s'han trobat %d errors fatals"
 Here also, a @code{msgctxt} context can be specified before @code{msgid},
 like above.
 
+Here, additional kinds of flags can be used:
+
+@table @code
+@item range:
+@kwindex range:@r{ flag}
+This flag is followed by a range of non-negative numbers, using the syntax
+@code{range: @var{minimum-value}..@var{maximum-value}}.  It designates the
+possible values that the numeric parameter of the message can take.  In some
+languages, translators may produce slightly better translations if they know
+that the value can only take on values between 0 and 10, for example.
+@end table
+
 The @var{previous-untranslated-string} is optionally inserted by the
 @code{msgmerge} program, at the same time when it marks a message fuzzy.
 It helps the translator to see which changes were done by the developers
@@ -6072,6 +6084,19 @@ printf (ngettext ("%$2d file removed from directory %$1s",
 @noindent
 See @ref{c-format} for details about this argument reordering syntax.
 
+When you know that the value of @code{n} is within a given range, you can
+specify it as a comment directed to the @code{xgettext} tool.  This
+information may help translators to use more adequate translations.  Like
+this:
+
+@smallexample
+if (days > 7 && days < 14)
+  /* xgettext: range: 1..6 */
+  printf (ngettext ("one week and one day", "one week and %d days",
+                    days - 7),
+          days - 7);
+@end smallexample
+
 It is also possible to use this function when the strings don't contain a
 cardinal number: