Programmer's Reference Guide

Adapters for Zend_Translate

Zend_Translate
Programmer's Reference Guide

Using Translation Adapters

The next step is to use the adapter within your code.

Example #1 Example of single-language PHP code

<?php
print "Example\n";
print "=======\n";
print "Here is line one\n";
print "Today is the " . date("d.m.Y") . "\n";
print "\n";
print "Fix language here is line two\n";

The example above shows some output with no support for translation. You probably write your code in your native language. Generally you need to translate not only the output, but also error messages and log messages.

The next step is to include Zend Translate in your existing code. Of course it is much easier if you are writing your code using Zend_Translate instead of changing your code afterwards.

Example #2 Example of multi-lingual PHP code

<?php
require_once("Zend/Translate.php");

$translate = new Zend_Translate('gettext', '/my/path/source-de.mo', 'de');
$translate->addTranslation('//my/path/fr-source.mo', 'fr');

print $translate->_("Example")."\n";
print "=======\n";
print $translate->_("Here is line one")."\n";
printf($translate->_("Today is the %1\$s") . "\n", date("d.m.Y"));
print "\n";

$translate->setLocale('fr');
print $translate->_("Fix language here is line two") . "\n";

Now let's get a deeper look into what has been done and how to integrate Zend_Translate into your code.

Create a new Translation object and define the base adapter:

<?php
require_once("Zend/Translate.php");

$translate = new Zend_Translate('gettext', '/my/path/source-de.mo', 'de');

In this example we decided the Gettext Adapter. We place our file source-de.mo into the directory /my/path. The gettext file will have German translation included. And we also added another language source for French.

The next step is to wrap all strings which are to be translated. The simplest approach is to have only simple strings or sentences like this:

<?php
print $translate->_("Example")."\n";
print "=======\n";
print $translate->_("Here is line one")."\n";

Some strings do not needed to be translated. The seperating line is always a seperating line, even in other languages.

Having data values integrated into a translation string is also supported through the use of embedded parameters.

<?php
printf($translate->_("Today is the %1\$s") . "\n", date("d.m.Y"));

Instead of print(), use the printf() function and replace all parameters with %1\$s parts. The first is %1\$s, the second %2\$s, and so on. This way a translation can be done without knowing the exact value. In our example, the date is always the actual day, but the string can be translated without the knowledge of the actual day.

Each string is identified in the translation storage by a message id. You can use message id's instead of strings in your code, like this:

<?php
print $translate->_(1)."\n";
print "=======\n";
print $translate->_(2)."\n";

But doing this has several disadvantages:

You can not see what your code should output just by viewing your code.

Also you will get problems if some strings are not translated. You always must imagine how translation works. First Zend_Translate looks if the set language has a translation for the given message id or string. If no translation string has been found it refers to the next lower language as defined within Zend_Locale. So "de_AT" becomes "de" only. If there is no translation found for "de" either, then the original message is returned. This way you always have an output, in case the message translation does not exist in your message storage. Zend_Translate never throws an error or exception when translating strings.

Translation Source Structures

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.

Creating array 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');

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 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.

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 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.

Example #3 Example TMX file

<?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 spezified 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.

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 #4 Example CSV file

#Example csv file
message1;Nachricht1
message2;Nachricht2

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

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

If you have to have the separator sign within your translation string you just have to double it to be included within the translation. One separator sign will separate the origin and translation strings and two separator signs will write the separator signs within the string. See the following example for details

Example #5 Example CSV file two

#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('separator' => ','));
$translate->addTranslation('path/to/other.csv', 'fr');

Options for adapters

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 avaiable to all adapters. 'clear' decides if translation data shold 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.

Example #6 Using translation options

// 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 avaiable options for the different adapters with a description of their useage:

**Options for Translation Adapters**
Adapter	Option	Standard value	Description
all	clear	false	If set to true, the already read translations will be cleared. This can be used instead of creating a new instance when reading new translation data
Csv	separator	;	Defines which sign is used for seperating source and translation

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.

Handling languages

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

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 avaiable for the language, an exception will be thrown.

The isAvaiable() method checks if a given language is already avaiable. 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.

Example #7 Handling languages with adapters

...
// 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");

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

Checking for translations

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 fix 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.

Example #8 Checking if a text is translateable

$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 avaiable in 'de_AT'";
}
if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' can be translated in 'de_AT' falls back to 'de'";
}

Access to the source data

Of course sometimes it is usefull 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 avaiable in all languages. Which means that in a normal situation you will not have to set this parameter.

Example #9 Handling languages with adapters

...
// 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);

Adapters for Zend_Translate

Zend_Translate
Programmer's Reference Guide

Zend_Uri