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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21829 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.translate.using">
   5     <title>Utiliser les adaptateurs de traduction</title>
   6
   7     <para>L'étape suivante est d'utiliser l'adaptateur dans votre code.</para>
   8
   9     <example id="zend.translate.using.example1">
  10         <title>Exemple de code PHP monolingue</title>
  11
  12         <programlisting language="php"><![CDATA[
  13 print "Exemple\n";
  14 print "=======\n";
  15 print "Ceci la ligne une\n";
  16 print "Aujourd'hui nous sommes le " . date("d/m/Y") . "\n";
  17 print "\n";
  18 print "Correction de la langue ceci est la ligne deux\n";
  19 ]]></programlisting>
  20     </example>
  21
  22     <para>
  23         L'exemple ci-dessus montre l'affichage sans le support de traduction. Vous écrivez
  24         probablement votre code dans votre langue maternelle. Généralement vous devez traduire non
  25         seulement l'affichage, mais également les messages d'erreur et les messages de log.
  26     </para>
  27
  28     <para>
  29         La prochaine étape est d'inclure <classname>Zend_Translate</classname> dans votre code
  30         existant. Naturellement il est beaucoup plus facile si vous écrivez dès le début votre code
  31         en utilisant <classname>Zend_Translate</classname> au lieu de modifier votre code
  32         après.
  33     </para>
  34
  35     <example id="zend.translate.using.example2">
  36         <title>Exemple de code PHP multilingue</title>
  37
  38         <programlisting language="php"><![CDATA[
  39 $translate = new Zend_Translate(
  40     array(
  41         'adapter' => 'gettext',
  42         'content' => '/my/path/source-de.mo',
  43         'locale'  => 'de'
  44     )
  45 );
  46 $translate->addTranslation(
  47     array(
  48         'content' => '/path/to/translation/fr-source.mo',
  49         'locale'  => 'fr'
  50     )
  51 );
  52
  53 print $translate->_("Exemple")."\n";
  54 print "=======\n";
  55 print $translate->_("Ceci la ligne une")."\n";
  56 printf($translate->_("Aujourd'hui nous sommes le %1\$s") . "\n",
  57                      date("d/m/Y"));
  58 print "\n";
  59
  60 $translate->setLocale('fr');
  61 print $translate->_("Correction de la langue ceci est la ligne deux") . "\n";
  62 ]]></programlisting>
  63     </example>
  64
  65     <para>
  66         Maintenant regardons plus attentivement ce qui a été fait et la façon d'intégrer
  67         <classname>Zend_Translate</classname> dans votre code.
  68     </para>
  69
  70     <para>
  71         Créer un nouvel objet de traduction et définir l'adaptateur de base : <programlisting
  72         role="php"><![CDATA[
  73 $translate = new Zend_Translate(
  74     array(
  75         'adapter' => 'gettext',
  76         'content' => '/path/to/translation/source-de.mo',
  77         'locale'  => 'de'
  78     )
  79 );
  80 ]]></programlisting> Dans cet exemple nous avons décidé d'utiliser <emphasis>l'adaptateur
  81         Gettext</emphasis>. Nous plaçons notre fichier <code>source-de.mo</code> dans le dossier
  82         <code>/chemin/vers</code>. Le fichier gettext inclura la traduction allemande. Et nous avons
  83         également ajouté un autre fichier de langue pour le français.
  84     </para>
  85
  86     <para>
  87         L'étape suivante est d'envelopper toutes les chaînes qui doivent être traduites.
  88         L'approche la plus simple est d'avoir seulement des chaînes simples ou des phrases comme
  89         celle-ci : <programlisting language="php"><![CDATA[
  90 print $translate->_("Exemple")."\n";
  91 print "=======\n";
  92 print $translate->_("Ceci la ligne une")."\n";
  93 ]]></programlisting>Certaines chaînes ne sont pas nécessairement traduites. La ligne séparatrice
  94         est toujours la même, même dans d'autres langues.
  95     </para>
  96
  97     <para>
  98         Avoir des valeurs de données intégrées dans une chaîne de traduction est également
  99         supporté par l'utilisation des paramètres inclus. <programlisting language="php"><![CDATA[
 100 printf($translate->_("Aujourd'hui nous sommes le %1\$s") . "\n",
 101                      date("d/m/Y"));
 102 ]]></programlisting> Au lieu de <methodname>print()</methodname>, utiliser la fonction <methodname>printf()</methodname>
 103         et remplacer tous les paramètres avec des éléments de type <code>%1\$s</code>. Le premier
 104         est <code>%1\$s</code>, le second <code>%2\$s</code>, et ainsi de suite. De cette façon une
 105         traduction peut être faite sans savoir la valeur exacte. Dans notre exemple, la date est
 106         toujours le jour actuel, mais la chaîne peut être traduite sans connaissance du jour
 107         actuel.
 108     </para>
 109
 110     <para>
 111         Chaque chaîne est identifiée dans le stockage de traduction par un identificateur de
 112         message. Vous pouvez employer l'identificateur de message au lieu des chaînes dans votre
 113         code, comme ceci : <programlisting language="php"><![CDATA[
 114 print $translate->_(1)."\n";
 115 print "=======\n";
 116 print $translate->_(2)."\n";
 117 ]]></programlisting> faire ceci a plusieurs inconvénients :
 118  </para>
 119
 120     <para>
 121         Vous ne pouvez pas voir ce que votre code devrait afficher juste en lisant
 122         celui-ci.
 123     </para>
 124
 125     <para>
 126         En outre vous obtiendrez des problèmes si certaines chaînes ne sont pas traduites.
 127         Vous devez toujours imaginer comment la traduction fonctionne. Premièrement
 128         <classname>Zend_Translate</classname> vérifie si la langue choisie a une traduction pour
 129         l'identificateur de message ou la chaîne fournie. Si aucune chaîne de traduction n'a été
 130         trouvée, elle se reporte sur la langue suivante comme définie dans
 131         <classname>Zend_Locale</classname>. Ainsi le "<emphasis>de_AT</emphasis>" devient seulement
 132         "<emphasis>de</emphasis>". Si aucune traduction n'est trouvée pour le
 133         "<emphasis>de</emphasis>", alors le message original est retourné. De cette façon vous avez
 134         toujours un affichage, au cas où la traduction de message n'existerait pas dans votre
 135         stockage des messages. <classname>Zend_Translate</classname> ne lève jamais d'erreur ou
 136         d'exception en traduisant les chaînes.
 137     </para>
 138
 139     <sect2 id="zend.translate.using.structure">
 140         <title>Structures des sources de traduction</title>
 141
 142         <para>
 143             L'étape suivante est la création des sources de traduction pour les multiples
 144             langues vers lesquelles vous traduisez. Chaque adaptateur est créé de sa propre manière
 145             comme décrit ici. Mais il y a quelques dispositifs généraux qui sont valables pour tous
 146             les adaptateurs.
 147         </para>
 148
 149         <para>
 150             Vous devrez savoir où stocker vos fichiers sources de traduction. Avec
 151             <classname>Zend_Translate</classname> vous n'avez aucune restriction. Les structures
 152             suivantes sont préférables :
 153         </para>
 154
 155         <itemizedlist>
 156             <listitem>
 157                 <para>Structure de source unique</para>
 158
 159                 <programlisting><![CDATA[
 160 /application
 161 /languages
 162   lang.en
 163   lang.de
 164 /library
 165 ]]></programlisting>
 166
 167                 <para>
 168                     Positif : Tous les fichiers sources pour chacune des langues peuvent être
 169                     trouvés dans un dossier. Aucun fractionnement des fichiers.
 170                 </para>
 171             </listitem>
 172
 173             <listitem>
 174                 <para>Source structurée par langue</para>
 175
 176                 <programlisting><![CDATA[
 177 /application
 178 /languages
 179   /en
 180     lang.en
 181     other.en
 182   /de
 183     lang.de
 184     other.de
 185 /library
 186 ]]></programlisting>
 187
 188                 <para>
 189                     Positif : chaque langue est située dans un dossier. La traduction est
 190                     facilitée car un seul dossier doit être traduit par une équipe de langue. En
 191                     outre l'utilisation de dossiers multiples est transparente.
 192                 </para>
 193             </listitem>
 194
 195             <listitem>
 196                 <para>Source structurée par application</para>
 197
 198                 <programlisting><![CDATA[
 199 /application
 200   /languages
 201     lang.en
 202     lang.de
 203     other.en
 204     other.de
 205 ]]></programlisting>
 206
 207                 <para>
 208                     Positif : tous les fichiers sources pour chacune des langues peuvent être
 209                     trouvés dans un seul dossier. Aucun fractionnement des fichiers.
 210                 </para>
 211
 212                 <para>
 213                     Négatif : avoir des dossiers multiples pour la même langue est
 214                     problématique.
 215                 </para>
 216             </listitem>
 217
 218             <listitem>
 219                 <para>Source structurée par Gettext</para>
 220
 221                 <programlisting><![CDATA[
 222 /languages
 223   /de
 224     /LC_MESSAGES
 225       lang.mo
 226       other.mo
 227   /en
 228     /LC_MESSAGES
 229       lang.mo
 230       other.mo
 231 ]]></programlisting>
 232
 233                 <para>
 234                     Positif : de vieilles sources de gettext peuvent être utilisées sans
 235                     changer la structure.
 236                 </para>
 237
 238                 <para>
 239                     Négatif : avoir des dossiers de dossiers peut être embrouillant pour les
 240                     personnes qui n'ont pas utilisé gettext avant.
 241                 </para>
 242             </listitem>
 243
 244             <listitem>
 245                 <para>Source structurée par fichier</para>
 246
 247                 <programlisting><![CDATA[
 248 /application
 249   /models
 250     mymodel.php
 251     mymodel.de
 252     mymodel.en
 253   /views
 254   /controllers
 255     mycontroller.de
 256 /document_root
 257   /images
 258   /styles
 259   .htaccess
 260   index.php
 261   index.de
 262 /library
 263   /Zend
 264 ]]></programlisting>
 265
 266                 <para>Positif : chaque fichier est lié à sa propre source de traduction.</para>
 267
 268                 <para>
 269                     Négatif : de multiples petits fichiers sources de traduction rendent plus
 270                     difficile la traduction. En outre chaque fichier doit être ajouté comme source
 271                     de traduction.
 272                 </para>
 273             </listitem>
 274         </itemizedlist>
 275
 276         <para>
 277             Les fichiers source uniques et structurés par langue sont les plus utilisés pour
 278             <classname>Zend_Translate</classname>.
 279         </para>
 280
 281         <para>
 282             Maintenant, que nous connaissons la structure que nous voulons avoir, nous devons
 283             créer nos fichiers sources de traduction.
 284         </para>
 285     </sect2>
 286
 287     <sect2 id="zend.translate.using.source.array">
 288         <title>Créer des fichiers sources de type tableau</title>
 289
 290         <para>
 291             Les fichiers sources de type tableau sont simplement des tableaux. Mais vous devez
 292             les définir manuellement parce qu'il n'y a aucun outil pour automatiser cela. Mais parce
 293             qu'ils sont très simples, ils représentent la manière la plus rapide de rechercher des
 294             messages si votre code fonctionne comme prévu. C'est généralement le meilleur adaptateur
 295             pour démarrer avec des systèmes multilingues.
 296         </para>
 297
 298         <programlisting language="php"><![CDATA[
 299 $english = array('message1' => 'message1',
 300                  'message2' => 'message2',
 301                  'message3' => 'message3');
 302 $german = array('message1' => 'Nachricht1',
 303                 'message2' => 'Nachricht2',
 304                 'message3' => 'Nachricht3');
 305
 306 $translate = new Zend_Translate('array', $english, 'en');
 307 $translate->addTranslation($deutsch, 'de');
 308 ]]></programlisting>
 309
 310         <para>
 311             Depuis la version 1.5 il est également possible d'avoir des tableaux inclus dans
 312             un fichier externe. Vous devez simplement fournir le nom de fichier,
 313             <classname>Zend_Translate</classname> l'inclura automatiquement et recherchera le
 314             tableau. Voir l'exemple suivant pour les détails :
 315         </para>
 316
 317         <programlisting language="php"><![CDATA[
 318 // montableau.php
 319 return array(
 320     'message1' => 'Nachricht1',
 321     'message2' => 'Nachricht2',
 322     'message3' => 'Nachricht3');
 323
 324 // contrôleur
 325 $translate = new Zend_Translate('array',
 326                                 'chemin/vers/montableau.php',
 327                                 'de');
 328 ]]></programlisting>
 329
 330         <note>
 331             <para>
 332                 Les fichiers qui ne renvoient pas un tableau ne seront pas inclus. N'importe
 333                 quel rendu issu de ce fichier sera ignoré et également supprimé.
 334             </para>
 335         </note>
 336     </sect2>
 337
 338     <sect2 id="zend.translate.using.source.gettext">
 339         <title>Créer des fichiers sources Gettext</title>
 340
 341         <para>
 342             Des fichiers source Gettext sont créés par la bibliothèque GNU gettext. Il y a
 343             plusieurs outils libres disponibles qui peuvent analyser vos fichiers de code et créer
 344             les fichiers sources nécessaires à gettext. Ces fichiers se terminent par
 345             <emphasis>*.mo</emphasis> et ce sont des fichiers binaires. Un gratuiciel pour créer ces
 346             fichiers est <ulink url="http://sourceforge.net/projects/poedit/">poEdit</ulink>. Cet
 347             outil vous aide également pour le processus de traduction lui-même.
 348         </para>
 349
 350         <programlisting language="php"><![CDATA[
 351 // Les fichiers mo sont créés et déjà traduits
 352 $translate = new Zend_Translate('gettext',
 353                                 'chemin/vers/english.mo',
 354                                 'en');
 355 $translate->addTranslation('chemin/vers/german.mo', 'de');
 356 ]]></programlisting>
 357
 358         <para>
 359             Comme vous pouvez le voir, les adaptateurs sont utilisés exactement de la même
 360             manière, avec juste une petite différence : changer "<code>array</code>" en
 361             "<code>gettext</code>". Toutes autres utilisations sont exactement les mêmes qu'avec
 362             tous autres adaptateurs. Avec l'adaptateur de gettext vous ne devez plus vous occuper de
 363             la structure des répertoires, du "<code>bindtextdomain</code>" et du
 364             "<code>textdomain</code>". Fournissez juste le chemin et le nom de fichier à
 365             l'adaptateur.
 366         </para>
 367
 368         <note>
 369             <para>
 370                 Vous devriez toujours employer UTF-8 comme source d'encodage. Autrement vous
 371                 aurez des problèmes si vous employez deux encodages différents. Par exemple, si un
 372                 de vos fichiers source est encodé en ISO-8815-1 et un fichier différent est codé
 373                 avec CP815. Vous ne pouvez utiliser qu'un seul encodage pour vos fichiers sources,
 374                 ainsi une de vos langues ne s'affichera probablement pas correctement.
 375             </para>
 376
 377             <para>
 378                 UTF-8 est un format portable qui supporte toutes les langues. Si vous employez
 379                 l'encodage UTF-8 pour toutes les langues, vous éliminez le problème des encodages
 380                 incompatibles.
 381             </para>
 382         </note>
 383
 384         <para>
 385             La plupart des éditeur gettext ajoutent les informations de l'adaptateur comme
 386             chaines de traduction vides. C'est pour cela que traduire des chaines vides ne
 387             fonctionne pas avec l'adaptateur gettext. A la place, elles sont effacées de la table de
 388             traduction. <methodname>getAdapterInfo()</methodname> retourne les informations de l'adaptateur
 389             gettext, notamment les informations des fichiers gettext ajoutés.
 390         </para>
 391
 392         <programlisting language="php"><![CDATA[
 393 // Informations sur l'adaptateur
 394 $translate = new Zend_Translate('gettext',
 395                                 'path/to/english.mo',
 396                                 'en');
 397 print_r $translate->getAdapterInfo();
 398 ]]></programlisting>
 399     </sect2>
 400
 401     <sect2 id="zend.translate.using.source.tmx">
 402         <title>Créer des fichiers source TMX</title>
 403
 404         <para>
 405             Les fichiers sources TMX sont les nouveaux standards industriels. Ils ont
 406             l'avantage d'être des fichiers <acronym>XML</acronym> et ainsi ils sont lisibles par tout éditeur de
 407             fichier et naturellement ils sont lisibles pour l'homme. Vous pouvez soit créer des
 408             fichiers TMX manuellement avec un éditeur de texte, soit utiliser un outil. Mais la
 409             plupart des programmes actuellement disponibles pour développer des fichiers source TMX
 410             ne sont pas des gratuiciels.
 411         </para>
 412
 413         <example id="zend.translate.using.source.tmx.example">
 414             <title>Exemple de fichier TMX</title>
 415
 416             <programlisting language="xml"><![CDATA[
 417 <?xml version="1.0" ?>
 418 <!DOCTYPE tmx SYSTEM "tmx14.dtd">
 419 <tmx version="1.4">
 420  <header creationtoolversion="1.0.0" datatype="winres"
 421          segtype="sentence" adminlang="en-us" srclang="de-at"
 422          o-tmf="abc" creationtool="XYZTool" >
 423  </header>
 424  <body>
 425   <tu tuid='message1'>
 426    <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
 427    <tuv xml:lang="en"><seg>message1</seg></tuv>
 428   </tu>
 429   <tu tuid='message2'>
 430    <tuv xml:lang="en"><seg>message2</seg></tuv>
 431    <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
 432   </tu>
 433 ]]></programlisting>
 434
 435             <programlisting language="php"><![CDATA[
 436 $translate = new Zend_Translate('tmx',
 437                                 'chemin/vers/mytranslation.tmx',
 438                                 'en');
 439 // TMX peut contenir différentes langues dans le même fichier
 440 ]]></programlisting>
 441         </example>
 442
 443         <para>
 444             Les fichiers TMX peuvent avoir plusieurs langues dans le même fichier. Toute autre
 445             langue incluse est ajoutée automatiquement, ainsi vous n'avez pas à appeler
 446             <methodname>addLanguage()</methodname>.
 447         </para>
 448
 449         <para>
 450             Si vous voulez avoir seulement les langues spécifiées de la source traduite, vous
 451             pouvez régler l'option <code>defined_language</code> à <constant>TRUE</constant>. Avec cette
 452             option vous pouvez ajouter les langues souhaitées explicitement avec
 453             <methodname>addLanguage()</methodname>. La valeur par défaut pour cette option est d'ajouter toutes
 454             les langues.
 455         </para>
 456     </sect2>
 457
 458     <sect2 id="zend.translate.using.source.csv">
 459         <title>Créer des fichiers source CSV</title>
 460
 461         <para>
 462             Les fichiers sources CSV sont petits et lisibles pour l'homme. Si vos clients
 463             veulent eux-mêmes traduire, vous utiliserez probablement l'adaptateur CSV.
 464         </para>
 465
 466         <example id="zend.translate.using.source.csv.example">
 467             <title>Exemple avec un fichier CSV</title>
 468
 469             <programlisting><![CDATA[
 470 #Exemple de fichier csv
 471 message1;Nachricht1
 472 message2;Nachricht2
 473 ]]></programlisting>
 474
 475             <programlisting language="php"><![CDATA[
 476 $translate = new Zend_Translate('csv',
 477                                 'chemin/vers/matraduction.csv',
 478                                 'de');
 479 $translate->addTranslation('chemin/vers/autretraduction.csv',
 480                            'fr');
 481 ]]></programlisting>
 482         </example>
 483
 484         <para>
 485             Il existe trois options différentes pour l'adaptateur CSV. Vous pouvez paramétrer
 486             "<code>delimiter</code>", "<code>limit</code>" et "<code>enclosure</code>".
 487         </para>
 488
 489         <para>
 490             Le délimiteur standard des fichiers CSV est le signe "<code>;</code>". Mais
 491             celui-ci n'est pas obligatoire. Avec l'option "<code>delimiter</code>" vous pouvez
 492             décider d'utiliser un autre signe de séparation.
 493         </para>
 494
 495         <para>
 496             La taille limite d'une ligne de fichier CSV est par défaut "<code>0</code>" Ce qui
 497             veut dire que la fin de la ligne est recherchée automatiquement. Si vous paramétrez
 498             l'option "<code>limit</code>" avec une valeur quelconque, alors le fichier CSV sera lu
 499             plus rapidement, mais toute ligne dont la longueur excédera la limite sera
 500             tronquée.
 501         </para>
 502
 503         <para>
 504             "L'échappement" par défaut d'un fichier CSV est le "<code>"</code>". Vous pouvez
 505             en paramétrer un autre avec l'option "<code>enclosure</code>".
 506         </para>
 507
 508         <example id="zend.translate.using.source.csv.example2">
 509             <title>Exemple avec un fichier CSV (2)</title>
 510
 511             <programlisting><![CDATA[
 512 #Exemple de fichier csv
 513 # original 'message,1'
 514 "message,1",Nachricht1
 515 # traduction 'Nachricht,2'
 516 message2,"Nachricht,2"
 517 # original 'message3,'
 518 "message3,",Nachricht3
 519 ]]></programlisting>
 520
 521             <programlisting language="php"><![CDATA[
 522 $translate = new Zend_Translate('csv',
 523                                 'chemin/vers/matraduction.csv',
 524                                 'de',
 525                                 array('delimiter' => ','));
 526 $translate->addTranslation('chemin/vers/autretraduction.csv',
 527                            'fr');
 528 ]]></programlisting>
 529         </example>
 530     </sect2>
 531
 532     <sect2 id="zend.translate.using.source.ini">
 533         <title>Créer des fichiers sources INI</title>
 534
 535         <para>
 536             Les fichiers sources <acronym>INI</acronym> sont lisibles par l'homme mais habituellement pas très
 537             petits puisqu'ils incluent également d'autres données à côté des traductions. Si vous
 538             avez des données qui seront éditables par vos clients, vous pouvez aussi utiliser
 539             l'adaptateur <acronym>INI</acronym> dans ce cas.
 540         </para>
 541
 542         <example id="zend.translate.using.source.ini.example">
 543             <title>Exemple avec un fichier INI</title>
 544
 545             <programlisting><![CDATA[
 546 [Test]
 547 ;Commentaires possibles
 548 Message_1="Nachricht 1 (de)"
 549 Message_2="Nachricht 2 (de)"
 550 Message_3="Nachricht :3 (de)"
 551 ]]></programlisting>
 552
 553             <programlisting language="php"><![CDATA[
 554 $translate = new Zend_Translate('ini',
 555                                 'path/to/mytranslation.ini',
 556                                 'de');
 557 $translate->addTranslation('path/to/other.ini',
 558                            'it');
 559 ]]></programlisting>
 560         </example>
 561
 562         <para>
 563             Les fichiers <acronym>INI</acronym> ont de multiples restrictions. Si une valeur dans le fichier <acronym>INI</acronym>
 564             contient un caractère non-alphanumérique, il doit être entouré avec des guillemets
 565             doubles ("). Il y a aussi des mots réservés qui ne doivent pas être utilisés en tant que
 566             clés des fichiers <acronym>INI</acronym>. Ceci inclut : <constant>NULL</constant>, <code>yes</code>,
 567             <code>no</code>, <constant>TRUE</constant> et <constant>FALSE</constant>. Les valeurs <constant>NULL</constant>,
 568             <code>no</code> et <constant>FALSE</constant> sont retournées sous la forme "". <code>yes</code>
 569             et <constant>TRUE</constant> sont retournés en "1". Les caractères {}|&amp;~![()" ne doivent pas
 570             être utilisés dans la clé et ont une signification particulière dans la valeur. Ne les
 571             utilisez pas ou vous rencontrerez des comportements inattendus.
 572         </para>
 573     </sect2>
 574
 575     <sect2 id="zend.translate.using.options">
 576         <title>Options pour les adaptateurs</title>
 577
 578         <para>
 579             Les options peuvent être utilisées avec tous les adaptateurs. Bien sûr chacun
 580             d'eux accepte des options différentes. Vous pouvez passer des options quand vous créez
 581             l'adaptateur. Pour l'instant il y a qu'une option qui est valable pour tous les
 582             adaptateurs. '<code>clear</code>' décide si des données de traduction peuvent être
 583             ajoutées à l'existant ou non. Le comportement standard est d'ajouter des nouvelles
 584             données de traduction à l'existant. Les données de traduction sont seulement effacées
 585             pour la langue choisie. Donc on ne touchera pas aux autres langues.
 586         </para>
 587
 588         <para>
 589             Vous pouvez régler des options temporaires en utilisant
 590             <methodname>addTranslation($data, $locale, array $options = array())</methodname> comme troisième
 591             paramètre optionnel. Ou vous pouvez utiliser la fonction <methodname>setOptions()</methodname> pour
 592             régler une option.
 593         </para>
 594
 595         <example id="zend.translate.using.options.example">
 596             <title>Utiliser les options de traduction</title>
 597
 598             <programlisting language="php"><![CDATA[
 599 // définir ':' comme séparateur pour les fichiers sources de traduction
 600 $options = array('delimiter' => ':');
 601 $translate = new Zend_Translate('csv',
 602                                 'chemin/vers/matraduction.csv',
 603                                 'fr',
 604                                 $options);
 605
 606 ...
 607
 608 // efface le langage défini et utilise de nouvelles données de traduction
 609 $options = array('clear' => true);
 610 $translate->addTranslation('chemin/vers/nouveau.csv',
 611                            'en',
 612                            $options);
 613 ]]></programlisting>
 614         </example>
 615
 616         <para>
 617             Ici vous pouvez trouver toutes les options disponibles pour les différents
 618             adaptateurs avec une description de leur utilisation :
 619         </para>
 620
 621         <table id="zend.translate.using.options.alloptions">
 622             <title>Options des adaptateurs de traduction</title>
 623
 624             <tgroup cols="4">
 625                 <thead>
 626                     <row>
 627                         <entry>Adaptateur</entry>
 628                         <entry>Option</entry>
 629                         <entry>Valeur standard</entry>
 630                         <entry>Description</entry>
 631                     </row>
 632                 </thead>
 633
 634                 <tbody>
 635                     <row>
 636                         <entry>Tous</entry>
 637                         <entry><code>clear</code></entry>
 638                         <entry><constant>FALSE</constant></entry>
 639                         <entry>Si réglé à <constant>TRUE</constant>, les traductions déjà lues seront
 640                         effacées. Ceci peut être utilisé au lieu de créer une nouvelle instance
 641                         quand on lit de nouvelles données de traduction.</entry>
 642                     </row>
 643
 644                     <row>
 645                         <entry>Tous</entry>
 646                         <entry><code>disableNotices</code></entry>
 647                         <entry><constant>FALSE</constant></entry>
 648                         <entry>Si réglé à <constant>TRUE</constant>, toutes les notices concernant la
 649                         non-disponibilité des traductions seront désactivées. Vous devriez
 650                         mettre cette option à <constant>TRUE</constant> dans votre environnement de
 651                         production.</entry>
 652                     </row>
 653
 654                     <row>
 655                         <entry>Tous</entry>
 656                         <entry><code>ignore</code></entry>
 657                         <entry><emphasis>.</emphasis></entry>
 658                         <entry>Tous les dossiers et les fichiers commençant par ce caractère
 659                         seront ignorés dans la recherche automatique de traductions. La valeur
 660                         par défaut est <emphasis>'.'</emphasis>, ce qui signifie que tous les
 661                         fichiers cachés (Unix) seront ignorés. Mettre une valeur par exemple à
 662                         'tmp' aura pour effet d'ignorer les dossiers ou fichiers 'tmpImages' ou
 663                         encore 'tmpFiles' (par exemple), ainsi que tous les
 664                         sous-dossiers</entry>
 665                     </row>
 666
 667                      <row>
 668                          <entry>all</entry>
 669                         <entry>log</entry>
 670                         <entry><emphasis>null</emphasis></entry>
 671                         <entry>An instance of Zend_Log where untranslated messages and notices will
 672                         be written to</entry>
 673                     </row>
 674
 675                      <row>
 676                         <entry>logMessage</entry>
 677                         <entry>all</entry>
 678                         <entry>The message which will be written into the log</entry>
 679                         <entry>
 680                             <emphasis>Untranslated message within '%locale%': %message%</emphasis>
 681                         </entry>
 682                     </row>
 683
 684                     <row>
 685                         <entry>all</entry>
 686                         <entry>logUntranslated</entry>
 687                         <entry><emphasis>false</emphasis></entry>
 688                         <entry>When this option is set to true, all message id's which can not be
 689                         translated will be written into a also attached log</entry>
 690                     </row>
 691
 692                     <row>
 693                         <entry>Tous</entry>
 694                         <entry><code>scan</code></entry>
 695                         <entry><constant>NULL</constant></entry>
 696                         <entry>Si réglé à <constant>NULL</constant>, aucun scan de la structure de
 697                         répertoire ne sera effectué. Si réglé à
 698                         <classname>Zend_Translate::LOCALE_DIRECTORY</classname>, la localisation
 699                         sera détectée dans le répertoire. Si réglé à
 700                         <classname>Zend_Translate::LOCALE_FILENAME</classname>, la localisation
 701                         sera détectée dans le nom de fichier. Voir <xref
 702                         linkend="zend.translate.using.detection" /> pour de plus amples
 703                         détails.</entry>
 704                     </row>
 705
 706                     <row>
 707                         <entry>Csv</entry>
 708                         <entry><code>delimiter</code></entry>
 709                         <entry><code>;</code></entry>
 710                         <entry>Définit quel signe est utilisé pour la séparation de la source et
 711                         de la traduction.</entry>
 712                     </row>
 713
 714                     <row>
 715                         <entry>Csv</entry>
 716                         <entry><code>length</code></entry>
 717                         <entry><code>0</code></entry>
 718                         <entry>Définit la longueur maximum d'une ligne de fichier. Réglé à 0, la
 719                         recherche sera automatique.</entry>
 720                     </row>
 721
 722                     <row>
 723                         <entry>Csv</entry>
 724                         <entry><code>enclosure</code></entry>
 725                         <entry><code>"</code></entry>
 726                         <entry>Définit le caractère d'échappement.</entry>
 727                     </row>
 728                 </tbody>
 729             </tgroup>
 730         </table>
 731
 732         <para>
 733             Si vous souhaitez avoir vos propres définitions d'options, vous pouvez les
 734             utiliser avec tous les adaptateurs. La méthode <methodname>setOptions()</methodname> peut être
 735             utilisée pour définir vos options. La méthode <methodname>setOptions()</methodname> nécessite un
 736             tableau avec les options que vous voulez paramétrer. Si une option fournie existe déjà,
 737             elle sera alors ré-assignée. Vous pouvez définir autant d'options que nécessaire car
 738             elles ne seront pas vérifiées par l'adaptateur. Vérifiez simplement que vous ne créez
 739             pas une option qui existe déjà dans l'adaptateur, vous affecteriez alors une nouvelle
 740             valeur.
 741         </para>
 742
 743         <para>
 744             Pour récupérer l'ensemble des options, vous pouvez utiliser la méthode
 745             <methodname>getOptions()</methodname>. Quand <methodname>getOptions()</methodname> est appelée sans paramètre,
 746             elle retourne l'ensemble des options. Si un paramètre est fourni, seule l'option
 747             particulière sera retournée.
 748         </para>
 749     </sect2>
 750
 751     <sect2 id="zend.translate.using.languages">
 752         <title>Gérer les langues</title>
 753
 754         <para>
 755             En travaillant avec différentes langues il y a quelques méthodes qui seront
 756             utiles.
 757         </para>
 758
 759         <para>
 760             La méthode <methodname>getLocale()</methodname> peut être utilisée pour récupérer la langue
 761             actuellement réglée. Elle peut retourner soit une instance de
 762             <classname>Zend_Locale</classname>, soit un identifiant de localisation.
 763         </para>
 764
 765         <para>
 766             La méthode <methodname>setLocale()</methodname> règle une nouvelle langue standard pour la
 767             traduction. Ceci évite de placer le paramètre facultatif de langue plus d'une fois lors
 768             de l'appel de la méthode <methodname>translate()</methodname>. Si la langue donnée n'existe pas, ou
 769             si aucune donnée de traduction n'est disponible pour la langue, <methodname>setLocale()</methodname>
 770             essaye de remonter à la langue sans région si elle est indiquée. Une langue
 771             <code>fr_FR</code> serait remontée à <code>fr</code>. Si la remontée n'est pas possible,
 772             une exception sera levée.
 773         </para>
 774
 775         <para>
 776             La méthode <methodname>isAvailable()</methodname> vérifie si une langue donnée est déjà
 777             disponible. Elle retourne <constant>TRUE</constant> si des données existent pour la langue
 778             fournie.
 779         </para>
 780
 781         <para>
 782             Et enfin la méthode <methodname>getList()</methodname> peut être utilisée pour récupérer sous
 783             la forme d'un tableau tous les langues paramétrées pour un adaptateur.
 784         </para>
 785
 786         <example id="zend.translate.using.languages.example">
 787             <title>Gestion des langues avec des adaptateurs</title>
 788
 789             <programlisting language="php"><![CDATA[
 790 ...
 791 // retourne la langue paramétrée actuelle
 792 $actual = $translate->getLocale();
 793
 794 ...
 795 // vous pouvez utiliser le paramètre optionel au moment de la traduction
 796 echo $translate->_("mon_texte", "fr");
 797 // ou paramètrer une langue standard
 798 $translate->setLocale("fr");
 799 echo $translate->_("mon_texte");
 800 // référence à la langue de base... fr_CH sera remonté à fr
 801 $translate->setLocale("fr_CH");
 802 echo $translate->_("mon_texte");
 803 ...
 804 // vérifie si la langue existe
 805 if ($translate->isAvailable("fr")) {
 806     // la langue existe
 807 }
 808 ]]></programlisting>
 809         </example>
 810
 811         <sect3 id="zend.translate.using.languages.automatic">
 812             <title>Gestion automatique des langues</title>
 813
 814             <para>
 815                 Notez que tant que vous ajouterez les nouvelles sources de traduction
 816                 seulement via la méthode <methodname>addTranslation()</methodname>,
 817                 <classname>Zend_Translate</classname> cherchera automatiquement la langue
 818                 correspondant au mieux à votre environnement quand vous utiliserez une des
 819                 localisations automatiques "<code>auto</code>" ou "<code>browser</code>". Donc
 820                 normalement vous ne devriez pas appeler <methodname>setLocale()</methodname>. Ceci ne doit être
 821                 utilisé qu'en conjonction avec la détection automatique des sources de
 822                 traduction.
 823             </para>
 824
 825             <para>
 826                 L'algorithme recherchera la meilleure locale suivant le navigateur des
 827                 utilisateurs et votre environnement. Voyez l'exemple suivant pour les détails
 828                 :
 829             </para>
 830
 831             <example id="zend.translate.using.languages.automatic.example">
 832                 <title>Comment la détection automatique de la langue fonctionne-t-elle ?</title>
 833
 834                 <programlisting language="php"><![CDATA[
 835 // Assumons que le navigateur retourne ces valeurs
 836 // HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";
 837
 838 // Exemple 1 :
 839 $translate = new Zend_Translate('gettext',
 840                                 '\my_it.mo',
 841                                 'auto',
 842                                 array('scan' => Zend_Translate::LOCALE_FILENAME);
 843 // pas de langue trouvée, on retourne le messageid
 844
 845 // Exemple 2 :
 846 $translate = new Zend_Translate('gettext',
 847                                 '\my_fr.mo',
 848                                 'auto',
 849                                 array('scan' => Zend_Translate::LOCALE_FILENAME);
 850 // langue correspondante trouvée "en_US"
 851
 852 // Exemple 3 :
 853 $translate = new Zend_Translate('gettext',
 854                                 '\my_de.mo',
 855                                 'auto',
 856                                 array('scan' => Zend_Translate::LOCALE_FILENAME);
 857 // langue correspondante trouvée "de" car "de_AT" est descendue à "de"
 858
 859 // Exemple 4 :
 860 $translate = new Zend_Translate('gettext',
 861                                 '\my_it.mo',
 862                                 'auto',
 863                                 array('scan' => Zend_Translate::LOCALE_FILENAME);
 864 $translate->addTranslation('\my_ru.mo', 'ru');
 865 $translate->setLocale('it_IT');
 866 // retourne "it_IT" comme source de traduction et surcharge le réglage automatique
 867 ]]></programlisting>
 868             </example>
 869
 870             <para>
 871                 Si vous utilisez <methodname>setLocale()</methodname>, la detection automatique de la
 872                 langue sera alors annulée, et la langue à utiliser sera celle spécifiée par l'appel
 873                 de la méthode.
 874             </para>
 875
 876             <para>
 877                 Si vous voulez réactiver la détection automatique, réappelez
 878                 <methodname>setLocale()</methodname> et passez lui la valeur <emphasis>auto</emphasis>.
 879             </para>
 880
 881             <para>
 882                 Depuis Zend Framework 1.7.0 <classname>Zend_Translate</classname> reconnait
 883                 une locale globale pour l'application. Vous pouvez ainsi simplement mettre un objet
 884                 <classname>Zend_Locale</classname> dans le registre, comme montré ci-après. Avec
 885                 cette fonctionnalité, vous pouvez oublier le passage de la locale à votre objet de
 886                 traduction.
 887             </para>
 888
 889             <programlisting language="php"><![CDATA[
 890 // En fichier d'amorçage (bootstrap)
 891 $locale = new Zend_Locale('de_AT');
 892 Zend_Registry::set('Zend_Locale', $locale);
 893
 894 // ailleurs dans votre application
 895 $translate = new Zend_Translate('gettext', '\my_de.mo');
 896 $translate->getLocale();
 897 ]]></programlisting>
 898         </sect3>
 899     </sect2>
 900
 901     <sect2 id="zend.translate.using.detection">
 902         <title>Détéction automatique de la source</title>
 903
 904         <para>
 905             Zend_Translate peut détecter les sources de traduction de manière automatique.
 906             Ainsi vous n'avez pas à déclarer toutes les sources manuellement. Vous laissez
 907             Zend_Translate faire ce travail et scanner complètement tout un répertoire à la
 908             recherche de fichiers de langue de traduction.
 909         </para>
 910
 911         <note>
 912             <para>
 913                 La détection automatique des sources de traduction est disponible depuis Zend
 914                 Framework version 1.5.
 915             </para>
 916         </note>
 917
 918         <para>
 919             L'utilisation est assez semblable à celle qui permet de spécifier une source de
 920             langue. Vous devez simplement donner un dossier, et non plus un fichier, à l'adaptateur.
 921             Ce dossier sera alors scanné
 922         </para>
 923
 924         <example id="zend.translate.using.languages.directory.example">
 925             <title>Scanner un dossier à la recherche de sources de traduction</title>
 926
 927             <programlisting language="php"><![CDATA[
 928 // Soit la structure suivante :
 929 //  /language
 930 //  /language/login/login.tmx
 931 //  /language/logout/logout.tmx
 932 //  /language/error/loginerror.tmx
 933 //  /language/error/logouterror.tmx
 934
 935 $translate = new Zend_Translate('tmx', '/language');
 936 ]]></programlisting>
 937         </example>
 938
 939         <para>
 940             Notez que Zend_Translate cherche dans tous les sous-repertoires. L'utilisation
 941             devient alors relativement simple. Aussi, Zend_Translate ignorera tout fichier qui ne
 942             l'interresse pas : des fichiers non représentatifs de traductions ou encore des fichiers
 943             illisibles. Vérifiez donc que le dossier principal ne contienne que des fichiers de
 944             traductions, car Zend_Translate ne renverra aucune erreur dans le cas contraire, il
 945             ignorera simplement de tels fichiers.
 946         </para>
 947
 948         <note>
 949             <para>
 950                 Selon la compléxité de la récursivité, la traversée du répertoire principal
 951                 peut devenir longue et couteuse.
 952             </para>
 953         </note>
 954
 955         <para>
 956             Dans notre exemple, nous utilisons l'adaptateur TMX qui inclut la langue à
 957             utiliser dans le fichier en question. D'autres adaptateurs n'agissent pas comme cela,
 958             ainsi les noms de fichiers devront comporter les noms des langues à considérer pour de
 959             tels adaptateurs.
 960         </para>
 961
 962         <sect3 id="zend.translate.using.detection.directory">
 963             <title>La langue se trouve dans le nom des dossiers</title>
 964
 965             <para>
 966                 One way to include automatic language detection is to name the directories
 967                 related to the language which is used for the sources within this directory. This is
 968                 the easiest way and is used for example within standard gettext
 969                 implementations.
 970             </para>
 971
 972             <para>
 973                 Zend_Translate needs the 'scan' option to know that it should search the names
 974                 of all directories for languages. See the following example for details:
 975             </para>
 976
 977             <example id="zend.translate.using.detection.directory.example">
 978                 <title>Directory scanning for languages</title>
 979
 980                 <programlisting language="php"><![CDATA[
 981 // expect we have the following structure
 982 //  /language
 983 //  /language/de/login/login.mo
 984 //  /language/de/error/loginerror.mo
 985 //  /language/en/login/login.mo
 986 //  /language/en/error/loginerror.mo
 987
 988 $translate = new Zend_Translate('gettext',
 989                                 '/language',
 990                                 null,
 991                                 array('scan' =>
 992                                     Zend_Translate::LOCALE_DIRECTORY));
 993 ]]></programlisting>
 994             </example>
 995
 996             <note>
 997                 <para>
 998                     This works only for adapters which do not include the language within the
 999                     source file. Using this option for example with TMX will be ignored. Also
1000                     language definitions within the filename will be ignored when using this
1001                     option.
1002                 </para>
1003             </note>
1004
1005             <note>
1006                 <para>
1007                     You should be aware if you have several subdirectories under the same
1008                     structure. Expect we have a structure like
1009                     <code>/language/module/de/en/file.mo</code>. The path contains in this case
1010                     multiple strings which would be detected as locale. It could be eigther
1011                     <code>de</code> or <code>en</code>. As the behaviour is, in this case, not
1012                     declared it is recommended that you use file detection in such
1013                     situations.
1014                 </para>
1015             </note>
1016         </sect3>
1017
1018         <sect3 id="zend.translate.using.detection.filename">
1019             <title>Language through filenames</title>
1020
1021             <para>
1022                 Another way to detect the langage automatically is to use special filenames.
1023                 You can either name the complete file or parts of a file with the used language. To
1024                 use this way of detection you will have to set the 'scan' option at initiation.
1025                 There are several ways of naming the sourcefiles which are described below:
1026             </para>
1027
1028             <example id="zend.translate.using.detection.filename.example">
1029                 <title>Filename scanning for languages</title>
1030
1031                 <programlisting language="php"><![CDATA[
1032 // expect we have the following structure
1033 //  /language
1034 //  /language/login/login_en.mo
1035 //  /language/login/login_de.mo
1036 //  /language/error/loginerror_en.mo
1037 //  /language/error/loginerror_de.mo
1038
1039 $translate = new Zend_Translate('gettext',
1040                                 '/language',
1041                                 null,
1042                                 array('scan' =>
1043                                     Zend_Translate::LOCALE_FILENAME));
1044 ]]></programlisting>
1045             </example>
1046
1047             <sect4 id="zend.translate.using.detection.filename.complete">
1048                 <title>Complete Filename</title>
1049
1050                 <para>
1051                     Having the whole file named after the language is the simplest way but
1052                     only usable if you have only one file per directory.
1053                 </para>
1054
1055                 <programlisting><![CDATA[
1056 /languages
1057   en.mo
1058   de.mo
1059   es.mo
1060 ]]></programlisting>
1061             </sect4>
1062
1063             <sect4 id="zend.translate.using.detection.filename.extension">
1064                 <title>Extension of the file</title>
1065
1066                 <para>
1067                     Another very simple way if to use the extension of the file for the
1068                     language detection. But this may be confusing because you will no longer know
1069                     which file extension the file originally was.
1070                 </para>
1071
1072                 <programlisting><![CDATA[
1073 /languages
1074   view.en
1075   view.de
1076   view.es
1077 ]]></programlisting>
1078             </sect4>
1079
1080             <sect4 id="zend.translate.using.detection.filename.token">
1081                 <title>Filename tokens</title>
1082
1083                 <para>
1084                     Zend_Translate is also captable of detecting the language if it is
1085                     included within the filename. But if you use this way you will have to seperate
1086                     the language with a token. There are three supported tokens which can be used: A
1087                     point '.', a underline '_', or a hyphen '-'.
1088                 </para>
1089
1090                 <programlisting><![CDATA[
1091 /languages
1092   view_en.mo  -> detects english
1093   view_de.mo  -> detects german
1094   view_it.mo  -> detects italian
1095 ]]></programlisting>
1096
1097                 <para>
1098                     The first found token which can be detected as locale will be used. See
1099                     the following example for details.
1100                 </para>
1101
1102                 <programlisting><![CDATA[
1103 /languages
1104   view_en_de.mo  -> detects english
1105   view_en_es.mo  -> detects english and overwrites the first file
1106                     because the same messageids are used
1107   view_it_it.mo  -> detects italian
1108 ]]></programlisting>
1109
1110                 <para>
1111                     All three tokens are used to detect the locale. The first one is the point
1112                     '.', the second is the underline '_' and the third the hyphen '-'. If you have
1113                     several tokens within the filename the first found depending on the order of the
1114                     tokens will be used. See the following example for details.
1115                 </para>
1116
1117                 <programlisting><![CDATA[
1118 /languages
1119   view_en-it.mo  -> detects english because '_' will be used before '-'
1120   view-en_it.mo  -> detects italian because '_' will be used before '-'
1121   view_en.it.mo  -> detects italian because '.' will be used before '_'
1122 ]]></programlisting>
1123             </sect4>
1124         </sect3>
1125     </sect2>
1126
1127     <sect2 id="zend.translate.using.istranslated">
1128         <title>Vérifier les traductions</title>
1129
1130         <para>
1131             Normalement le texte sera traduit sans aucun calcul. Mais il est quelquefois
1132             nécessaire si un texte est traduit ou non dans la source. Dans ce cas la méthode
1133             <methodname>isTranslated()</methodname> peut être utilisé.
1134         </para>
1135
1136         <para>
1137             <methodname>isTranslated($messageId, $original = false, $locale = null)</methodname> prend
1138             comme premier paramètre le texte dont vous voulez vérifier que la traduction est
1139             possible. Et comme troisième paramètre optionnel la langue dont vous voulez connaître la
1140             traduction. Le second paramètre optionnel détermine si la traduction est fixée à la
1141             langue déclarée ou si une autre langue peut être utilisée. Si vous avez un texte qui
1142             peut être traduit en "fr" mais pas en "fr_fr" vous obtiendriez normalement la traduction
1143             fournie, mais avec <varname>$original</varname> réglé à <constant>TRUE</constant>, la méthode
1144             <methodname>isTranslated()</methodname> retournera <constant>FALSE</constant> dans ce cas.
1145         </para>
1146
1147         <example id="zend.translate.using.istranslated.example">
1148             <title>Vérifier si une texte est traduisible</title>
1149
1150             <programlisting language="php"><![CDATA[
1151 $english = array('message1' => 'Nachricht 1',
1152                  'message2' => 'Nachricht 2',
1153                  'message3' => 'Nachricht 3');
1154 $translate = new Zend_Translate('array', $english, 'de_AT');
1155
1156 if ($translate->isTranslated('message1')) {
1157     print "'message1' peut être traduit";
1158 }
1159 if (!($translate->isTranslated('message1', true, 'de'))) {
1160     print "'message1' ne peut pas être traduit en 'de', "
1161         . "il est seulement disponible en 'de_AT'";
1162 }
1163 if ($translate->isTranslated('message1', false, 'de')) {
1164     print "'message1' peut être traduit en 'de_AT' "
1165         . "et par conséquent en 'de'";}
1166 ]]></programlisting>
1167         </example>
1168     </sect2>
1169
1170     <sect2 id="zend.translate.using.logging">
1171
1172         <title>How to log not found translations</title>
1173
1174         <para>
1175             When you have a bigger site or you are creating the translation files manually, you
1176             often have the problem that some messages are not translated. But there is a easy
1177             solution for you when you are using <classname>Zend_Translate</classname>.
1178         </para>
1179
1180         <para>
1181             You have to follow two or three simple steps. First, you have to create a instance of
1182             <classname>Zend_Log</classname>. And then you have to attach this instance to
1183             <classname>Zend_Translate</classname>. See the following example:
1184         </para>
1185
1186         <example id="zend.translate.using.logging.example">
1187             <title>Log translations</title>
1188             <programlisting language="php"><![CDATA[
1189 $translate = new Zend_Translate('gettext', $path, 'de');
1190
1191 // Create a log instance
1192 $writer = new Zend_Log_Writer_Stream('/path/file.log');
1193 $log = new Zend_Log($writer);
1194
1195 // Attach it to the translation instance
1196 $translate->setOptions(array(
1197     'log' => $log,
1198     'logUntranslated' => true));
1199
1200 $translate->translate('unknown string');
1201 ]]></programlisting>
1202         </example>
1203
1204         <para>
1205             Now you will have in the log a new notice:
1206             <code>Untranslated message within 'de': unknown string</code>.
1207         </para>
1208
1209         <note>
1210             <para>
1211                 You should note that any translation which can not be found will be logged. This
1212                 means all translations when a user requests a not supported language. But also every
1213                 request to a message which can not be translated will be logged. Be aware that when
1214                 100 people request the same translation you will have 100 notices logged.
1215             </para>
1216         </note>
1217
1218         <para>
1219             This feature can not only be used to log messages but also to attach this not translated
1220             messages into a empty translation file. To archive this you will have to write your own
1221             log writer which writes the format you want to have and strips the prepending
1222             "Untranslated message" for you.
1223         </para>
1224
1225         <para>
1226             You can also set the '<code>logMessage</code>' option when you want to have your own log
1227             message. Use the '<code>%message%</code>' token for placing the messageId within your log
1228             message, and the '<code>%locale%</code>' token for the requested locale. See the
1229             following example for a self defined log message:
1230         </para>
1231
1232         <example id="zend.translate.using.logging.example2">
1233             <title>Self defined log messages</title>
1234             <programlisting language="php"><![CDATA[
1235 $translate = new Zend_Translate('gettext', $path, 'de');
1236
1237 // Create a log instance
1238 $writer = new Zend_Log_Writer_Stream('/path/to/file.log');
1239 $log    = new Zend_Log($writer);
1240
1241 // Attach it to the translation instance
1242 $translate->setOptions(array(
1243     'log'             => $log,
1244     'logMessage'      => "Missing '%message%' within locale '%locale%'",
1245     'logUntranslated' => true));
1246
1247 $translate->translate('unknown string');
1248 ]]></programlisting>
1249         </example>
1250
1251     </sect2>
1252
1253     <sect2 id="zend.translate.using.sourcedata">
1254         <title>Access to the source data</title>
1255
1256         <para>
1257             Of course sometimes it is useful to have access to the translation source data.
1258             Therefor two functions exist.
1259         </para>
1260
1261         <para>
1262             The <methodname>getMessageIds($locale = null)</methodname> method returns all known message
1263             ids as array.
1264         </para>
1265
1266         <para>
1267             And the <methodname>getMessages($locale = null)</methodname> method returns the complete
1268             translation source as array. The message id is used as key and the translation data as
1269             value.
1270         </para>
1271
1272         <para>
1273             Both methods accept an optional parameter <varname>$locale</varname> which, when set,
1274             returns the translation data for the specified language. If this parameter is not given,
1275             the actual set language will be used. Keep in mind that normally all translations should
1276             be available in all languages. Which means that in a normal situation you will not have
1277             to set this parameter.
1278         </para>
1279
1280         <para>
1281             Additionally the <methodname>getMessages()</methodname> method is able to return the complete
1282             translation dictionary with the pseudo-locale 'all'. This will return all available
1283             translation data for each added locale.
1284         </para>
1285
1286         <note>
1287             <para>
1288                 Attention: The returned array can be <emphasis>very big</emphasis>, depending
1289                 on the count of added locales and the amount of translation data.
1290             </para>
1291         </note>
1292
1293         <example id="zend.translate.using.sourcedata.example">
1294             <title>Handling languages with adapters</title>
1295
1296             <programlisting language="php"><![CDATA[
1297 ...
1298 // returns all known message ids
1299 $messageids = $translate->getMessageIds();
1300 print_r($messageids);
1301
1302 ...
1303 // or just for the specified language
1304 $messageids = $translate->getMessageIds('en_US');
1305 print_r($messageids);
1306
1307 ...
1308 // returns all the complete translation data
1309 $source = $translate->getMessages();
1310 print_r($source);
1311 ]]></programlisting>
1312         </example>
1313     </sect2>
1314 </sect1>