Your next step is to create the translation sources for the several languages to which you translate. Every adapter is created its own way as described here. But there are some general features that are relevant for all adapters.

You should know where to store your translation source files. With Zend_Translate you are not bound to any restriction. The following structures are preferable:

• Single structured source

  /application
  /languages
    lang.en
    lang.de
  /library
  
  

  Positive: All source files for every languages can be found in one directory. No splitting of related files.

• Language structured source

  /application
  /languages
    /en
      lang.en
      other.en
    /de
      lang.de
      other.de
  /library
  
  

  Positive: Every language is based in one directory. Easy translation as only one directory has to be translated by a language team. Also the usage of multiple files is transparent.

• Application structured source

  /application
    /languages
      lang.en
      lang.de
      other.en
      other.de
  
  

  Positive: All source files for every languages can be found in one directory. No splitting of related files.

  Negative: Having multiple files for the same language is problematic.

• Gettext structured source

  /languages
    /de
      /LC_MESSAGES
        lang.mo
        other.mo
    /en
      /LC_MESSAGES
        lang.mo
        other.mo
  
  

  Positive: Old gettext sources can be used without changing structure.

  Negative: Having sub-sub directories may be confusing for people who have not used gettext before.

• File structured source

  /application
    /models
      mymodel.php
      mymodel.de
      mymodel.en
    /views
    /controllers
      mycontroller.de
  /document_root
    /images
    /styles
    .htaccess
    index.php
    index.de
  /library
    /Zend
  
  

  Positive: Every file is related to its own translation source.

  Negative: Multiple small translation source files make it harder to translate. Also every file has to be added as translation source.

Single structured and language structured source files are most usable for Zend_Translate.

So now, that we know which structure we want to have, we should create our translation source files.

Array source files are just arrays. But you have to define them manually because there is no tool for 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.

$english = array('message1' => 'message1',
                 'message2' => 'message2',
                 'message3' => 'message3');
$german = array('message1' => 'Nachricht1',
                'message2' => 'Nachricht2',
                'message3' => 'Nachricht3');

$translate = new Zend_Translate('array', $english, 'en');
$translate->addTranslation($deutsch, 'de');

        

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

// myarray.php
return array(
    'message1' => 'Nachricht1',
    'message2' => 'Nachricht2',
    'message3' => 'Nachricht3');

// controller
$translate = new Zend_Translate('array', 'path/to/myarray.php', 'de');

        

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

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 files have the ending *.mo and they are binary files. One freeware tool for creating the files is » poEdit. This tool also supports you for the translation process itself.

// We expect that we have created the mo files and translated them
$translate = new Zend_Translate('gettext', 'path/to/english.mo', 'en');
$translate->addTranslation('path/to/german.mo', 'de');

        

As you can see the adapters are used exactly the same way, with only just 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 if you are using two different source encodings. For example, if one of your source files is encoded with ISO-8815-11 and another file is encoded 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. If you use UTF-8 encoding for all languages, you eliminate the problem of incompatible encodings.

Many gettext editors add adapter informations as empty translation string. This is the reason why empty string 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 where the filename is used as key.

// How to get the adapter informations
$translate = new Zend_Translate('gettext', 'path/to/english.mo', 'en');
print_r $translate->getAdapterInfo();

        

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 they are human-readable. You can either create TMX files manually with a text editor, or you can use a tool. But most tools currently available for developing TMX source files are not freeware.

<?xml version="1.0" ?>
<!DOCTYPE tmx SYSTEM "tmx14.dtd">
<tmx version="1.4">
 <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence"
         adminlang="en-us" srclang="de-at" o-tmf="abc"
         creationtool="XYZTool" >
 </header>
 <body>
  <tu tuid='message1'>
   <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
   <tuv xml:lang="en"><seg>message1</seg></tuv>
  </tu>
  <tu tuid='message2'>
   <tuv xml:lang="en"><seg>message2</seg></tuv>
   <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
  </tu>

$translate = new Zend_Translate('tmx', 'path/to/mytranslation.tmx', 'en');
// TMX can have several languages within one TMX file.

            

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 explicit with addLanguage(). The default value for this option is to add all languages.

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

#Example csv file
message1;Nachricht1
message2;Nachricht2

$translate = new Zend_Translate('csv', 'path/to/mytranslation.csv', 'de');
$translate->addTranslation('path/to/other.csv', 'fr');

            

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

The default delimiter for CSV string is the ';' sign. But it has not to be that sign. With the option 'delimiter' you can decide to use another delimiter sign.

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 the 'limit' option 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 with the option 'enclosure'.

# Example csv file
# original 'message,1'
"message,1",Nachricht1
# translation 'Nachricht,2'
message2,"Nachricht,2"
# original 'message3,'
"message3,",Nachricht3

$translate = new Zend_Translate('csv',
                                'path/to/mytranslation.csv',
                                'de',
                                array('delimiter' => ','));
$translate->addTranslation('path/to/other.csv', 'fr');

            

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 could also use the INI adapter for this purpose.

[Test]
;TestPage Comment
Message_1="Nachricht 1 (de)"
Message_2="Nachricht 2 (de)"
Message_3="Nachricht :3 (de)"

$translate = new Zend_Translate('ini', 'path/to/mytranslation.ini', 'de');
$translate->addTranslation('path/to/other.ini', 'it');

            

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 you will have unexpected behaviour.

Options can be used with all adapters. Of course the options are different for all adapters. You can set options when you create the adapter. Actually there is one option which is available to all adapters. 'clear' decides if translation data should be added to existing one or not. Standard behaviour is to add new translation data to existing one. But the translation data is only cleared for the selected language. So all other languages will not be touched.

You can set options temporary when using addTranslation($data, $locale, array $options = array()). as third and optional parameter. And you can use the setOptions() function to set the options fix.

// define ':' as separator for the translation source files
$options = array('separator' => ':');
$translate = new Zend_Translate('csv',
                                'path/to/mytranslation.csv',
                                'de',
                                $options);

...

// clear the defined language and use new translation data
$options = array('clear' => true);
$translate->addTranslation('path/to/new.csv', 'fr', $options);

            

Here you can find all available options for the different adapters with a description of their usage:

When you want to have self defined options, you are also able to use them within all adapters. The setOptions() method can be used to define your option. setOptions() needs an array with the options you want to set. If an given option exists it will be signed over. You can define as much options as needed as they will not be checked by the adapter. Just get sure that you do not sign over any existing option which is used by an adapter.

To return the set option you can use the getOptions() method. When getOptions() is called without an parameter it will return all set options. When the optional parameter is given you will only get the particular option returned.

When working with different languages there are a few methods which will be useful.

The getLocale() method can be used to get the actual set language. It can eigther hold an instance of Zend_Locale or the identifier of a locale.

The setLocale() method sets a new standard language for translation. This prevents the need of setting the optional language parameter more than once to the translate() method. If the given language does not exist, or no translation data is available for the language, setLocale() tries to downgrade to the language without the region if any was given. A language of en_US would be downgraded to en. When also the downgraded language can not be found an exception will be thrown.

The isAvailable() method checks if a given language is already available. It returns true if data for the given language exist.

And finally the getList() method can be used to get all actual set languages for an adapter returned as array.

...
// returns the actual set language
$actual = $translate->getLocale();

...
// you can use the optional parameter while translating
echo $translate->_("my_text", "fr");
// or set a new standard language
$translate->setLocale("fr");
echo $translate->_("my_text");
// refer to the base language... fr_CH will be downgraded to fr and be
// used
$translate->setLocale("fr_CH");
echo $translate->_("my_text");

...
// check if this language exist
if ($translate->isAvailable("fr")) {
    // language exists
}

            

// Let's expect the browser returns this language settings
HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";

// Example 1:
$translate = new Zend_Translate("gettext", "\my_it.mo", "it_IT");
$translate->addTranslation("\my_es.mo","es_UG");
// no fitting language found, return the messageid

// Example 2:
$translate = new Zend_Translate("gettext", "\my_en.mo", "en_US");
$translate->addTranslation("\my_it.mo","it_IT");
// best found fitting language is "en_US"

// Example 3:
$translate = new Zend_Translate("gettext", "\my_it.mo", "it_IT");
$translate->addTranslation("\my_de.mo","de");
// best found fitting language is "de" because "de_AT" will be
// degraded to "de"

// Example 4:
$translate = new Zend_Translate("gettext", "\my_it.mo", "it_IT");
$translate->addTranslation("\my_ru.mo","ru");
$translate->setLocale("it_IT");
$translate->addTranslation("\my_de.mo","de");
// returns "it_IT" as translation source

                

// in your bootstrap file
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

// somewhere in your application
$translate = new Zend_Translate("gettext", "\my_de.mo");
$translate->getLocale();

            

Zend_Translate can detect translation sources automatically. So you don't have to declare each source file manually. You can let Zend_Translate do this job and scan the complete directory structure for source files.

Note: Automatic source detection is available since Zend Framework version 1.5 .

The usage is quite the same as initiating a single translation source with one difference. You must give a directory which has to be scanned instead a file.

// expect we have the following structure
//  /language
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate('tmx', '/language');

            

So Zend_Translate does not only search the given directory, but also all subdirectories for translation source files. This makes the usage quite simple. But Zend_Translate will ignore all files which are not sources or which produce failures while reading the translation data. So you have to make sure that all of your translation sources are correct and readable because you will not get any failure if a file is bogus or can not be read.

Note: Depending on how deep your directory structure is and how much files are within this structure it can take a long time for Zend_Translate to complete.

In our example we have used the TMX format which includes the language to be used within the source. But many of the other source formats are not able to include the language within the file. Even this sources can be used with automatic scanning if you do some pre-requisits as described below:

// expect we have the following structure
//  /language
//  /language/de/login/login.mo
//  /language/de/error/loginerror.mo
//  /language/en/login/login.mo
//  /language/en/error/loginerror.mo

$translate = new Zend_Translate('gettext',
                                '/language',
                                null,
                                array('scan' =>
                                      Zend_Translate::LOCALE_DIRECTORY));

                

// expect we have the following structure
//  /language
//  /language/login/login_en.mo
//  /language/login/login_de.mo
//  /language/error/loginerror_en.mo
//  /language/error/loginerror_de.mo

$translate = new Zend_Translate('gettext',
                                '/language',
                                null,
                                array('scan' =>
                                      Zend_Translate::LOCALE_FILENAME));

                

/languages
  en.mo
  de.mo
  es.mo

/languages
  view.en
  view.de
  view.es

/languages
  view_en.mo  -> detects english
  view_de.mo  -> detects german
  view_it.mo  -> detects italian

/languages
  view_en_de.mo  -> detects english
  view_en_es.mo  -> detects english and overwrites the first file
  view_it_it.mo  -> detects italian

/languages
  view_en-it.mo  -> detects english because '_' will be used before '-'
  view-en_it.mo  -> detects italian because '_' will be used before '-'
  view_en.it.mo  -> detects italian because '.' will be used before '_'

Normally text will be translated without any computations. But sometimes it is necessary to know if a text is translated or not within the source. Therefor the isTranslated() method can be used.

isTranslated($messageId, $original = false, $locale = null) takes as first parameter the text from which you want to know if it can be translated. And as optional third parameter the locale for which you want to know the translation. The optional second parameter declares if translation is fixed to the declared language or a lower set of translations can be used. If you have a text which can be translated by 'en' but not for 'en_US' you will normally get the translation returned, but by setting $original to true, the isTranslated() method will return false in such cases.

$english = array('message1' => 'Nachricht 1',
                 'message2' => 'Nachricht 2',
                 'message3' => 'Nachricht 3');
$translate = new Zend_Translate('array', $english, 'de_AT');

if ($translate->isTranslated('message1')) {
    print "'message1' can be translated";
}
if (!($translate->isTranslated('message1', true, 'de'))) {
    print "'message1' can not be translated in 'de' as it's only " .
    "available in 'de_AT'";
}
if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' can be translated in 'de_AT' falls back to 'de'";
}

            

Of course sometimes it is useful to have access to the translation source data. Therefor two functions exist.

The getMessageIds($locale = null) method returns all known message ids as array.

And the getMessages($locale = null) method returns the complete translation source as array. The message id is used as key and the translation data as value.

Both methods accept an optional parameter $locale which, when set, returns the translation data for the specified language. If this parameter is not given, the actual set language will be used. Keep in mind that normally all translations should be available in all languages. Which means that in a normal situation you will not have to set this parameter.

Additionally the getMessages() method is able to return the complete translation dictionary with the pseudo-locale 'all'. This will return all available translation data for each added locale.

Note: Attention: The returned array can be very big, depending on the count of added locales and the amount of translation data.

...
// returns all known message ids
$messageids = $translate->getMessageIds();
print_r($messageids);

...
// or just for the specified language
$messageids = $translate->getMessageIds('en_US');
print_r($messageids);

...
// returns all the complete translation data
$source = $translate->getMessages();
print_r($source);