Download the PHP package vkr/translation-bundle without Composer

Overview

This bundle handles translations. Though there are several other Symfony bundles that do the same, this one is algorithm-agnostic and ORM-agnostic. Translations are stored in entities that might be the same as Doctrine entities, but technically any other ORM can be used as well as non-DB persistence solutions. Users can use default translation algorithms shipped with the bundle or create some on their own. An algorithm can use one or more drivers. Three drivers are shipped with this bundle - one uses Doctrine and and is written for situation where a translations table exists per every translatable entity, the second uses Google Translate, while the third allows to use another field of translated entity as a fallback.

Installation

There are several steps that need to be done before using the bundle.

1) Create these entries in

2) Create a locale retriever service. It must implement and define its two methods. Both methods can return ISO language codes in either short (as in 'en') or long (as in 'en_US') forms.

3) Define a language entity. It must implement . The method should return a language code in the same form as returned by your locale retriever.

4) Define at least one pair of entities - see below.

5) (Optional) If you want to use Google Translations integration, set parameter in .

Defining entity pairs

This bundle is built around the idea of having a separate translation entity for every entity that needs to be translated. Therefore, two entities are needed - a translatable entity that is to be translated and a translation entity that contains translations.

The translatable entity must implement , while its translation entity must implement . Also, there is a naming convention: the translation entity full class name must be the same as that of translatable entity (including namespace) with 'Translations' suffix.

It is recommended (though not necessary) to use provided traits for both interfaces: and . The second one provides all needed methods for translation entity, but translatable entities requires one more method to be defined manually - , which should return an array of field names for every field of translation entity, excluding primary key and associations. For every field that is returned, a getter and a setter need to be defined manually on the translatable entity, their names should be identical to those on the translated entity. In other words, if you have a 'name' field on the translation entity, you need to write something like this on the translatable entity:

If you are using Doctrine, YAML or XML mappings for both entities should contain these:

1) PK fields called "id".

2) One-to-many association to "translations" on translatable entity (eager loading highly recommended).

3) Many-to-one associations on translation entity to "language" and "entity" that point to language entity and translatable entity, respectfully.

Examples for YAML mappings of language, translatable and translation entities are provided in folder.

Optional methods on translatable entity

A translatable entity may define two more methods.

. Under default algorithm, it allows to define a scalar value or another field on the translatable entity as a fallback in case no translations are found. It accepts one optional argument, , which can be used in case there is more than one translatable field. Under default algorithm, if is returned, the bundle will revert to default behavior, that is, throw a . If you do not want the exception to be thrown, but just return an empty string if translations are not found, just make return empty string.

This example will return slug instead of name and 'foo' instead of description:

If you want to use this method in your custom algorithm, you must include a dependency on .

method should return true if you want to enable Google Translations for the entity. If not present, Google Translations will be disabled under default algorithm.

If you want to use this method in your custom algorithm, you must include a dependency on .

TranslationManager::translate() method

The most basic usage of this bundle is as follows:

It will return the first argument (the translatable entity), but the translatable fields will now be populated and accessible via getters. Note that cloning is not used, and the original will be changed.

The first argument to can be changed to an array of translatable entities, as returned by Doctrine's and . In this case, the same array of entities will be returned.

There are two more optional arguments.

The second argument is the locale string in the same format that is returned by language entity's . If not specified, the target language will be determined by of your locale retriever service.

The third argument is the ordering column that should be the name of one of entity's translatable fields. If the first argument is an array, its elements will be reordered based on that field. Currently only ascending ordering is supported.

Because exceptions can be thrown, it is recommended to catch on every call to .

Algorithms and drivers

This bundle can work with multiple translation algorithms. By default, is used. You can swap algorithms by using this syntax:

You can create your own algorithm by implementing . It must contain method which must return a translation entity. While technically all external DB and API calls can be contained in the algorithm itself, it is recommended to decouple them into driver classes. A driver is a plain PHP class that handles external calls. Three drivers are shipped with the bundle: , and . The third one uses another field of a translated entity as a translation and was designed to be used as a fallback if no other translations are found. If you wish to extend the bundle, note that it is highly recommended that no classes except for algorithms depend on drivers.

Three algorithms are shipped with the bundle.

DefaultAlgorithm

1) The script into the DB looks for the translation into the specified locale.

2) If not found, the script looks for the translation into a locale specified by method of your locale retriever.

3) If the translation into that default locale is found, and Google Translation is enabled, the script attempts to get translation into the specified locale from Google. If Google driver throws exception, translation from step 2 is returned.

4) If there is no translation neither to specified locale nor to default locale, the script attempts to retrieve just any other random translation from the DB.

5) Then, if successful, and if Google Translations is enabled, the script will try to translate that translation into the specified locale via Google. If Google driver throws exception, translation from step 4 is returned.

6) Finally, if no translations exist in the DB, the script will look for method on the entity and return whatever value it returns, except for .

7) If does not exist or returns , the script gives up and throws .

NoTranslationAlgorithm

This algorithm does not really translate anything, it just searches for any translation in the DB (returning the one with least PK value if there are many) and throws if there are none. Second and third arguments to are not used.

OnDemandAlgorithm

This algorithm behaves pretty close to , but is less persistent in trying to find a translation. It does not use third argument to .

1) The script looks into the DB for the translation into the specified locale.

2) If there is no translation to specified locale,the script attempts to retrieve just any other random translation from the DB.

3) Then, if successful, and if Google Translations is enabled, the script will try to translate that translation into the specified locale via Google. If Google driver throws exception, translation from step 2 is returned.

4) If step 2 is unsuccessful, the script gives up and throws .

TranslationUpdater::updateTranslations() method

This method provides simple interface for creating and updating translations. It has three mandatory arguments - the translatable entity, the locale, and the array of values. The basic usage example is as follows:

The third argument must contain as many field-value pairs as there are translatable fields on the entity. The method searches for a translation to the given locale and updates the translatable fields, or creates a translation if it does not yet exist.

This method may also throw if no getter and/or setter is found on the translation entity or if the translation entity cannot be initialized using keyword.