From: Bruno Haible <bruno@clisp.org>
Date: Sat, 4 Oct 2008 11:26:27 +0000 (+0000)
Subject: Document the 'range:' flag syntax.
X-Git-Tag: v0.18~303
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0df8562f1aac3826cc72425383f3ee72bdfc012e;p=thirdparty%2Fgettext.git

Document the 'range:' flag syntax.
---

diff --git a/NEWS b/NEWS
index faa54a6ca..c59131ba3 100644
--- 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 1431263ca..40f142b64 100644
--- 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 9484e962e..5f4676196 100644
--- 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: