changeset 888:18dee397f8e1

More i18n doc improvements.
author cmlenz
date Mon, 19 Apr 2010 11:45:40 +0000
parents 148c17f49111
children e9827ccf94ee
files doc/i18n.txt genshi/filters/i18n.py
diffstat 2 files changed, 74 insertions(+), 33 deletions(-) [+]
line wrap: on
line diff
--- a/doc/i18n.txt
+++ b/doc/i18n.txt
@@ -222,6 +222,66 @@
              structure of the text changing, thus making translation as a
              single message ineffective.
 
+``i18n:choose``, ``i18n:singular``, ``i18n:plural``
+---------------------------------------------------
+
+Translatable strings that vary based on some number of objects, such as “You
+have 1 new message” or “You have 3 new messages”, present their own challenge,
+in particular when you consider that different languages have different rules
+for pluralization. For example, while English and most western languages have
+two plural forms (one for ``n=1`` and an other for ``n<>1``), Welsh has five
+different plural forms, while Hungarian only has one.
+
+The ``gettext`` framework has long supported this via the ``ngettext()``
+family of functions. You specify two default messages, one singular and one
+plural, and the number of items. The translations however may contain any
+number of plural forms for the message, depending on how many are commonly
+used in the language. ``ngettext`` will choose the correct plural form of the
+translated message based on the specified number of items.
+
+Genshi provides a variant of the ``i18n:msg`` directive described above that
+allows choosing the proper plural form based on the numeric value of a given
+variable. The pluralization support is implemented in a set of three
+directives that must be used together: ``i18n:choose``, ``i18n:singular``, and
+``i18n:plural``.
+
+The ``i18n:choose`` directive is used to set up the context of the message: it
+simply wraps the singular and plural variants.
+
+The value of this directive is split into two parts: the first is the
+*numeral*, a Python expression that evaluates to a number to determine which
+plural form should be chosen. The second part, separated by a semicolon, lists
+the parameter names. This part is equivalent to the value of the ``i18n:msg``
+directive.
+
+For example:
+
+.. code-block:: genshi
+
+  <p i18n:choose="len(messages); num">
+    <i18n:singular>You have <b>${len(messages)}</b> new message.</i18n:singular>
+    <i18n:plural>You have <b>${len(messages)}</b> new messages.</i18n:plural>
+  </p>
+
+All three directives can be used either as elements or attribute. So the above
+example could also be written as follows:
+
+.. code-block:: genshi
+
+  <i18n:choose numeral="len(messages)" params="num">
+    <p i18n:singular="">You have <b>${len(messages)}</b> new message.</p>
+    <p i18n:plural="">You have <b>${len(messages)}</b> new messages.</p>
+  </i18n:choose>
+
+When used as an element, the two parts of the ``i18n:choose`` value are split
+into two different attributes: ``numeral`` and ``params``. The
+``i18n:singular`` and ``i18n:plural`` directives do not require or support any
+value (or any extra attributes).
+
+--------------------
+Comments and Domains
+--------------------
+
 ``i18n:comment``
 ----------------
 
@@ -243,41 +303,22 @@
 This directive has no impact on how the template is rendered, and is ignored
 outside of the extraction process.
 
-
--------------
-Pluralization
--------------
-
-Translatable strings that vary based on some number of objects, such as “You
-have 1 new message” or “You have 3 new messages”, present their own challenge,
-in particular when you consider that different languages have different rules
-for pluralization. For example, while English and most western languages have
-two plural forms (one for ``n=1`` and one for ``n<>1``), Welsh has five
-different plural forms, while Hungarian only has one.
-
-The ``gettext`` framework has long supported this via the ``ngettext()``
-family of functions. You specify two default messages, one singular and one
-plural, and the number of items. The translations however may contain any
-number of plural forms for the message, depending on how many are commonly
-used in the language. ``ngettext`` will choose the correct plural form of the
-translated message based on the specified number of items.
-
-Genshi provides a variant of the ``i18n:msg`` directive described above that
-allows choosing the proper plural form based on some variable.
-
-``i18n:choose``, ``i18n:singular``, ``i18n:plural``
----------------------------------------------------
-
-TODO
-
--------------------
-Translation Domains
--------------------
-
 ``i18n:domain``
 ---------------
 
-TODO
+In larger projects, message catalogs are commonly split up into different
+*domains*. For example, you might have a core application domain, and then
+separate domains for extensions or libraries.
+
+Genshi provides a directive called ``i18n:domain`` that lets you choose the
+translation domain for a particular scope. For example:
+
+.. code-block:: genshi
+
+  <div i18n:domain="examples">
+    <p>Hello, world!</p>
+  </div>
+
 
 Extraction
 ==========
--- a/genshi/filters/i18n.py
+++ b/genshi/filters/i18n.py
@@ -293,7 +293,7 @@
       </div>
     </html>
 
-    When used as a directive and not as an attribute:
+    When used as a element and not as an attribute:
 
     >>> tmpl = MarkupTemplate('''\
         <html xmlns:i18n="http://genshi.edgewall.org/i18n">
Copyright (C) 2012-2017 Edgewall Software