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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21661 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.translate.plurals">
   5     <title>Notation des pluriels pour Translation</title>
   6
   7     <para>
   8         Depuis Zend Framework 1.9, <classname>Zend_Translate</classname> gère les pluriels.
   9         Comme presque tous les langages utilisent des pluriels, la traduction doit gérer celà.
  10     </para>
  11
  12     <para>
  13         Qu'est ce qu'un pluriel? En général, les pluriels sont des mots qui prennent en compte une contenance
  14         numérique. Cependant chaque langue a sa propre définition du pluriel. En anglais, par exemple, un seul pluriel
  15         par mot existe donc par exemple "car" donnera "cars" au pluriel. D'autres langages comme le russe
  16         proposent plusieurs pluriels et plusieurs règles de pluriels.
  17     </para>
  18
  19     <para>
  20         Lorsque vous voulez utiliser les pluriels avec <classname>Zend_Translate</classname> vous n'avez pas besoin
  21         de savoir comment ceux-ci sont définis, seul le traducteur sait. Vous devez juste savoir la langue dans laquelle
  22         traduire.
  23     </para>
  24
  25     <para>
  26         Il existe 2 manières d'utiliser les pluriels. La traditionnelle qui vous fait utiliser une méthode,
  27         la moderne, qui permet d'utiliser la même méthode pour plusieurs pluriels.
  28     </para>
  29
  30     <sect2 id="zend.translate.plurals.traditional">
  31         <title>Méthode traditionnelle</title>
  32
  33         <para>
  34             Les personnes connaissant gettext vont reconnaitre cette méthodologie. Il existe une seule méthode
  35             <methodname>plural()</methodname> qui rend le pluriel.
  36         </para>
  37
  38         <example id="zend.translate.plurals.traditional.example1">
  39             <title>Exemple avec la méthode traditionnelle</title>
  40
  41             <para>
  42                 La méthode <methodname>plural()</methodname> accepte 4 paramètres. Le premier est le messageId au singulier, le second
  43                 est le messageId du pluriel, le troisième est le nombre ou la quantité.
  44             </para>
  45
  46             <para>
  47                 La quantité va être utilisée pour détecter le pluriel à retourner. Le 4ème paramètre optionnel peut être utilisé pour
  48                 spécifier une locale concernant la traduction.
  49             </para>
  50
  51             <programlisting language="php"><![CDATA[
  52 $translate = new Zend_Translate(
  53     array(
  54         'adapter' => 'gettext',
  55         'content' => '/path/to/german.mo',
  56         'locale'  => 'de'
  57     )
  58 );
  59 $translate->plural('Car', 'Cars', $number);
  60 ]]></programlisting>
  61         </example>
  62     </sect2>
  63
  64     <sect2 id="zend.translate.plurals.modern">
  65         <title>Méthode moderne de traduction du pluriel</title>
  66
  67         <para>
  68             Utilisez la méthode <methodname>translate()</methodname> pour la traduction des pluriels.
  69         </para>
  70
  71         <para>
  72             Pour utiliser la traduction de pluriels avec <methodname>translate()</methodname>, passez un tableau
  73             comme messageId plutôt qu'une chaine. Ce tableau doit contenir le messageId original, celui du pluriel,
  74             une quantité et optionnellement une locale.
  75         </para>
  76
  77         <example id="zend.translate.plurals.modern.example1">
  78             <title>Exemple de la méthode moderne de traduction du pluriel</title>
  79
  80             <para>
  81                 Pour traduire un pluriel avec la méthode moderne, agissez comme suit:
  82             </para>
  83
  84             <programlisting language="php"><![CDATA[
  85 $translate = new Zend_Translate(
  86     array(
  87         'adapter' => 'gettext',
  88         'content' => '/path/to/german.mo',
  89         'locale'  => 'de'
  90     )
  91 );
  92 $translate->translate(array('Car', 'Cars', $number));
  93 ]]></programlisting>
  94         </example>
  95
  96         <para>
  97             Avec cette méthode, vous pouvez utiliser n'importe quelle langue comme messageId original.
  98         </para>
  99
 100         <example id="zend.translate.plurals.modern.example2">
 101             <title>Exemple de la méthode moderne de traduction du pluriel utilisant un langage source différent</title>
 102
 103             <para>
 104                 Imaginons que nous voulions utiliser du russe et que le messageId est russe et non anglais.
 105             </para>
 106
 107             <programlisting language="php"><![CDATA[
 108 $translate = new Zend_Translate(
 109     array(
 110         'adapter' => 'gettext',
 111         'content' => '/path/to/german.mo',
 112         'locale'  => 'de'
 113     )
 114 );
 115 $translate->translate(array('Car',
 116                             'Cars first plural',
 117                             'Cars second plural',
 118                             $number,
 119                             'ru'));
 120 ]]></programlisting>
 121         </example>
 122
 123         <para>
 124             Comme vous le voyez, vous pouvez donner plus d'un pluriel, mais il faut alors spécifier la langue pour que
 125             <classname>Zend_Translate</classname> puisse trouver les règles de pluriel appropriées.
 126         </para>
 127
 128         <para>
 129             Si vous omettez la langue, l'anglais sera utilisé et tout pluriel superflu sera ignoré.
 130         </para>
 131     </sect2>
 132
 133     <sect2 id="zend.translate.plurals.source">
 134         <title>Fichiers sources de pluriels</title>
 135
 136         <para>
 137             Toutes les sources ne supportent pas les pluriels. Voyez la liste ci-après pour les détails:
 138         </para>
 139
 140         <table id="zend.translate.plurals.source.supportedadapters">
 141             <title>Support du pluriel</title>
 142             <tgroup cols="4">
 143                 <thead>
 144                     <row>
 145                         <entry>Adaptateur</entry>
 146                         <entry>Pluriels supportés</entry>
 147                     </row>
 148                 </thead>
 149                 <tbody>
 150                     <row>
 151                         <entry>Array</entry>
 152                         <entry><emphasis>oui</emphasis></entry>
 153                     </row>
 154                     <row>
 155                         <entry>Csv</entry>
 156                         <entry><emphasis>oui</emphasis></entry>
 157                     </row>
 158                     <row>
 159                         <entry>Gettext</entry>
 160                         <entry><emphasis>oui</emphasis></entry>
 161                     </row>
 162                     <row>
 163                         <entry>Ini</entry>
 164                         <entry><emphasis>non</emphasis></entry>
 165                     </row>
 166                     <row>
 167                         <entry>Qt</entry>
 168                         <entry><emphasis>non</emphasis></entry>
 169                     </row>
 170                     <row>
 171                         <entry>Tbx</entry>
 172                         <entry><emphasis>non</emphasis></entry>
 173                     </row>
 174                     <row>
 175                         <entry>Tmx</entry>
 176                         <entry><emphasis>non</emphasis></entry>
 177                     </row>
 178                     <row>
 179                         <entry>Xliff</entry>
 180                         <entry><emphasis>non</emphasis></entry>
 181                     </row>
 182                     <row>
 183                         <entry>XmlTm</entry>
 184                         <entry><emphasis>non</emphasis></entry>
 185                     </row>
 186                 </tbody>
 187             </tgroup>
 188         </table>
 189
 190         <para>
 191             Lisez la suite pour des exemples.
 192         </para>
 193
 194         <sect3 id="zend.translate.plurals.source.array">
 195             <title>Source tableau contenant des pluriels</title>
 196
 197             <para>
 198                 Un tableau de traduction contenant des pluriels devrait ressembler à ceci:
 199             </para>
 200
 201             <programlisting language="php"><![CDATA[
 202 array(
 203     'plural_0' => array(
 204         'plural_0 (ru)',
 205         'plural_1 (ru)',
 206         'plural_2 (ru)',
 207         'plural_3 (ru)'
 208     ),
 209     'plural_1' => ''
 210 );
 211 ]]></programlisting>
 212
 213             <para>
 214                 Dans cet exemple, <code>plural_0</code> et <code>plural_1</code> sont les définitions du pluriel
 215                 depuis le code source. Le tableau à l'index <code>plural_0</code> possède les pluriels traduits.
 216                 Regardez l'exemple suivant avec du vrai contenu et une traduction anglais - allemand.
 217             </para>
 218
 219             <programlisting language="php"><![CDATA[
 220 array(
 221     'Car' => array(
 222         'Auto',
 223         'Autos'
 224     ),
 225     'Cars' => ''
 226 );
 227 ]]></programlisting>
 228
 229             <para>
 230                 Si votre langue supporte plusieurs pluriels, ajoutez les simplement dans le tableau à la
 231                 suite du premier pluriel.
 232             </para>
 233         </sect3>
 234
 235         <sect3 id="zend.translate.plurals.source.csv">
 236             <title>Csv et pluriels</title>
 237
 238             <para>
 239                 Un fichier csv gérant des pluriels ressemble à ceci:
 240             </para>
 241
 242             <programlisting language="php"><![CDATA[
 243 "plural_0";"plural_0 (ru)";"plural_1 (ru)";"plural_2 (ru)";"plural_3 (ru)"
 244 "plural_1";
 245 ]]></programlisting>
 246
 247             <para>
 248                 Toutes les traductions des pluriels doivent être ajoutées après le premier pluriel et
 249                 tout les pluriels suivants doivent être ajoutés après, mais sans traduction.
 250                 Notez que le délimiteur est nécessaire pour les pluriels vides.
 251             </para>
 252         </sect3>
 253
 254         <sect3 id="zend.translate.plurals.source.gettext">
 255             <title>Gettext et pluriels</title>
 256
 257             <para>
 258                 Gettext supporte nativement les pluriels, les fichiers
 259                 <filename>*.mo</filename> contiennent tout ce qui est nécessaire.
 260             </para>
 261
 262             <note>
 263                 <para>
 264                     Notez que gettext ne gère pas les langues à plusieurs pluriels, utilisez
 265                     un autre adaptateur dans ce cas là.
 266                 </para>
 267             </note>
 268         </sect3>
 269     </sect2>
 270
 271     <sect2 id="zend.translate.plurals.customrules">
 272         <title>Custom plural rules</title>
 273
 274         <para>
 275             In rare cases it could be useful to be able to define own plural rules. See chinese for
 276             example. This language defines two plural rules. Per default it does not use plurals.
 277             But in rare cases it uses a rule like <emphasis>(number == 1) ? 0 : 1</emphasis>.
 278         </para>
 279
 280         <para>
 281             Also when you want to use a language which has no known plural rules, and would want to
 282             define your own rules.
 283         </para>
 284
 285         <para>
 286             This can be done by using <methodname>Zend_Translate_Plural::setRule()</methodname>.
 287             The method expects two parameters which must be given. A rule, which is simply a
 288             callback to a self defined method. And a locale for which the rule will be used.
 289         </para>
 290
 291         <para>
 292             Your rule could look like this:
 293         </para>
 294
 295         <programlisting language="php"><![CDATA[
 296 public function MyRule($number) {
 297     return ($number == 10) ? 0 : 1;
 298 }
 299 ]]></programlisting>
 300
 301         <para>
 302             As you see, your rule must accept one parameter. It is the number which you will use to
 303             return which plural the translation has to use. In our example we defined that when we
 304             get a '10' the plural definition 0 has to be used, in all other cases we're using 1.
 305         </para>
 306
 307         <para>
 308             Your rules can be as simple or as complicated as you want. You must only return an
 309             integer value. The plural definition 0 stands for singular translation, and 1 stands for
 310             the first plural rule.
 311         </para>
 312
 313         <para>
 314             To activate your rule, and to link it to the wished locale, you have to call it like
 315             this:
 316         </para>
 317
 318         <programlisting language="php"><![CDATA[
 319 Zend_Translate_Plural::setPlural('MyPlural', 'zh');
 320 ]]></programlisting>
 321
 322         <para>
 323             Now we linked our plural definition to the chinese language.
 324         </para>
 325
 326         <para>
 327             You can define one plural rule for every language. But you should be aware that you set
 328             the plural rules before you are doing translations.
 329         </para>
 330
 331         <note>
 332             <title>Define custom plurals only when needed</title>
 333
 334             <para>
 335                 <classname>Zend_Translate</classname> defines plurals for most known languages.
 336                 You should not define own plurals when you are not in need. The default rules work
 337                 most of time.
 338             </para>
 339         </note>
 340     </sect2>
 341 </sect1>
 342 <!--
 343 vim:se ts=4 sw=4 et:
 344 -->