Mercurial > genshi > genshi-test
comparison doc/i18n.txt @ 888:18dee397f8e1
More i18n doc improvements.
| author | cmlenz |
|---|---|
| date | Mon, 19 Apr 2010 11:45:40 +0000 |
| parents | 148c17f49111 |
| children | e9827ccf94ee |
comparison
equal
deleted
inserted
replaced
| 887:148c17f49111 | 888:18dee397f8e1 |
|---|---|
| 220 nested directives. Directives commonly change the structure of | 220 nested directives. Directives commonly change the structure of |
| 221 the generated markup dynamically, which often would result in the | 221 the generated markup dynamically, which often would result in the |
| 222 structure of the text changing, thus making translation as a | 222 structure of the text changing, thus making translation as a |
| 223 single message ineffective. | 223 single message ineffective. |
| 224 | 224 |
| 225 ``i18n:comment`` | 225 ``i18n:choose``, ``i18n:singular``, ``i18n:plural`` |
| 226 ---------------- | 226 --------------------------------------------------- |
| 227 | |
| 228 The ``i18n:comment`` directive can be used to supply a comment for the | |
| 229 translator. For example, if a template snippet is not easily understood | |
| 230 outside of its context, you can add a translator comment to help the | |
| 231 translator understand in what context the message will be used: | |
| 232 | |
| 233 .. code-block:: genshi | |
| 234 | |
| 235 <p i18n:msg="name" i18n:comment="Link to the relevant support site"> | |
| 236 Please visit <a href="${site.url}">${site.name}</a> for help. | |
| 237 </p> | |
| 238 | |
| 239 This comment will be extracted together with the message itself, and will | |
| 240 commonly be placed along the message in the message catalog, so that it is | |
| 241 easily visible to the person doing the translation. | |
| 242 | |
| 243 This directive has no impact on how the template is rendered, and is ignored | |
| 244 outside of the extraction process. | |
| 245 | |
| 246 | |
| 247 ------------- | |
| 248 Pluralization | |
| 249 ------------- | |
| 250 | 227 |
| 251 Translatable strings that vary based on some number of objects, such as “You | 228 Translatable strings that vary based on some number of objects, such as “You |
| 252 have 1 new message” or “You have 3 new messages”, present their own challenge, | 229 have 1 new message” or “You have 3 new messages”, present their own challenge, |
| 253 in particular when you consider that different languages have different rules | 230 in particular when you consider that different languages have different rules |
| 254 for pluralization. For example, while English and most western languages have | 231 for pluralization. For example, while English and most western languages have |
| 255 two plural forms (one for ``n=1`` and one for ``n<>1``), Welsh has five | 232 two plural forms (one for ``n=1`` and an other for ``n<>1``), Welsh has five |
| 256 different plural forms, while Hungarian only has one. | 233 different plural forms, while Hungarian only has one. |
| 257 | 234 |
| 258 The ``gettext`` framework has long supported this via the ``ngettext()`` | 235 The ``gettext`` framework has long supported this via the ``ngettext()`` |
| 259 family of functions. You specify two default messages, one singular and one | 236 family of functions. You specify two default messages, one singular and one |
| 260 plural, and the number of items. The translations however may contain any | 237 plural, and the number of items. The translations however may contain any |
| 261 number of plural forms for the message, depending on how many are commonly | 238 number of plural forms for the message, depending on how many are commonly |
| 262 used in the language. ``ngettext`` will choose the correct plural form of the | 239 used in the language. ``ngettext`` will choose the correct plural form of the |
| 263 translated message based on the specified number of items. | 240 translated message based on the specified number of items. |
| 264 | 241 |
| 265 Genshi provides a variant of the ``i18n:msg`` directive described above that | 242 Genshi provides a variant of the ``i18n:msg`` directive described above that |
| 266 allows choosing the proper plural form based on some variable. | 243 allows choosing the proper plural form based on the numeric value of a given |
| 267 | 244 variable. The pluralization support is implemented in a set of three |
| 268 ``i18n:choose``, ``i18n:singular``, ``i18n:plural`` | 245 directives that must be used together: ``i18n:choose``, ``i18n:singular``, and |
| 269 --------------------------------------------------- | 246 ``i18n:plural``. |
| 270 | 247 |
| 271 TODO | 248 The ``i18n:choose`` directive is used to set up the context of the message: it |
| 272 | 249 simply wraps the singular and plural variants. |
| 273 ------------------- | 250 |
| 274 Translation Domains | 251 The value of this directive is split into two parts: the first is the |
| 275 ------------------- | 252 *numeral*, a Python expression that evaluates to a number to determine which |
| 253 plural form should be chosen. The second part, separated by a semicolon, lists | |
| 254 the parameter names. This part is equivalent to the value of the ``i18n:msg`` | |
| 255 directive. | |
| 256 | |
| 257 For example: | |
| 258 | |
| 259 .. code-block:: genshi | |
| 260 | |
| 261 <p i18n:choose="len(messages); num"> | |
| 262 <i18n:singular>You have <b>${len(messages)}</b> new message.</i18n:singular> | |
| 263 <i18n:plural>You have <b>${len(messages)}</b> new messages.</i18n:plural> | |
| 264 </p> | |
| 265 | |
| 266 All three directives can be used either as elements or attribute. So the above | |
| 267 example could also be written as follows: | |
| 268 | |
| 269 .. code-block:: genshi | |
| 270 | |
| 271 <i18n:choose numeral="len(messages)" params="num"> | |
| 272 <p i18n:singular="">You have <b>${len(messages)}</b> new message.</p> | |
| 273 <p i18n:plural="">You have <b>${len(messages)}</b> new messages.</p> | |
| 274 </i18n:choose> | |
| 275 | |
| 276 When used as an element, the two parts of the ``i18n:choose`` value are split | |
| 277 into two different attributes: ``numeral`` and ``params``. The | |
| 278 ``i18n:singular`` and ``i18n:plural`` directives do not require or support any | |
| 279 value (or any extra attributes). | |
| 280 | |
| 281 -------------------- | |
| 282 Comments and Domains | |
| 283 -------------------- | |
| 284 | |
| 285 ``i18n:comment`` | |
| 286 ---------------- | |
| 287 | |
| 288 The ``i18n:comment`` directive can be used to supply a comment for the | |
| 289 translator. For example, if a template snippet is not easily understood | |
| 290 outside of its context, you can add a translator comment to help the | |
| 291 translator understand in what context the message will be used: | |
| 292 | |
| 293 .. code-block:: genshi | |
| 294 | |
| 295 <p i18n:msg="name" i18n:comment="Link to the relevant support site"> | |
| 296 Please visit <a href="${site.url}">${site.name}</a> for help. | |
| 297 </p> | |
| 298 | |
| 299 This comment will be extracted together with the message itself, and will | |
| 300 commonly be placed along the message in the message catalog, so that it is | |
| 301 easily visible to the person doing the translation. | |
| 302 | |
| 303 This directive has no impact on how the template is rendered, and is ignored | |
| 304 outside of the extraction process. | |
| 276 | 305 |
| 277 ``i18n:domain`` | 306 ``i18n:domain`` |
| 278 --------------- | 307 --------------- |
| 279 | 308 |
| 280 TODO | 309 In larger projects, message catalogs are commonly split up into different |
| 310 *domains*. For example, you might have a core application domain, and then | |
| 311 separate domains for extensions or libraries. | |
| 312 | |
| 313 Genshi provides a directive called ``i18n:domain`` that lets you choose the | |
| 314 translation domain for a particular scope. For example: | |
| 315 | |
| 316 .. code-block:: genshi | |
| 317 | |
| 318 <div i18n:domain="examples"> | |
| 319 <p>Hello, world!</p> | |
| 320 </div> | |
| 321 | |
| 281 | 322 |
| 282 Extraction | 323 Extraction |
| 283 ========== | 324 ========== |
| 284 | 325 |
| 285 The ``Translator`` class provides a class method called ``extract``, which is | 326 The ``Translator`` class provides a class method called ``extract``, which is |