ITEEDU

Your next step is to create the translation sources for the languages you want to translate. Every adapter is created its own way as described here, but there are common features applicable for all adapters.

You have to decide where to store your translation source files. Using Zend_Translate you are not restricted in any way. The following structures are preferable:

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

$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 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:

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

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

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

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

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

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

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 ';', 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 CSV file
"message,1",Nachricht1
message2,"Nachricht,2"
"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 can use the INI adapter.

[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 it will produce 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' sets 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 other languages remain untouched.

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

// define ':' as separator for the translation source files
$options = array('delimiter' => ':');
$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 make sure not to overwrite any existing option which is used by an adapter.

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

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

The getLocale() method can be used to get the currently set language. It can either 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 even 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 currently set languages for an adapter returned as array.

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

// you can use the optional parameter while translating
echo $translate->_("my_text", "fr");
// or set a new language
$translate->setLocale("fr");
echo $translate->_("my_text");
// refer to the base language
// fr_CH will be downgraded to fr
$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 these language settings:
// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";

// Example 1:
// When no fitting language is found, the message ID is returned
$translate = new Zend_Translate(
    'gettext',
    'my_it.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

// Example 2:
// Best found fitting language is 'fr'
$translate = new Zend_Translate(
    'gettext',
    'my_fr.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

// Example 3:
// Best found fitting language is 'de' ('de_AT' will be degraded)
$translate = new Zend_Translate(
    'gettext',
    'my_de.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

// Example 4:
// Returns 'it' as translation source and overrides the automatic settings
$translate = new Zend_Translate(
    'gettext',
    'my_it.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

$translate->addTranslation('my_ru.mo', 'ru');
$translate->setLocale('it_IT');

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

// default language when requested language is not available
$defaultlanguage = 'en';

// somewhere in your application
$translate = new Zend_Translate('gettext', 'my_de.mo');

if (!$translate->isAvailable($locale->getLanguage())) {
    // not available languages are rerouted to another language
    $translate->setLocale($defaultlanguage);
}

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

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

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

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

例 56.11. Directory scanning for languages

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

	注意
	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. Assuming we have a structure like /language/module/de/en/file.mo. In this case the path contains multiple strings which would be detected as locale. It could be either de or en. In such a case the behaviour is undefined and it is recommended to use file detection in such situations.

// assuming 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/
/languages/en.mo
/languages/de.mo
/languages/es.mo

/languages/
/languages/view.en
/languages/view.de
/languages/view.es

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

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

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

Normally text will be translated without any computation. But sometimes it is necessary to know if a text is translated or not, therefor the isTranslated() method can be used.

isTranslated($messageId, $original = false, $locale = null) takes the text you want to check as its first parameter, and as optional third parameter the locale for which you want to do the check. The optional second parameter declares whether translation is fixed to the declared language or a lower set of translations can be used. If you have a text which can be returned for 'en' but not for 'en_US' you will normally get the translation returned, but by setting $original to true, isTranslated() will return false.

$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 to 'de'"
        . " as it's available only in 'de_AT'";
}

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

When you have a bigger site or you are creating the translation files manually, you often have the problem that some messages are not translated. But there is an easy solution for you when you are using Zend_Translate.

You have to follow two or three simple steps. First, you have to create an instance of Zend_Log. Then you have to attach this instance to Zend_Translate. See the following example:

$translate = new Zend_Translate('gettext', $path, 'de');

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate->setOptions(array(
    'log'             => $log,
    'logUntranslated' => true));

$translate->translate('unknown string');

Now you will have a new notice in the log: Untranslated message within 'de': unknown string.

	注意
	You should note that any translation which can not be found will be logged. This means all translations when a user requests a language which is not supported. Also every request for a message which can not be translated will be logged. Be aware, that 100 people requesting the same translation, will result 100 logged notices.

This feature can not only be used to log messages but also to attach this untranslated messages into an empty translation file. To do so you will have to write your own log writer which writes the format you want to have and strips the prepending "Untranslated message".

You can also set the 'logMessage' option when you want to have your own log message. Use the '%message%' token for placing the messageId within your log message, and the '%locale%' token for the requested locale. See the following example for a self defined log message:

$translate = new Zend_Translate('gettext', $path, 'de');

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate->setOptions(array(
    'log'             => $log,
    'logMessage'      => "Missing '%message%' within locale '%locale%'",
    'logUntranslated' => true));

$translate->translate('unknown string');

Sometimes it is useful to have access to the translation source data. Therefor the following two functions are provided.

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

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

Both methods accept an optional parameter $locale which, if 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 can be used to return the complete translation dictionary using 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 number 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);