Zend_Translate can handle different adapters for translation.
Each adapter has its own advantages and disadvantages.
Below is a comprehensive list of all supported adapters for
translation source files.
Table 167. Adapters for Zend_Translate
| Adapter | Description | Usage |
|---|---|---|
| Array | Use PHP arrays | Small pages; simplest usage; only for programmers |
| Csv | Use comma separated (*.csv/*.txt) files | Simple text file format; fast; possible problems with unicode characters |
| Gettext | Use binary gettext (*.mo) files | GNU standard for linux; thread-safe; needs tools for translation |
| Ini | Use simple INI (*.ini) files | Simple text file format; fast; possible problems with unicode characters |
| Tbx | Use termbase exchange (*.tbx/*.xml) files | Industry standard for inter application terminology strings; XML format |
| Tmx | Use tmx (*.tmx/*.xml) files | Industry standard for inter application translation; XML format; human readable |
| Qt | Use qt linguist (*.ts) files | Cross platform application framework; XML format; human readable |
| Xliff | Use xliff (*.xliff/*.xml) files |
A simpler format as TMX but related to it;
XML format; human readable
|
| XmlTm | Use xmltm (*.xml) files | Industry standard for XML document translation memory; XML format; human readable |
| Others | *.sql | Different other adapters may be implemented in the future |
You should decide which Adapter you want to use for
Zend_Translate. Frequently, external criteria such as a project
requirement or a customer requirement determines this for you, but if you are in
the position to do this yourself, the following hints may simplify
your decision.
Note
When deciding your adapter you should also be aware of the used
encoding. Even if Zend Framework declares UTF-8 as default
encoding you will sometimes be in the need of other encoding.
Zend_Translate will not change any encoding which is defined
within the source file which means that if your Gettext source
is build upon ISO-8859-1 it will also return strings in this encoding
without converting them. There is only one restriction:
When you use a XML based source format like TMX or XLIFF you must define the encoding within the XML files header because XML files without defined encoding will be treated as UTF-8 by any XML parser by default. You should also be aware that actually the encoding of XML files is limited to the encodings supported by PHP which are UTF-8, ISO-8859-1 and US-ASCII.
The Array Adapter is the Adapter which is simplest to use for programmers. But when you have numerous translation strings or many languages you should think about another Adapter. For example, if you have 5000 translation strings, the Array Adapter is possibly not the best choice for you.
You should only use this Adapter for small sites with a handful of languages, and if you or your programmer team creates the translations yourselves.
The Csv Adapter is the Adapter which is simplest to use for customers. CSV files are readable by standard text editors, but text editors often do not support utf8 character sets.
You should only use this Adapter if your customer wants to do translations himself.
Note
Beware that the Csv Adapter has problems when your Csv files are encoded differently than the locale setting of your environment. This is due to a Bug of PHP itself which will not be fixed before PHP 6.0 (http://bugs.php.net/bug.php?id=38471). So you should be aware that the Csv Adapter due to PHP restrictions is not locale aware.
The Gettext Adapter is the Adapter which is used most
frequently. Gettext is a translation source format which was
introduced by GNU, and is now used worldwide.
It is not human readable, but there are several freeware tools
(for instance, POEdit),
which are very helpful. The Zend_Translate Gettext Adapter is
not implemented using PHP's gettext extension.
You can use the Gettext Adapter even if you do not have
the PHP gettext extension installed.
Also the Adapter is thread-safe and the PHP gettext extension
is currently not thread-safe.
Most people will use this adapter. With the available tools, professional translation is very simple. But gettext data are is stored in a machine-readable format, which is not readable without tools.
The Ini Adapter is a very simple Adapter which can even be used directly by customers. INI files are readable by standard text editors, but text editors often do not support utf8 character sets.
You should only use this Adapter when your customer wants to do translations himself. Do not use this adapter as generic translation source.
Regression in PHP 5.3
Prior to PHP 5.3, parse_ini_file()
and parse_ini_string() handled non-ASCII characters
within INI option keys worked without an issue. However,
starting with PHP 5.3, any such keys will now be silently
dropped in the returned array from either function. If you had keys utilizing
UTF-8 or Latin-1 characters, you may find your translations no longer work when
using the INI adapter. If this is the case, we recommend
utilizing a different adapter.
The Tbx Adapter is an Adapter which will be used by customers which already use the TBX format for their internal translation system. Tbx is no standard translation format but more a collection of already translated and pre translated source strings. When you use this adapter you have to be sure that all your needed source string are translated. TBX is a XML file based format and a completely new format. XML files are human-readable, but the parsing is not as fast as with gettext files.
This adapter is perfect for companies when pre translated source files already exist. The files are human readable and system-independent.
The Tmx Adapter is the Adapter which will be used by most customers which have multiple systems which use the same translation source, or when the translation source must be system-independent. TMX is a XML file based format, which is announced to be the next industry standard. XML files are human-readable, but the parsing is not as fast as with gettext files.
Most medium to large companies use this adapter. The files are human readable and system-independent.
The Qt Adapter is for all customers which have TS files as their translation source which are made by QtLinguist. QT is a XML file based format. XML files are human-readable, but the parsing is not as fast as with gettext files.
Several big players have build software upon the QT framework. The files are human readable and system-independent.
The Xliff Adapter is the Adapter which will be used by most customers which want to have XML files but do not have tools for TMX. XLIFF is a XML file based format, which is related to TMX but simpler as it does not support all possibilities of it. XML files are human-readable, but the parsing is not as fast as with gettext files.
Most medium companies use this adapter. The files are human readable and system-independent.
The XmlTm Adapter is the Adapter which will be used by customers which do their layout themself. XmlTm is a format which allows the complete HTML source to be included in the translation source, so the translation is coupled with the layout. XLIFF is a XML file based format, which is related to XLIFF but its not as simple to read.
This adapter should only be used when source files already exist. The files are human readable and system-independent.
Zend_Translate allows you to integrate and use self written
Adapter classes. They can be used like the standard Adapter classes which
are already included within Zend_Translate.
Any adapter class you want to use with Zend_Translate must be a
subclass of Zend_Translate_Adapter.
Zend_Translate_Adapter is an abstract class which already defines
all what is needed for translation. What has to be done by you, is the definition of the
reader for translation datas.
The usage of the prefix "Zend" should be limited to Zend Framework.
If you extend Zend_Translate with your own adapter, you should
name it like "Company_Translate_Adapter_MyFormat". The following code shows an
example of how a self written adapter class could be implemented:
try {
$translate = new Zend_Translate(
array(
'adapter' => 'Company_Translate_Adapter_MyFormat',
'content' => '/path/to/translate.xx',
'locale' => 'en',
'myoption' => 'myvalue'
)
);
} catch (Exception $e) {
// File not found, no adapter class...
// General failure
}
Zend_Translate allows you use internally
Zend_Cache to fasten the loading of translation sources. This
comes very handy if you use many translation sources or extensive source formats like
XML based files.
To use caching you will just have to give a cache object to the
Zend_Translate::setCache() method. It takes a instance of
Zend_Cache as only parameter. Also if you use any adapter direct
you can use the setCache() method. For convenience there are
also the static methods getCache(),
hasCache(), clearCache() and
removeCache().
$cache = Zend_Cache::factory('Core',
'File',
$frontendOptions,
$backendOptions);
Zend_Translate::setCache($cache);
$translate = new Zend_Translate(
array(
'adapter' => 'gettext',
'content' => '/path/to/translate.mo',
'locale' => 'en'
)
);
// to clear the cache somewhere later in your code
Zend_Translate::clearCache();
Note
You must set the cache before you use or initiate
any adapter or instance of Zend_Translate. Otherwise your
translation source will not be cached until you add a new source with the
addTranslation() method.
When the attached cache supports tagging you can set a own tag string by using the
option tag. This allows you do delete only the cache from this
single instance of Zend_Translate. When you are not using this
option the default tag Zend_Translate is used.
Using the option tag you must give the used tag to
clearCache() to declare which tag you want to delete.
$cache = Zend_Cache::factory('Core',
'File',
$frontendOptions,
$backendOptions);
Zend_Translate::setCache($cache);
$translate = new Zend_Translate(
array(
'adapter' => 'gettext',
'content' => '/path/to/translate.mo',
'locale' => 'en',
'tag' => 'MyTag'
)
);
// somewhere later in your code
Zend_Translate::clearCache('MyTag');