PHP 5.6 и PHP 7 на русском: 38.3. Using Translation Adapters. Глава 38. Zend

38.3. Using Translation Adapters
Пред.	Глава 38. Zend_Translate	След.

38.3. Using Translation Adapters

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

Пример 38.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.

Пример 38.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.

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

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

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
<?php
return array(
    'message1' => 'Nachricht1',
    'message2' => 'Nachricht2',
    'message3' => 'Nachricht3');

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

	Замечание
	Files which do not return an array will fail to be included. Also any output within this file will be ignored and suppressed.

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

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

Пример 38.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.

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

Пример 38.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

Пример 38.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');

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

Пример 38.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 available options for the different adapters with a description of their usage:

Таблица 38.2. 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
all	scan	null	If set to null, no scanning of the directory structure will be done. If set to Zend_Translate::LOCALE_DIRECTORY the locale will be detected within the directory. It set to Zend_Translate::LOCALE_FILENAME the locale will be detected within the filename. See Раздел 38.3.8, «Automatic source detection» for details
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.

38.3.7. Handling languages

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.

Пример 38.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");
// 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
}

38.3.7.1. Automatically handling of languages

Note that as long as you only add new translation sources with the addTranslation() method Zend_Translate will automatically set the best fitting language for your environment. So normally you will not need to call setLocale().

The algorithmus will search for the best fitting locale depending on the users browser and your environment. See the following example for details:

Пример 38.8. How automatically language detection works

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

After setting a language manually with the setLocale() method the automatically detection will be switched off and overridden.

If you want to use the automatic again, you can set the language auto with setLocale() which will reactivate the automatically detection for Zend_Translate.

38.3.8. Automatic source detection

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.

	Замечание
	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.

Пример 38.9. Scanning a directory structure for sources

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

	Замечание
	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: scanned.

38.3.8.1. Language through naming directories

One way to include automatic language detection is to name the directories related to the language which is used for the sources within this directory. This is the easiest way and is used for example within standard gettext implementations.

Zend_Translate needs the 'scan' option to know that it should search the names of all directories for languages. See the following example for details:

Пример 38.10. Directory scanning for languages

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

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

	Замечание
	This works only for adapters which do not include the language within the source file. Using this option for example with TMX will be ignored. Also language definitions within the filename will be ignored when using this option.

	Замечание
	You should be aware if you have several subdirectories under the same structure. Expect we have a structure like `/language/module/de/en/file.mo`. The path contains in this case multiple strings which would be detected as locale. It could be eigther `de` or `en`. As the behaviour is, in this case, not declared it is recommended that you use file detection in such situations.

38.3.8.2. Language through filenames

Another way to detect the langage automatically is to use special filenames. You can either name the complete file or parts of a file with the used language. To use this way of detection you will have to set the 'scan' option at initiation. There are several ways of naming the sourcefiles which are described below:

Пример 38.11. Filename scanning for languages

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

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

38.3.8.2.1. Complete Filename

Having the whole file named after the language is the simplest way but only usable if you have only one file per directory.

/languages
  en.mo
  de.mo
  es.mo

38.3.8.2.2. Extension of the file

Another very simple way if to use the extension of the file for the language detection. But this may be confusing because you will no longer know which file extension the file originally was.

/languages
  view.en
  view.de
  view.es

38.3.8.2.3. Filename tokens

Zend_Translate is also captable of detecting the language if it is included within the filename. But if you use this way you will have to seperate the language with a token. There are three supported tokens which can be used: A point '.', a underline '_', or a hyphen '-'.

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

The first found token which can be detected as locale will be used. See the following example for details.

/languages
  view_en_de.mo  -> detects english
  view_en_es.mo  -> detects english and overwrites the first file because the same messageids are used
  view_it_it.mo  -> detects italian

All three tokens are used to detect the locale. The first one is the point '.', the second is the underline '_' and the third the hyphen '-'. If you have several tokens within the filename the first found depending on the order of the tokens will be used. See the following example for details.

/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 '_'

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

Пример 38.12. Checking if a text is translatable

$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'";
}

38.3.10. Access to the source data

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.

	Замечание
	Attention: The returned array can be very big, depending on the count of added locales and the amount of translation data.

Пример 38.13. 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);

Пред.	Уровень выше	След.
38.2. Adapters for Zend_Translate	Начало	Глава 39. Zend_Uri

PHP5

Для web разработчика

Nov 21
38.3. Using Translation Adapters. Глава 38. Zend_Translate.

38.3. Using Translation Adapters

38.3.1. Translation Source Structures

38.3.2. Creating array source files

38.3.3. Creating Gettext Source Files

38.3.4. Creating TMX Source Files

38.3.5. Creating CSV Source Files

38.3.6. Options for adapters

38.3.7. Handling languages

38.3.7.1. Automatically handling of languages

38.3.8. Automatic source detection

38.3.8.1. Language through naming directories

38.3.8.2. Language through filenames

38.3.8.2.1. Complete Filename

38.3.8.2.2. Extension of the file

38.3.8.2.3. Filename tokens

38.3.9. Checking for translations

38.3.10. Access to the source data

PHP5

Для web разработчика

Nov 2138.3. Using Translation Adapters. Глава 38. Zend_Translate.

38.3. Using Translation Adapters

38.3.1. Translation Source Structures

38.3.2. Creating array source files

38.3.3. Creating Gettext Source Files

38.3.4. Creating TMX Source Files

38.3.5. Creating CSV Source Files

38.3.6. Options for adapters

38.3.7. Handling languages

38.3.7.1. Automatically handling of languages

38.3.8. Automatic source detection

38.3.8.1. Language through naming directories

38.3.8.2. Language through filenames

38.3.8.2.1. Complete Filename

38.3.8.2.2. Extension of the file

38.3.8.2.3. Filename tokens

38.3.9. Checking for translations

38.3.10. Access to the source data

Nov 21
38.3. Using Translation Adapters. Глава 38. Zend_Translate.