There are several additional features which are supported by
Zend_Translate
. Read here for these additional informations.
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.
Example 57.7. Using translation options
// 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:
Table 57.2. Options for translation adapters
Option | Adapter | Description | Default value |
---|---|---|---|
clear | all | 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 | false |
disableNotices | all | If set to true, all notices regarding not available translations will be disabled. You should set this option to true in production environment | false |
ignore | all |
All directories and files beginning with this prefix will be ignored
when searching for files. This value defaults to
'.' which leads to the behavior that all hidden
files will be ignored. Setting this value to 'tmp' would
mean that directories and files like 'tmpImages' and
'tmpFiles' would be ignored as well as all subsequent
directories
|
. |
log | all |
An instance of Zend_Log where untranslated
messages and notices will be written to
|
null |
logMessage | all | The message which will be written into the log | Untranslated message within '%locale%': %message% |
logUntranslated | all | When this option is set to true, all message IDs which can not be translated will be written into the attached log | false |
scan | all |
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. If set to
Zend_Translate::LOCALE_FILENAME the locale will
be detected within the filename. See Section 57.5.3, “Automatic source detection” for details
|
null |
delimiter | Csv | Defines which sign is used as delimiter for separating source and translation | ; |
enclosure | Csv | Defines the enclosure character to be used. Defaults to a doublequote | " |
length | Csv | Defines the maximum length of a csv line. When set to 0 it will be detected automatically | 0 |
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.
Example 57.8. Handling languages with adapters
// 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 }
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 when you use one
of the automatic locales which are 'auto
' or 'browser
'.
So normally you will not need to call setLocale()
. This should only be
used in conjunction with automatic source detection.
The algorithm will search for the best fitting locale depending on the user's browser and your environment. See the following example for details:
Example 57.9. Automatically language detection
// 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');
After setting a language manually with the setLocale()
method the
automatic detection will be switched off and overridden.
If you want to use it again, you can set the language
auto with setLocale()
which will reactivate
the automatic detection for Zend_Translate
.
Since Zend Framework 1.7.0 Zend_Translate
also recognises an
application wide locale. You can simply set a Zend_Locale
instance to the registry like shown below. With this notation you can forget about
setting the locale manually with each instance when you want to use the same locale
multiple times.
// 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.
![]() |
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.
Example 57.10. Scanning a directory structure for sources
// 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.
![]() |
Note |
---|---|
Depending on how deep your directory structure is and how much files are within
this structure it can take a long time for |
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:
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:
Example 57.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));
![]() |
Note |
---|---|
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. |
![]() |
Note |
---|---|
You should be aware if you have several subdirectories under the same
structure. Assuming we have a structure like
|
Another way to detect the language automatically is to use special filenames. You
can either name the complete file or parts of a file after 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:
Example 57.12. Filename scanning for languages
// 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));
Having the whole file named after the language is the simplest way but only viable if you have only one file per language.
/languages/ /languages/en.mo /languages/de.mo /languages/es.mo
Another simple way to use the extension of the file for language detection. But this may be confusing since you will no longer have an idea which extension the file originally had.
/languages/ /languages/view.en /languages/view.de /languages/view.es
Zend_Translate
is also capable of detecting the language
if it is included within the filename. But if you go this way you will have to
separate the language with a token. There are three supported tokens which can
be used: a dot '.', an underscore '_', or a hyphen '-'.
/languages/ /languages/view_en.mo -> detects english /languages/view_de.mo -> detects german /languages/view_it.mo -> detects italian
The first found string delimited by a token which can be interpreted as a locale will be used. See the following example for details.
/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
All three tokens are used to detect the locale. When the filename contains multiple tokens, the first found token depends on the order of the tokens which are used. See the following example for details.
/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.
Example 57.13. 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 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:
Example 57.14. Log translations
$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
.
![]() |
Note |
---|---|
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:
Example 57.15. Self defined log messages
$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.
![]() |
Note |
---|---|
Attention: the returned array can be very big, depending on the number of added locales and the amount of translation data. |
Example 57.16. 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);