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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.translate.sourcecreation">
   4     <title>Creating source files</title>
   5
   6     <para>
   7         Below you will find a description of the different source formats
   8         which can be used with <classname>Zend_Translate</classname>.
   9     </para>
  10
  11     <note>
  12         <para>
  13             Note that most of the described formats should be created by using
  14             a tool or a generation process. These Tools and processes are not part
  15             of Zend Framework and for most of the described formats free tools
  16             are available.
  17         </para>
  18     </note>
  19
  20     <sect2 id="zend.translate.sourcecreation.array">
  21         <title>Creating Array source files</title>
  22
  23         <para>
  24             Array source files are plain arrays. But you have to define them
  25             manually since there is no tool to aid this.
  26             But because they are so simple, it's the fastest way to look up
  27             messages if your code works as expected. It's generally the best
  28             adapter to get started with translation business.
  29         </para>
  30
  31         <programlisting language="php"><![CDATA[
  32 $english = array(
  33     'message1' => 'message1',
  34     'message2' => 'message2',
  35     'message3' => 'message3');
  36
  37 $german = array(
  38     'message1' => 'Nachricht1',
  39     'message2' => 'Nachricht2',
  40     'message3' => 'Nachricht3');
  41
  42 $translate = new Zend_Translate(
  43     array(
  44         'adapter' => 'array',
  45         'content' => $english,
  46         'locale'  => 'en'
  47     )
  48 );
  49 $translate->addTranslation(array('content' => $german, 'locale' => 'de'));
  50 ]]></programlisting>
  51
  52         <para>
  53             Since release 1.5 it is also supported to have arrays included within an external file.
  54             You just have to provide the filename and <classname>Zend_Translate</classname> will
  55             automatically include it and look for the array. See the following example for details:
  56         </para>
  57
  58         <programlisting language="php"><![CDATA[
  59 // myarray.php
  60 return array(
  61     'message1' => 'Nachricht1',
  62     'message2' => 'Nachricht2',
  63     'message3' => 'Nachricht3');
  64
  65 // controller
  66 $translate = new Zend_Translate(
  67     array(
  68         'adapter' => 'array',
  69         'content' => '/path/to/myarray.php',
  70         'locale'  => 'de'
  71     )
  72 );
  73 ]]></programlisting>
  74
  75         <note>
  76             <para>
  77                 Files which do not return an array will fail to be included.
  78                 Also any output within this file will be ignored and suppressed.
  79             </para>
  80         </note>
  81     </sect2>
  82
  83     <sect2 id="zend.translate.sourcecreation.gettext">
  84         <title>Creating Gettext source files</title>
  85
  86         <para>
  87             Gettext source files are created by GNU's gettext library.
  88             There are several free tools available that can parse your
  89             code files and create the needed gettext source files.
  90             These have the extension <emphasis>*.mo</emphasis>
  91             and they are binary files.
  92             An open source tool for creating the files is
  93             <ulink url="http://sourceforge.net/projects/poedit/">poEdit</ulink>.
  94             This tool also supports you during the translation process itself.
  95         </para>
  96
  97         <programlisting language="php"><![CDATA[
  98 // We accume that we have created the mo files and translated them
  99 $translate = new Zend_Translate(
 100     array(
 101         'adapter' => 'gettext',
 102         'content' => '/path/to/english.mo',
 103         'locale'  => 'en'
 104     )
 105 );
 106 $translate->addTranslation(
 107     array(
 108         'content' => '/path/to/german.mo',
 109         'locale' => 'de'
 110     )
 111 );
 112 ]]></programlisting>
 113
 114         <para>
 115             As you can see the adapters are used exactly the same way,
 116             with one small difference:
 117             change <emphasis>array</emphasis> to <emphasis>gettext</emphasis>. All other usages are
 118             exactly the same as with all other adapters.
 119             With the gettext adapter you no longer have to be aware of
 120             gettext's standard directory structure,
 121             bindtextdomain and textdomain.
 122             Just give the path and filename to the adapter.
 123         </para>
 124
 125         <note>
 126             <para>
 127                  You should always use UTF-8 as source encoding.
 128                  Otherwise you will have problems when using two
 129                  different source encodings.
 130                  E.g. one of your source files is encoded
 131                  with ISO-8815-11 and another one with CP815.
 132                  You can set only one encoding for your source file,
 133                  so one of your languages probably will not display correctly.
 134             </para>
 135
 136             <para>
 137                  UTF-8 is a portable format which supports all languages.
 138                  When using UTF-8 for all languages, you will eliminate
 139                  the problem of incompatible encodings.
 140             </para>
 141         </note>
 142
 143         <para>
 144             Many gettext editors add adapter informations as empty translation string.
 145             This is the reason why empty strings are not translated when using the
 146             gettext adapter. Instead they are erased from the translation table and
 147             provided by the <methodname>getAdapterInfo()</methodname> method. It will return
 148             the adapter informations for all added gettext files as array using the
 149             filename as key.
 150         </para>
 151
 152         <programlisting language="php"><![CDATA[
 153 // Getting the adapter informations
 154 $translate = new Zend_Translate(
 155     array(
 156         'adapter' => 'gettext',
 157         'content' => '/path/to/english.mo',
 158         'locale'  => 'en'
 159     )
 160 );
 161 print_r($translate->getAdapterInfo());
 162 ]]></programlisting>
 163     </sect2>
 164
 165     <sect2 id="zend.translate.sourcecreation.tmx">
 166         <title>Creating TMX source files</title>
 167
 168         <para>
 169             TMX source files are a new industry standard.
 170             They have the advantage of being <acronym>XML</acronym> files and so they are
 171             readable by every editor and of course by humans.
 172             You can either create TMX files manually with a text editor,
 173             or you can use a special tool. But most tools currently available for
 174             creating TMX source files are not freely available.
 175         </para>
 176
 177         <example id="zend.translate.sourcecreation.tmx.example">
 178             <title>Example TMX file</title>
 179
 180             <programlisting language="xml"><![CDATA[
 181 <?xml version="1.0" ?>
 182 <!DOCTYPE tmx SYSTEM "tmx14.dtd">
 183 <tmx version="1.4">
 184    <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence"
 185            adminlang="en-us" srclang="de-at" o-tmf="abc"
 186            creationtool="XYZTool" >
 187    </header>
 188    <body>
 189        <tu tuid='message1'>
 190            <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
 191            <tuv xml:lang="en"><seg>message1</seg></tuv>
 192        </tu>
 193        <tu tuid='message2'>
 194            <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
 195            <tuv xml:lang="en"><seg>message2</seg></tuv>
 196        </tu>
 197    </body>
 198 </tmx>
 199 ]]></programlisting>
 200
 201             <programlisting language="php"><![CDATA[
 202 $translate = new Zend_Translate(
 203     array(
 204         'adapter' => 'tmx',
 205         'content' => 'path/to/mytranslation.tmx',
 206         'locale'  => 'en'
 207     )
 208 );
 209 ]]></programlisting>
 210         </example>
 211
 212         <para>
 213             TMX files can have several languages within the same file.
 214             All other included languages are added automatically,
 215             so you do not have to call <methodname>addLanguage()</methodname>.
 216         </para>
 217
 218         <para>
 219             If you want to have only specified languages from the source translated
 220             you can set the option '<code>defined_language</code>' to <constant>TRUE</constant>.
 221             With this option you can add the wished languages explicitly with
 222             <methodname>addLanguage()</methodname>. The default value for this option is to add all
 223             languages.
 224         </para>
 225
 226         <note>
 227             <title>Option useId</title>
 228
 229             <para>
 230                 When you set the <emphasis>useId</emphasis> option to <constant>FALSE</constant>
 231                 then the <emphasis>srclang</emphasis> header will be used to define the language
 232                 which sets the message.
 233             </para>
 234
 235             <para>
 236                 In our example the message key would <emphasis>message1</emphasis> per default.
 237                 When this option is set to <constant>FALSE</constant> the message key
 238                 <emphasis>Nachricht1</emphasis> would be used.
 239             </para>
 240
 241             <para>
 242                 Note that the <emphasis>tuv</emphasis> entry which is related to the
 243                 <emphasis>srclang</emphasis> entry must be the first
 244                 <emphasis>tuv</emphasis> entry which is set like shown in the above example.
 245             </para>
 246         </note>
 247     </sect2>
 248
 249     <sect2 id="zend.translate.sourcecreation.csv">
 250         <title>Creating CSV source files</title>
 251
 252         <para>
 253             CSV source files are small and human readable.
 254             If your customers want to translate their own,
 255             you will probably use the CSV adapter.
 256         </para>
 257
 258         <example id="zend.translate.sourcecreation.csv.example">
 259             <title>Example CSV file</title>
 260
 261             <programlisting language="txt"><![CDATA[
 262 #Example csv file
 263 message1;Nachricht1
 264 message2;Nachricht2
 265 ]]></programlisting>
 266
 267             <programlisting language="php"><![CDATA[
 268 $translate = new Zend_Translate(
 269     array(
 270         'adapter' => 'csv',
 271         'content' => '/path/to/mytranslation.csv',
 272         'locale'  => 'de'
 273     )
 274 );
 275 $translate->addTranslation(
 276     array(
 277         'content' => 'path/to/other.csv',
 278         'locale' => 'fr'
 279     )
 280 );
 281 ]]></programlisting>
 282         </example>
 283
 284         <para>
 285             There are three different options for the CSV adapter.
 286             You can set '<code>delimiter</code>', '<code>limit</code>' and
 287             '<code>enclosure</code>'.
 288         </para>
 289
 290         <para>
 291             The default delimiter for CSV string is '<code>;</code>', but
 292             with the option '<code>delimiter</code>'
 293             you can decide to use another one.
 294         </para>
 295
 296         <para>
 297             The default limit for a line within a CSV file is '<code>0</code>'. This means
 298             that the end of a CSV line is searched automatically. If you set
 299             '<code>limit</code>' to any value, then the CSV file will be
 300             read faster, but any line exceeding this limit will be truncated.
 301         </para>
 302
 303         <para>
 304             The default enclosure to use for CSV files is '<code>"</code>'. You can
 305             set a different one using the option '<code>enclosure</code>'.
 306         </para>
 307
 308         <example id="zend.translate.sourcecreation.csv.example2">
 309             <title>Second CSV file example</title>
 310
 311             <programlisting language="txt"><![CDATA[
 312 # Example CSV file
 313 "message,1",Nachricht1
 314 message2,"Nachricht,2"
 315 "message3,",Nachricht3
 316 ]]></programlisting>
 317
 318             <programlisting language="php"><![CDATA[
 319 $translate = new Zend_Translate(
 320     array(
 321         'adapter' => 'csv',
 322         'content' => '/path/to/mytranslation.csv',
 323         'locale'  => 'de',
 324         'delimiter' => ','
 325     )
 326 );
 327
 328 $translate->addTranslation(
 329     array(
 330         'content' => '/path/to/other.csv',
 331         'locale' => 'fr'
 332     )
 333 );
 334 ]]></programlisting>
 335         </example>
 336
 337         <note>
 338             <para>
 339                 When you are using non-ASCII characters within your CSV file, like umlauts or UTF-8
 340                 chars, then you should always use enclosure. Omitting the enclosure can lead to
 341                 missing characters in your translation.
 342             </para>
 343         </note>
 344     </sect2>
 345
 346     <sect2 id="zend.translate.sourcecreation.ini">
 347         <title>Creating INI source files</title>
 348
 349         <para>
 350             <acronym>INI</acronym> source files are human readable but normally not very small as
 351             they also include other data beside translations. If you have data which shall be
 352             editable by your customers you can use the <acronym>INI</acronym> adapter.
 353         </para>
 354
 355         <example id="zend.translate.sourcecreation.ini.example">
 356             <title>Example INI file</title>
 357
 358             <programlisting language="txt"><![CDATA[
 359 [Test]
 360 ;TestPage Comment
 361 Message_1="Nachricht 1 (de)"
 362 Message_2="Nachricht 2 (de)"
 363 Message_3="Nachricht :3 (de)"
 364 ]]></programlisting>
 365
 366             <programlisting language="php"><![CDATA[
 367 $translate = new Zend_Translate(
 368     array(
 369         'adapter' => 'ini',
 370         'content' => '/path/to/mytranslation.ini',
 371         'locale'  => 'de'
 372     )
 373 );
 374 $translate->addTranslation(
 375     array(
 376         'content' => '/path/to/other.ini',
 377         'locale' => 'it'
 378     )
 379 );
 380 ]]></programlisting>
 381         </example>
 382
 383         <para>
 384             <acronym>INI</acronym> files have several restrictions. If a value in the
 385             <acronym>INI</acronym> file contains any non-alphanumeric characters it needs to be
 386             enclosed in double-quotes (<code>"</code>). There are also reserved words which must not
 387             be used as keys for <acronym>INI</acronym> files. These include:
 388             <constant>NULL</constant>, <code>yes</code>, <code>no</code>, <constant>TRUE</constant>,
 389             and <constant>FALSE</constant>. Values <constant>NULL</constant>, <code>no</code> and
 390             <constant>FALSE</constant> results in <code>""</code>, <code>yes</code> and
 391             <constant>TRUE</constant> results in <code>1</code>. Characters
 392             <code>{}|&amp;~![()"</code> must not be used anywhere in the key and have a special
 393             meaning in the value. Do not use them as it will produce unexpected behaviour.
 394         </para>
 395     </sect2>
 396 </sect1>
 397 <!--
 398 vim:se ts=4 sw=4 et:
 399 -->