eZ Components - Translation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. contents:: Table of Contents Introduction ============ Many web applications require the use of translated GUI elements. There are several traditional ways of providing this functionality, but none of them are particularly easy to use or maintain. The Translation component provides functionality for retrieving translated data through multiple (extendable) backends and for filtering translatable data. It also allows translated strings with parameters; as a result, it is possible to use different word orders in different languages while still utilizing the parameters correctly. Dependencies ============ This component has an optional dependency on the Cache component by means of the TranslationCacheTiein component. When the latter is installed, the Translation system can make use of a cache for the storage and retrieval of data. The Template component also has an optional dependency on this component, by means of the TemplateTranslationTiein component. This component adds a template function that uses the Translation component to fetch translated data. Class overview ============== ezcTranslationManager This is the main class of this component. It is responsible for calling the configured backends to read translation data and return a translation context in the form of an ezcTranslation object. ezcTranslationCacheBackend, ezcTranslationTsBackend These classes implement backends that read data from a specific source. ezcTranslationTsBackend reads its data from `Qt's Linguist files`_ - an XML-based format for storing original text and translated text. The ezcTranslationCacheBackend handler reads translation data through the Cache mechanism. ezcTranslation Objects of this class are returned by the ezcTranslationManager::getContext() method. ezcTranslationManager uses the backend's getContext() method to retrieve data. ezcTranslationComplementEmptyFilter This class implements a filter that substitutes a missing ("unfinished") translated string with its untranslated source. This filter makes sure that all translatable strings return some text, even if a particular string has not been translated yet. ezcTranslationBorkFilter, ezcTranslationLeetFilter These two classes serve as examples on how to implement filters. Aside from serving as examples, they have very little function. .. _Qt's Linguist files: http://qt.nokia.com/products/qt/features/internationalization Basic usage =========== In the simplest case, your application only needs to access translated versions of the strings that it uses. In most cases, the strings used in an application will be in English, but of course that is not always the case. In the first version of this component, we only support `Qt's Linguist files`_ (TS files) which group translatable strings together in contexts. The TS file format is handled by the ezcTranslationTsBackend class. This backend requires one setting (the location to find the translation) and has one option (the format for the filename for each locale). In the first example, we assume that all translations are stored in the "translations/" directory, and that the filename consists of "translation-" followed by the locale name with the suffix ".xml". The locale name itself is a freeform field, but we recommend to use the `ISO639-1`_ language code, followed by a _ (underscore), followed by the ISO3166_ country code. For example, use nb_NO.xml for Bokmål/Norway or nl_BE.xml for Dutch/Belgium. .. include:: tutorial_example_01.php :literal: In the above example we create a backend object in lines 4 and 5. We tell the backend where to find the translations and the format of the translation filename. The string "[LOCALE]" will automatically be replaced with the locale name when the translation file is opened. With the configured backend, we then construct a manager in line 7. In lines 8 and 9 we instruct the manager to return the contexts "tutorial/headers" and "tutorial/descriptions" for the "nb_NO" locale. When the manager retrieves the content, it first checks its internal cache to determine whether the ezcTranslation object for that context was already retrieved. If the object for the context is available in the cache, it will simply return the ezcTranslation object. If the context is not in the cache, it will defer the retrieving to the backend, store the results in its cache and return the context. Parameterized strings ===================== In many cases, there are parameters to your translated strings, for example to fill in the name of an article. In this case, a solution would be to separate the translatable string into two parts, then concatenate them together with the parameter in the correct place. However, it is also possible that the order of parameters changes when you translate a string. For example the English string "Search for 'appelmoes' returned 3 matches" can be translated in Dutch as: "Er zijn 3 items gevonden bij het zoeken naar 'appelmoes'". The simple concatenation mechanism would no longer work. Luckily, the Translation component supports parameterized strings in two different ways: with numerical replacement identifiers (such as %1 and %2) and with associative identifiers (such as %search_string and %matches). The following example illustrates how this is done. .. include:: tutorial_example_02.php :literal: The first lines are the same as in the previous example. In this case, however, we retrieve an ezcTranslation object for the same context for two different locales (in line 8 and 9). In lines 11 and 12, we request the translation for "Search for '%search_string' returned %matches matches.". This sentence has two parameters (search_string and matches) for which the values are provided in an array. The array is passed as the second parameter to the getTranslation() method. The translation for the English "The apple is round" in Norwegian is "Applet er rund". With the name of the fruit being the parameter, you can see that in Norwegian the parameter value needs to have its first letter uppercased, since it begins a sentence. The translation system supports this by specifying the first letter of the parameter name in the translated string as a capital letter. In TS format, this would be as follows: :: The %fruit is round. %Fruit er rund. When the first letter of a parameter name in the translated string is a capital, the translation system will also make the first letter of the parameter value uppercase. The output of the whole script is therefore: :: Er zijn 4 items gevonden bij het zoeken naar 'appelmoes'. Epplet er rund. .. _`ISO639-1`: http://www.loc.gov/standards/iso639-2/php/code_list.php .. _ISO3166: http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html Filters ======= In some cases, not all of the translation files are up to date. For example, the original translation file might be updated with new strings, but the translator has not had the time to translate the strings yet. For your application to show at least the original strings (often in English) the Translation component uses filters. Filters are applied after the backend retrieves the data, but before it is placed in the internal cache of the manager. .. include:: tutorial_example_03.php :literal: In this example, we add a filter to the manager in line 8. In line 9, we then request translation for a string that is marked as "unfinished". The ezcTranslationComplementEmptyFilter filter fills in the original string for every translation that is still marked as "unfinished". There are a few extra (but less useful) filters in the Translation component. The next example shows the "Leet" and "Bork" filters in action. The Bork filter mangles non-finished or non-translated text so that it is obvious which text is translatable but not yet translated. The "Leet" filter renders your text using Leetspeak_. Both filters are demonstrated in the following example: .. include:: tutorial_example_03b.php :literal: Lines 4 to 8 show the usage of ezcTranslationBorkFilter and lines 10 to 14 show the usage of ezcTranslationLeetFilter. The output of this script is:: header1 [Seerch for 'appelmoes' retoorned 4 metches.] 3r zijn 4 i73ms g3v0nd3n bij h37 z03k3n n44r 'appelmoes'. The first line is "header1" because this script includes the previous one. For the Bork filter you can see that it uses the original string and not the translated version. The Leet filter however uses the translated string exclusively. In case you want to implement your own filters, you need to create a class that implements the ezcTranslationFilter interface. Have a look at the implementation for the ezcTranslationBorkFilter filter, which shows how to implement such a class. .. _Leetspeak: http://en.wikipedia.org/wiki/Leet Iteration ========= In some situations it might be useful to iterate over all the contexts in a specific translation file. The backends that implement the ezcTranslationContextRead interface provide this functionality in the form of an iterator. The ezcTranslationTsBackend is such a class. Using this interface is extremely easy, as you will see in the next example. .. include:: tutorial_example_04.php :literal: In line 7, we initialize the reader with the locale "nb_NO". After this is done, we can simply use foreach() to loop over all the contexts in the translation definition (in lines 9 to 17). Caching ======= Reading from an XML file for every translation context is not very fast - especially when the translation file has a lot of strings. Thus, the translation system benefits from a caching solution. Caching is implemented in the Cache_ component and the links between this component and the caching component are implemented in ezcTranslationCacheBackend_ from the TranslationCacheTiein_ component. Using the cache backend is similar to using the Ts backend, as is shown in the next example: .. include:: tutorial_example_05.php :literal: Instead of setting up the Ts backend, we have to instantiate ezcCacheStorageFileArray (line 4), which we then pass as the sole parameter to the constructor of ezcTranslationCacheBackend_ (line 5). Lines 7 to 13 are exactly the same as in the first example. When you try to run this script an ezcTranslationContextNotAvailableException exception is thrown because we did not put any contents in the cache yet. ezcTranslationCacheBackend_ implements the ezcTranslationContextWrite interface. Using that, combined with a class that implements the ezcTranslationContextRead interface (such as ezcTranslationTsBackend), you can fill the cache in a memory efficient way. The next example demonstrates how this is done. .. include:: tutorial_example_06.php :literal: In lines 4 to 6 we set up the reader interface, like we did in the previous example. Then we continue in lines 8 to 10 to initialize the writer. You should keep the locale for both the reader and writer the same. In line 12, we use a foreach() loop to iterate over all the contexts through the reader interface. We use the ezcTranslationContextWrite::storeContext() method in line 14 to store the retrieved context object to the cache. After we iterate over all the contexts and store them, we initialize the reader and writer in lines 17-18. After you run this script, the script from the previous example would also work (as the cache now has all the contexts). .. _ezcTranslationCacheBackend: TranslationCacheTiein/ezcTranslationCacheBackend.html .. _ezcCacheStorageFileArray: Cache/ezcCacheStorageFileArray.html .. _Cache: introduction_Cache.html .. _TranslationCacheTiein: introduction_TranslationCacheTiein.html Manipulating translation files ============================== It is possible to use the Translation component to modify translation files in the Linguist format as well. The TS backend implements the ezcTranslationContextWrite interface as well. Modifications happen on context level, which means it is not possible right now to remove whole contexts from the translation files. Updating and adding strings to a context, as well as adding a whole new context is supported. To show how to do this, we take the following TS file as starting point: .. include:: translations/mod-example-nl_NL.xml :literal: And use the following script to update it: .. include:: tutorial_example_07.php :literal: After running, the output is:: existing added toegevoeg comment update with new translation ingevuld update translation bijgewerkt to obsolete markeren als ongebruikt new new string nieuwe string More information ================ See the API documentation for ezcTranslationManager (and of course the other classes in this component) for more information. .. Local Variables: mode: rst fill-column: 79 End: vim: et syn=rst tw=79