Using Translation Adapters
Zend_Translate
Programmer's Reference Guide

Creating source files

Below you will find a description of the different source formats which can be used with Zend_Translate.

Note: Note that most of the described formats should be created by using a tool or a generation process. These Tools and processes are not part of Zend Framework and for most of the described formats free tools are available.

Creating Array source files

Array source files are plain arrays. But you have to define them manually since there is no tool to aid this. But because they are so simple, it's the fastest way to look up messages if your code works as expected. It's generally the best adapter to get started with translation business.

  1. $english = array(
  2.     'message1' => 'message1',
  3.     'message2' => 'message2',
  4.     'message3' => 'message3');
  5.  
  6. $german = array(
  7.     'message1' => 'Nachricht1',
  8.     'message2' => 'Nachricht2',
  9.     'message3' => 'Nachricht3');
  10.  
  11. $translate = new Zend_Translate(
  12.     array(
  13.         'adapter' => 'array',
  14.         'content' => $english,
  15.         'locale'  => 'en'
  16.     )
  17. );
  18. $translate->addTranslation(array('content' => $german, 'locale' => 'de'));

Since release 1.5 it is also supported to have arrays included within an external file. You just have to provide the filename and Zend_Translate will automatically include it and look for the array. See the following example for details:

  1. // myarray.php
  2. return array(
  3.     'message1' => 'Nachricht1',
  4.     'message2' => 'Nachricht2',
  5.     'message3' => 'Nachricht3');
  6.  
  7. // controller
  8. $translate = new Zend_Translate(
  9.     array(
  10.         'adapter' => 'array',
  11.         'content' => '/path/to/myarray.php',
  12.         'locale'  => 'de'
  13.     )
  14. );

Note: Files which do not return an array will fail to be included. Also any output within this file will be ignored and suppressed.

Creating Gettext source files

Gettext source files are created by GNU's gettext library. There are several free tools available that can parse your code files and create the needed gettext source files. These have the extension *.mo and they are binary files. An open source tool for creating the files is » poEdit. This tool also supports you during the translation process itself.

  1. // We accume that we have created the mo files and translated them
  2. $translate = new Zend_Translate(
  3.     array(
  4.         'adapter' => 'gettext',
  5.         'content' => '/path/to/english.mo',
  6.         'locale'  => 'en'
  7.     )
  8. );
  9. $translate->addTranslation(
  10.     array(
  11.         'content' => '/path/to/german.mo',
  12.         'locale' => 'de'
  13.     )
  14. );

As you can see the adapters are used exactly the same way, with one small difference: change array to gettext. All other usages are exactly the same as with all other adapters. With the gettext adapter you no longer have to be aware of gettext's standard directory structure, bindtextdomain and textdomain. Just give the path and filename to the adapter.

Note: You should always use UTF-8 as source encoding. Otherwise you will have problems when using two different source encodings. E.g. one of your source files is encoded with ISO-8815-11 and another one with CP815. You can set only one encoding for your source file, so one of your languages probably will not display correctly.
UTF-8 is a portable format which supports all languages. When using UTF-8 for all languages, you will eliminate the problem of incompatible encodings.

Many gettext editors add adapter informations as empty translation string. This is the reason why empty strings are not translated when using the gettext adapter. Instead they are erased from the translation table and provided by the getAdapterInfo() method. It will return the adapter informations for all added gettext files as array using the filename as key.

  1. // Getting the adapter informations
  2. $translate = new Zend_Translate(
  3.     array(
  4.         'adapter' => 'gettext',
  5.         'content' => '/path/to/english.mo',
  6.         'locale'  => 'en'
  7.     )
  8. );
  9. print_r($translate->getAdapterInfo());

Creating TMX source files

TMX source files are a new industry standard. They have the advantage of being XML files and so they are readable by every editor and of course by humans. You can either create TMX files manually with a text editor, or you can use a special tool. But most tools currently available for creating TMX source files are not freely available.

Example #1 Example TMX file

  1. <?xml version="1.0" ?>
  2. <!DOCTYPE tmx SYSTEM "tmx14.dtd">
  3. <tmx version="1.4">
  4.    <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence"
  5.            adminlang="en-us" srclang="de-at" o-tmf="abc"
  6.            creationtool="XYZTool" >
  7.    </header>
  8.    <body>
  9.        <tu tuid='message1'>
  10.            <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
  11.            <tuv xml:lang="en"><seg>message1</seg></tuv>
  12.        </tu>
  13.        <tu tuid='message2'>
  14.            <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
  15.            <tuv xml:lang="en"><seg>message2</seg></tuv>
  16.        </tu>
  17.    </body>
  18. </tmx>
  1. $translate = new Zend_Translate(
  2.     array(
  3.         'adapter' => 'tmx',
  4.         'content' => 'path/to/mytranslation.tmx',
  5.         'locale'  => 'en'
  6.     )
  7. );

TMX files can have several languages within the same file. All other included languages are added automatically, so you do not have to call addLanguage().

If you want to have only specified languages from the source translated you can set the option defined_language to TRUE. With this option you can add the wished languages explicitly with addLanguage(). The default value for this option is to add all languages.

Note: Option useId
 When you set the useId option to FALSE then the srclang header will be used to define the language which sets the message.
In our example the message key would message1 per default. When this option is set to FALSE the message key Nachricht1 would be used.
Note that the tuv entry which is related to the srclang entry must be the first tuv entry which is set like shown in the above example.

Creating CSV source files

CSV source files are small and human readable. If your customers want to translate their own, you will probably use the CSV adapter.

Example #2 Example CSV file

  1. #Example csv file
  2. message1;Nachricht1
  3. message2;Nachricht2
  1. $translate = new Zend_Translate(
  2.     array(
  3.         'adapter' => 'csv',
  4.         'content' => '/path/to/mytranslation.csv',
  5.         'locale'  => 'de'
  6.     )
  7. );
  8. $translate->addTranslation(
  9.     array(
  10.         'content' => 'path/to/other.csv',
  11.         'locale' => 'fr'
  12.     )
  13. );

There are three different options for the CSV adapter. You can set delimiter, limit and enclosure.

The default delimiter for CSV string is ';', but with the option delimiter you can decide to use another one.

The default limit for a line within a CSV file is '0'. This means that the end of a CSV line is searched automatically. If you set limit to any value, then the CSV file will be read faster, but any line exceeding this limit will be truncated.

The default enclosure to use for CSV files is '"'. You can set a different one using the option enclosure.

Example #3 Second CSV file example

  1. # Example CSV file
  2. "message,1",Nachricht1
  3. message2,"Nachricht,2"
  4. "message3,",Nachricht3
  1. $translate = new Zend_Translate(
  2.     array(
  3.         'adapter' => 'csv',
  4.         'content' => '/path/to/mytranslation.csv',
  5.         'locale'  => 'de',
  6.         'delimiter' => ','
  7.     )
  8. );
  9.  
  10. $translate->addTranslation(
  11.     array(
  12.         'content' => '/path/to/other.csv',
  13.         'locale' => 'fr'
  14.     )
  15. );

Note: When you are using non-ASCII characters within your CSV file, like umlauts or UTF-8 chars, then you should always use enclosure. Omitting the enclosure can lead to missing characters in your translation.

Creating INI source files

INI source files are human readable but normally not very small as they also include other data beside translations. If you have data which shall be editable by your customers you can use the INI adapter.

Example #4 Example INI file

  1. [Test]
  2. ;TestPage Comment
  3. Message_1="Nachricht 1 (de)"
  4. Message_2="Nachricht 2 (de)"
  5. Message_3="Nachricht :3 (de)"
  1. $translate = new Zend_Translate(
  2.     array(
  3.         'adapter' => 'ini',
  4.         'content' => '/path/to/mytranslation.ini',
  5.         'locale'  => 'de'
  6.     )
  7. );
  8. $translate->addTranslation(
  9.     array(
  10.         'content' => '/path/to/other.ini',
  11.         'locale' => 'it'
  12.     )
  13. );

INI files have several restrictions. If a value in the INI file contains any non-alphanumeric characters it needs to be enclosed in double-quotes ("). There are also reserved words which must not be used as keys for INI files. These include: NULL, yes, no, TRUE, and FALSE. Values NULL, no and FALSE results in "", yes and TRUE results in '1'. Characters {}|&~![()" must not be used anywhere in the key and have a special meaning in the value. Do not use them as it will produce unexpected behaviour.

Using Translation Adapters
Zend_Translate
Programmer's Reference Guide