Changeset 1111 for trunk

Timestamp:

Apr 19, 2010, 1:45:40 PM (13 years ago)

Author:

cmlenz

Message:

More i18n doc improvements.

Location:

trunk

Files:

• doc/i18n.txt (modified) (3 diffs)
• genshi/filters/i18n.py (modified) (1 diff)

trunk/doc/i18n.txt

@@ -223 +223 @@
              single message ineffective.
 
-``i18n:comment``
-----------------
-
-The ``i18n:comment`` directive can be used to supply a comment for the
-translator. For example, if a template snippet is not easily understood
-outside of its context, you can add a translator comment to help the
-translator understand in what context the message will be used:
-
-.. code-block:: genshi
-
-  <p i18n:msg="name" i18n:comment="Link to the relevant support site">
-    Please visit <a href="${site.url}">${site.name}</a> for help.
-  </p>
-
-This comment will be extracted together with the message itself, and will
-commonly be placed along the message in the message catalog, so that it is
-easily visible to the person doing the translation.
-
-This directive has no impact on how the template is rendered, and is ignored
-outside of the extraction process.
-
-
--------------
-Pluralization
--------------
+``i18n:choose``, ``i18n:singular``, ``i18n:plural``
+---------------------------------------------------
 
 Translatable strings that vary based on some number of objects, such as “You
@@ -253 +230 @@
 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
+two plural forms (one for ``n=1`` and an other for ``n<>1``), Welsh has five
 different plural forms, while Hungarian only has one.
 
@@ -264 +241 @@
 
 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
--------------------
+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``
+----------------
+
+The ``i18n:comment`` directive can be used to supply a comment for the
+translator. For example, if a template snippet is not easily understood
+outside of its context, you can add a translator comment to help the
+translator understand in what context the message will be used:
+
+.. code-block:: genshi
+
+  <p i18n:msg="name" i18n:comment="Link to the relevant support site">
+    Please visit <a href="${site.url}">${site.name}</a> for help.
+  </p>
+
+This comment will be extracted together with the message itself, and will
+commonly be placed along the message in the message catalog, so that it is
+easily visible to the person doing the translation.
+
+This directive has no impact on how the template is rendered, and is ignored
+outside of the extraction process.
 
 ``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

trunk/genshi/filters/i18n.py

@@ -294 +294 @@
     </html>
 
-    When used as a directive and not as an attribute:
+    When used as a element and not as an attribute:
 
     >>> tmpl = MarkupTemplate('''\