31.3. Using Translation Adapters

31.3. Using Translation Adapters
السابق	فصل 31. Zend_Translate	التالي

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

مثال 31.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 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.

مثال 31.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";

$translation->setLanguage('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.

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

31.3.2. 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');

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

	ملاحظة
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.

ملاحظة

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.

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

مثال 31.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().

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

مثال 31.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

مثال 31.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');

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

مثال 31.6. Using translation options

$options = array('clear' => true);
$translate = new Zend_Translate('csv', 'path/to/mytranslation.csv', 'de');
$translate->addTranslation('path/to/other.csv', 'fr');
... // do something
$translate->addTranslation('path/to/new.csv', 'fr', $options); // clear language fr, use new translation

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

مثال 31.7. 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'";
}

السابق	أعلى	التالي
31.2. Adapters for Zend_Translate	البداية	فصل 32. Zend_Uri