documentation/manual/en/module_specs/Zend_Translate-Plurals.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.translate.plurals">
   4     <title>Plural notations for Translation</title>
   5
   6     <para>
   7         As of Zend Framework 1.9, <classname>Zend_Translate</classname> is able to provide plural
   8         support. Professional translation will always have the need to use plurals as they are
   9         native in almost all languages.
  10     </para>
  11
  12     <para>
  13         So what are plurals? Generally spoken plurals are words which take into account numeric
  14         meanings. But as you may imagine each language has it's own definition of plurals.
  15         English, for example, supports one plural. We have a singular definition, for example
  16         "car", which means implicit one car, and we have the plural definition, "cars" which could
  17         mean more than one car but also zero cars. Other languages like Russian or Polish have
  18         more plurals and also the rules for plurals are different.
  19     </para>
  20
  21     <para>
  22         When you want to use plurals with <classname>Zend_Translate</classname> you must not need
  23         to know how the plurals are defined, only the translator must know as he does the
  24         translation. The only information you need to have is the language.
  25     </para>
  26
  27     <para>
  28         There are two ways for using plurals... the traditional one, which means that you use a own
  29         method, and a modern one, which allows you to do plural translations with the same method
  30         as normal translations.
  31     </para>
  32
  33     <sect2 id="zend.translate.plurals.traditional">
  34         <title>Traditional plural translations</title>
  35
  36         <para>
  37             People who worked with gettext in past will be more common with traditional plural
  38             translations. There is a own <methodname>plural()</methodname> method which can be
  39             used for plural translations.
  40         </para>
  41
  42         <example id="zend.translate.plurals.traditional.example1">
  43             <title>Example of traditional plural translations</title>
  44
  45             <para>
  46                 The <methodname>plural()</methodname> method accepts 4 parameters. The first
  47                 parameter is the singular messageId, the second is the plural messageId and the
  48                 third is the number or amount.
  49             </para>
  50
  51             <para>
  52                 The number will be used to detect the plural which has to be returned. A optional
  53                 fourth parameter can be used to give a locale which will be used to return the
  54                 translation.
  55             </para>
  56
  57             <programlisting language="php"><![CDATA[
  58 $translate = new Zend_Translate(
  59     array(
  60         'adapter' => 'gettext',
  61         'content' => '/path/to/german.mo',
  62         'locale'  => 'de'
  63     )
  64 );
  65 $translate->plural('Car', 'Cars', $number);
  66 ]]></programlisting>
  67         </example>
  68     </sect2>
  69
  70     <sect2 id="zend.translate.plurals.modern">
  71         <title>Modern plural translations</title>
  72
  73         <para>
  74             As traditional plural translations are restricted to source code using English plurals
  75             we added a new way for plural translations. It allows to use the same
  76             <methodname>translate()</methodname> for standard and for plural translations.
  77         </para>
  78
  79         <para>
  80             To use plural translations with <methodname>translate()</methodname> you need to give
  81             an array as messageId instead of an string. This array must have the original plural
  82             messageId's, then the amount and at last an optional locale when your given messageId's
  83             are not in English notation.
  84         </para>
  85
  86         <example id="zend.translate.plurals.modern.example1">
  87             <title>Example of modern plural translations</title>
  88
  89             <para>
  90                 When we want to translate the same plural definitions like in the previous our
  91                 example would have to be defined like below.
  92             </para>
  93
  94             <programlisting language="php"><![CDATA[
  95 $translate = new Zend_Translate(
  96     array(
  97         'adapter' => 'gettext',
  98         'content' => '/path/to/german.mo',
  99         'locale'  => 'de'
 100     )
 101 );
 102 $translate->translate(array('Car', 'Cars', $number));
 103 ]]></programlisting>
 104         </example>
 105
 106         <para>
 107             Using modern plural translations it is also possible to use any language as source
 108             for messageId's.
 109         </para>
 110
 111         <example id="zend.translate.plurals.modern.example2">
 112             <title>Example of modern plural translations using a different source language</title>
 113
 114             <para>
 115                 Let's expect we want to use Russian and let's also expect that the given
 116                 messageId's are Russian and not English.
 117             </para>
 118
 119             <programlisting language="php"><![CDATA[
 120 $translate = new Zend_Translate(
 121     array(
 122         'adapter' => 'gettext',
 123         'content' => '/path/to/german.mo',
 124         'locale'  => 'de'
 125     )
 126 );
 127 $translate->translate(
 128     array(
 129         'Car',
 130         'Cars first plural',
 131         'Cars second plural',
 132         $number,
 133         'ru'
 134     )
 135 );
 136 ]]></programlisting>
 137         </example>
 138
 139         <para>
 140             As you can see you can give more than just the one English plural. But you must give
 141             the source language in this case so <classname>Zend_Translate</classname> knows which
 142             plural rules it has to apply.
 143         </para>
 144
 145         <para>
 146             When you omit the plural language then English will be used per default and any
 147             additional plural definition will be ignored.
 148         </para>
 149     </sect2>
 150
 151     <sect2 id="zend.translate.plurals.source">
 152         <title>Plural source files</title>
 153
 154         <para>
 155             Not all source formats support plural forms. Look into this list for details:
 156         </para>
 157
 158         <table id="zend.translate.plurals.source.supportedadapters">
 159             <title>Plural support</title>
 160
 161             <tgroup cols="4">
 162                 <thead>
 163                     <row>
 164                         <entry>Adapter</entry>
 165                         <entry>Plurals supported</entry>
 166                     </row>
 167                 </thead>
 168
 169                 <tbody>
 170                     <row>
 171                         <entry>Array</entry>
 172                         <entry><emphasis>yes</emphasis></entry>
 173                     </row>
 174
 175                     <row>
 176                         <entry>Csv</entry>
 177                         <entry><emphasis>yes</emphasis></entry>
 178                     </row>
 179
 180                     <row>
 181                         <entry>Gettext</entry>
 182                         <entry><emphasis>yes</emphasis></entry>
 183                     </row>
 184
 185                     <row>
 186                         <entry>Ini</entry>
 187                         <entry><emphasis>no</emphasis></entry>
 188                     </row>
 189
 190                     <row>
 191                         <entry>Qt</entry>
 192                         <entry><emphasis>no</emphasis></entry>
 193                     </row>
 194
 195                     <row>
 196                         <entry>Tbx</entry>
 197                         <entry><emphasis>no</emphasis></entry>
 198                     </row>
 199
 200                     <row>
 201                         <entry>Tmx</entry>
 202                         <entry><emphasis>no</emphasis></entry>
 203                     </row>
 204
 205                     <row>
 206                         <entry>Xliff</entry>
 207                         <entry><emphasis>no</emphasis></entry>
 208                     </row>
 209
 210                     <row>
 211                         <entry>XmlTm</entry>
 212                         <entry><emphasis>no</emphasis></entry>
 213                     </row>
 214                 </tbody>
 215             </tgroup>
 216         </table>
 217
 218         <para>
 219             Below you can find examples of plural defined source files.
 220         </para>
 221
 222         <sect3 id="zend.translate.plurals.source.array">
 223             <title>Array source with plural definitions</title>
 224
 225             <para>
 226                 An array with plural definitions has to look like the following example.
 227             </para>
 228
 229             <programlisting language="php"><![CDATA[
 230 array(
 231     'plural_0' => array(
 232         'plural_0 (ru)',
 233         'plural_1 (ru)',
 234         'plural_2 (ru)',
 235         'plural_3 (ru)'
 236     ),
 237     'plural_1' => ''
 238 );
 239 ]]></programlisting>
 240
 241             <para>
 242                 In the above example <code>plural_0</code> and <code>plural_1</code> are the
 243                 plural definitions from the source code. And the array at <code>plural_0</code>
 244                 has all translated plural forms available. Take a look at the following example
 245                 with real content and translation from English source to German.
 246             </para>
 247
 248             <programlisting language="php"><![CDATA[
 249 array(
 250     'Car' => array(
 251         'Auto',
 252         'Autos'
 253     ),
 254     'Cars' => ''
 255 );
 256 ]]></programlisting>
 257
 258             <para>
 259                 When your translated language supports more plural forms then simply add them to
 260                 the array below the first plural form. When your source language supports more
 261                 plural forms, than simply add a new empty translation.
 262             </para>
 263         </sect3>
 264
 265         <sect3 id="zend.translate.plurals.source.csv">
 266             <title>Csv source with plural definitions</title>
 267
 268             <para>
 269                 A csv file with plural definitions has to look like the following example.
 270             </para>
 271
 272             <programlisting language="php"><![CDATA[
 273 "plural_0";"plural_0 (ru)";"plural_1 (ru)";"plural_2 (ru)";"plural_3 (ru)"
 274 "plural_1";
 275 ]]></programlisting>
 276
 277             <para>
 278                 All translated plural forms have to be added after the first plural of the source
 279                 language. And all further plural forms of the source language have to be added
 280                 below but without translation. Note that you must add a delimiter to empty
 281                 source plurals.
 282             </para>
 283         </sect3>
 284
 285         <sect3 id="zend.translate.plurals.source.gettext">
 286             <title>Gettext source with plural definitions</title>
 287
 288             <para>
 289                 Gettext sources support plural forms out of the box. There is no need for adoption
 290                 as the <filename>*.mo</filename> file will contain all necessary data.
 291             </para>
 292
 293             <note>
 294                 <para>
 295                     Note that gettext does not support the usage of source languages which are not
 296                     using english plural forms. When you plan to use a source language which
 297                     supports other plural forms like russian for example, then you can not use
 298                     gettext sources.
 299                 </para>
 300             </note>
 301         </sect3>
 302     </sect2>
 303
 304     <sect2 id="zend.translate.plurals.customrules">
 305         <title>Custom plural rules</title>
 306
 307         <para>
 308             In rare cases it could be useful to be able to define own plural rules. See Chinese for
 309             example. This language defines two plural rules. Per default it does not use plurals.
 310             But in rare cases it uses a rule like <emphasis>(number == 1) ? 0 : 1</emphasis>.
 311         </para>
 312
 313         <para>
 314             Also when you want to use a language which has no known plural rules, and would want to
 315             define your own rules.
 316         </para>
 317
 318         <para>
 319             This can be done by using <methodname>Zend_Translate_Plural::setRule()</methodname>.
 320             The method expects two parameters which must be given. A rule, which is simply a
 321             callback to a self defined method. And a locale for which the rule will be used.
 322         </para>
 323
 324         <para>
 325             Your rule could look like this:
 326         </para>
 327
 328         <programlisting language="php"><![CDATA[
 329 public function MyRule($number) {
 330     return ($number == 10) ? 0 : 1;
 331 }
 332 ]]></programlisting>
 333
 334         <para>
 335             As you see, your rule must accept one parameter. It is the number which you will use to
 336             return which plural the translation has to use. In our example we defined that when we
 337             get a '10' the plural definition 0 has to be used, in all other cases we're using 1.
 338         </para>
 339
 340         <para>
 341             Your rules can be as simple or as complicated as you want. You must only return an
 342             integer value. The plural definition 0 stands for singular translation, and 1 stands for
 343             the first plural rule.
 344         </para>
 345
 346         <para>
 347             To activate your rule, and to link it to the wished locale, you have to call it like
 348             this:
 349         </para>
 350
 351         <programlisting language="php"><![CDATA[
 352 Zend_Translate_Plural::setPlural('MyPlural', 'zh');
 353 ]]></programlisting>
 354
 355         <para>
 356             Now we linked our plural definition to the Chinese language.
 357         </para>
 358
 359         <para>
 360             You can define one plural rule for every language. But you should be aware that you set
 361             the plural rules before you are doing translations.
 362         </para>
 363
 364         <note>
 365             <title>Define custom plurals only when needed</title>
 366
 367             <para>
 368                 <classname>Zend_Translate</classname> defines plurals for most known languages.
 369                 You should not define own plurals when you are not in need. The default rules work
 370                 most of time.
 371             </para>
 372         </note>
 373     </sect2>
 374 </sect1>
 375 <!--
 376 vim:se ts=4 sw=4 et:
 377 -->