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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.translate.using">
   4     <title>Using Translation Adapters</title>
   5
   6     <para>
   7         The next step is to use the adapter within your code.
   8     </para>
   9
  10     <example id="zend.translate.using.example1">
  11         <title>Example of single-language PHP code</title>
  12
  13         <programlisting language="php"><![CDATA[
  14 print "Example\n";
  15 print "=======\n";
  16 print "Here is line one\n";
  17 print "Today is the " . date("d.m.Y") . "\n";
  18 print "\n";
  19 print "Here is line two\n";
  20 ]]></programlisting>
  21     </example>
  22
  23     <para>
  24         The example above shows some output with no support for translation.
  25         You probably write your code in your native language.
  26         Generally you need to translate not only the output,
  27         but also error and log messages.
  28     </para>
  29
  30     <para>
  31         The next step is to integrate <classname>Zend_Translate</classname> into your existing code.
  32         Of course it is much easier if you had already written your code with
  33         translation in mind, than changing your code afterwards.
  34     </para>
  35
  36     <example id="zend.translate.using.example2">
  37         <title>Example of multi-lingual PHP code</title>
  38
  39         <programlisting language="php"><![CDATA[
  40 $translate = new Zend_Translate(
  41     array(
  42         'adapter' => 'gettext',
  43         'content' => '/my/path/source-de.mo',
  44         'locale'  => 'de'
  45     )
  46 );
  47 $translate->addTranslation(
  48     array(
  49         'content' => '/path/to/translation/fr-source.mo',
  50         'locale'  => 'fr'
  51     )
  52 );
  53
  54 print $translate->_("Example") . "\n";
  55 print "=======\n";
  56 print $translate->_("Here is line one") . "\n";
  57 printf($translate->_("Today is the %1\$s") . "\n", date('d.m.Y'));
  58 print "\n";
  59
  60 $translate->setLocale('fr');
  61 print $translate->_("Here is line two") . "\n";
  62 ]]></programlisting>
  63     </example>
  64
  65     <para>
  66         Now let's take a deeper look into what has been done and how to
  67         integrate <classname>Zend_Translate</classname> into your own code.
  68     </para>
  69
  70     <para>
  71         Create a new <classname>Zend_Translate</classname> object and define the base adapter:
  72     </para>
  73
  74     <programlisting language="php"><![CDATA[
  75 $translate = new Zend_Translate
  76     array(
  77         'adapter' => 'gettext',
  78         'content' => '/path/to/translation/source-de.mo',
  79         'locale'  => 'de'
  80     )
  81 );
  82 ]]></programlisting>
  83
  84     <para>
  85         In this example we chose the
  86         <emphasis>Gettext Adapter</emphasis>.
  87         We place our file <emphasis>source-de.mo</emphasis>
  88         into the directory <emphasis>/path/to/translation</emphasis>.
  89         The gettext file will have German translation included,
  90         and we also added another language source for French.
  91     </para>
  92
  93     <para>
  94         The next step is to wrap all strings which are to be translated.
  95         The simplest approach is to have only simple strings or sentences
  96         like this:
  97     </para>
  98
  99     <programlisting language="php"><![CDATA[
 100 print $translate->_("Example") . "\n";
 101 print "=======\n";
 102 print $translate->_("Here is line one") . "\n";
 103 ]]></programlisting>
 104
 105     <para>
 106         Some strings do not needed to be translated.
 107         The separating line is always a separating line,
 108         even in other languages.
 109     </para>
 110
 111     <para>
 112         Having data values integrated into a translation string is also
 113         supported through the use of embedded parameters.
 114     </para>
 115
 116     <programlisting language="php"><![CDATA[
 117 printf($translate->_("Today is the %1\$s") . "\n", date("d.m.Y"));
 118 ]]></programlisting>
 119
 120     <para>
 121         Instead of <methodname>print()</methodname>, use the <methodname>printf()</methodname>
 122         function and replace all parameters with <code>%1\$s</code> parts.
 123         The first is <code>%1\$s</code>, the second is <code>%2\$s</code>,
 124         and so on. This way a translation can be done without knowing
 125         the exact value. In our example, the date is always the actual day,
 126         but the string can be translated without the knowledge of the actual
 127         day.
 128     </para>
 129
 130     <para>
 131         Each string is identified in the translation storage by a message ID.
 132         You can use message IDs instead of strings in your code, like this:
 133     </para>
 134
 135     <programlisting language="php"><![CDATA[
 136 print $translate->_(1) . "\n";
 137 print "=======\n";
 138 print $translate->_(2) . "\n";
 139 ]]></programlisting>
 140
 141     <para>
 142         But doing this has several disadvantages:
 143     </para>
 144
 145     <para>
 146         You can not see what your code should output just by viewing your code.
 147     </para>
 148
 149     <para>
 150         Also you will have problems if some strings are not translated.
 151         You must always keep in mind how translation works.
 152         First <classname>Zend_Translate</classname> checks whether the specified language has a
 153         translation for the given message ID or string.
 154         If no translation string has been found it refers to the next lower
 155         level language as defined within <classname>Zend_Locale</classname>.
 156         So "<emphasis>de_AT</emphasis>" becomes
 157         "<emphasis>de</emphasis>" only.
 158         If there is no translation found for
 159         "<emphasis>de</emphasis>" either,
 160         then the original message is returned.
 161         This way you always have an output, even in case the message translation
 162         does not exist in your message storage.
 163         <classname>Zend_Translate</classname> never throws an error or exception when translating
 164         strings.
 165     </para>
 166
 167     <sect2 id="zend.translate.using.structure">
 168         <title>Translation Source Structures</title>
 169
 170         <para>
 171             Your next step is to create the translation sources for the
 172             languages you want to translate.
 173             Every adapter is created its own way as described here,
 174             but there are common features applicable for all adapters.
 175         </para>
 176
 177         <para>
 178             You have to decide where to store your translation source files.
 179             Using <classname>Zend_Translate</classname> you are not restricted in any way.
 180             The following structures are preferable:
 181         </para>
 182
 183         <itemizedlist>
 184             <listitem>
 185                 <para>
 186                     Single structured source
 187                 </para>
 188
 189                 <programlisting language="txt"><![CDATA[
 190 /application/
 191 /languages/
 192 /languages/lang.en
 193 /languages/lang.de
 194 /library/
 195 ]]></programlisting>
 196
 197                 <para>
 198                     Positive: all source files for every languages are stored
 199                     in one directory. No splitting of related files.
 200                 </para>
 201             </listitem>
 202
 203             <listitem>
 204                 <para>
 205                     Language structured source
 206                 </para>
 207
 208                 <programlisting language="txt"><![CDATA[
 209 /application/
 210 /languages/
 211 /languages/en/
 212 /languages/en/first.en
 213 /languages/en/second.en
 214 /languages/de/
 215 /languages/de/first.de
 216 /languages/de/second.de
 217 /library
 218 ]]></programlisting>
 219
 220                 <para>
 221                     Positive: Every language is stored in their own directories.
 222                     Easy translation, as every language team has to translate
 223                     only one directory. Also the usage of multiple files is transparent.
 224                 </para>
 225             </listitem>
 226
 227             <listitem>
 228                 <para>
 229                     Application structured source
 230                 </para>
 231
 232                 <programlisting language="txt"><![CDATA[
 233 /application/
 234 /application/languages/
 235 /application/languages/first.en
 236 /application/languages/first.de
 237 /application/languages/second.en
 238 /application/languages/second.de
 239 /library/
 240 ]]></programlisting>
 241
 242                 <para>
 243                     Positive: all source files for every language are stored
 244                     in one directory. No splitting of related files.
 245                 </para>
 246
 247                 <para>
 248                     Negative: having multiple files for the same language can be
 249                     problematic.
 250                 </para>
 251             </listitem>
 252
 253             <listitem>
 254                 <para>
 255                     Gettext structured source
 256                 </para>
 257
 258                 <programlisting language="txt"><![CDATA[
 259 /application/
 260 /languages/
 261 /languages/de/
 262 /languages/de/LC_MESSAGES/
 263 /languages/de/LC_MESSAGES/first.mo
 264 /languages/de/LC_MESSAGES/second.mo
 265 /languages/en/
 266 /languages/en/LC_MESSAGES/
 267 /languages/en/LC_MESSAGES/first.mo
 268 /languages/en/LC_MESSAGES/second.mo
 269 /library/
 270 ]]></programlisting>
 271
 272                 <para>
 273                     Positive: existing gettext sources can be used without changing
 274                     structure.
 275                 </para>
 276
 277                 <para>
 278                     Negative: having sub-sub directories may be confusing
 279                     for people who have not used gettext before.
 280                 </para>
 281             </listitem>
 282
 283             <listitem>
 284                 <para>
 285                    File structured source
 286                 </para>
 287
 288                 <programlisting language="txt"><![CDATA[
 289 /application/
 290 /application/models/
 291 /application/models/MyModel.php
 292 /application/models/MyModel.de
 293 /application/models/MyModel.en
 294 /application/controllers/
 295 /application/controllers/MyController.php
 296 /application/controllers/MyController.de
 297 /application/controllers/MyController.en
 298 /library/
 299 ]]></programlisting>
 300
 301                 <para>
 302                     Positive: translation files are localted near their source.
 303                 </para>
 304
 305                 <para>
 306                     Negative: too many and also small translation files result in
 307                     being tedious to translate.
 308                     Also every file has to be added as translation source.
 309                 </para>
 310             </listitem>
 311         </itemizedlist>
 312
 313         <para>
 314             Single structured and language structured source files are most
 315             usable for <classname>Zend_Translate</classname>.
 316         </para>
 317
 318         <para>
 319             So now, that we know which structure we want to have,
 320             we should create our translation source files.
 321         </para>
 322     </sect2>
 323 </sect1>
 324 <!--
 325 vim:se ts=4 sw=4 et:
 326 -->