Additional features for translationThere are several additional features which are supported by Zend_Translate. Read here for these additional informations. 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: '
You can set options temporarily when using Example #1 Using translation 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. Handling languagesWhen 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 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 #2 Handling languages with adapters
Automatical 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 when you use one of the automatic locales which are
' 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 #3 Automatically language detection
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.
Automatic source detectionZend_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.
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 #4 Scanning a directory structure for sources
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.
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: Language through naming directoriesOne 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 ' Example #5 Directory scanning for languages
Language through filenames
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 ' Example #6 Filename scanning for languages
Complete filenameHaving 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 Extension of the fileAnother 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 Filename tokensZend_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 '_' Checking for translationsNormally 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 #7 Checking if a text is translatable
How to log not found translationsWhen 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 #8 Log translations
Now you will have a new notice in the log:
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 ' Example #9 Self defined log messages
Accessing source dataSometimes 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.
Example #10 Handling languages with adapters
|