Translatable
class Translatable extends DataExtension implements PermissionProvider (View source)
The Translatable decorator allows your DataObjects to have versions in different languages, defining which fields are can be translated. Translatable can be applied to any DataObject} subclass, but is mostly used with {@link SiteTree.
Translatable is compatible with the Versioned extension. To avoid cluttering up the database-schema of the 99% of sites without multiple languages, the translation-feature is disabled by default.
Locales (e.g. 'en_US') are used in Translatable for identifying a record by language, see section "Locales and Language Tags".
Configuration
The extension is automatically enabled for SiteTree and SiteConfig records, if they can be found. Add the following to your config.yml in order to register a custom class:
MyClass:
extensions:
TranslatableMake sure to rebuild the database through /dev/build after enabling translatable. Use the correct set_default_locale() before building the database for the first time, as this locale will be written on all new records.
"Default" locales
Important: If the "default language" of your site is not US-English (en_US), please ensure to set the appropriate default language for your content before building the database with Translatable enabled:
Translatable::set_default_locale(<locale>); // e.g. 'de_DE' or 'fr_FR'For the Translatable class, a "locale" consists of a language code plus a region code separated by an underscore, for example "de_AT" for German language ("de") in the region Austria ("AT"). See http://www.w3.org/International/articles/language-tags/ for a detailed description.
Usage
Getting a translation for an existing instance:
$translatedObj = Translatable::get_one_by_locale('MyObject', 'de_DE');Getting a translation for an existing instance:
$obj = DataObject::get_by_id('MyObject', 99); // original language
$translatedObj = $obj->getTranslation('de_DE');Getting translations through Translatable::set_current_locale(). This is not a recommended approach, but sometimes inavoidable (e.g. for Versioned methods).
$origLocale = Translatable::get_current_locale();
Translatable::set_current_locale('de_DE');
$obj = Versioned::get_one_by_stage('MyObject', "ID = 99");
Translatable::set_current_locale($origLocale);Creating a translation:
$obj = new MyObject();
$translatedObj = $obj->createTranslation('de_DE');Usage for SiteTree
Translatable can be used for subclasses of SiteTree, it is automatically configured if this class is foun.
If a child page translation is requested without the parent page already having a translation in this language, the extension will recursively create translations up the tree. Caution: The "URLSegment" property is enforced to be unique across languages by auto-appending the language code at the end. You'll need to ensure that the appropriate "reading language" is set before showing links to other pages on a website through $_GET['locale']. Pages in different languages can have different publication states through the Versioned extension.
Note: You can't get Children() for a parent page in a different language through set_current_locale(). Get the translated parent first.
// wrong
Translatable::set_current_locale('de_DE');
$englishParent->Children();
// right
$germanParent = $englishParent->getTranslation('de_DE');
$germanParent->Children();Translation groups
Each translation can have one or more related pages in other languages. This relation is optional, meaning you can create translations which have no representation in the "default language". This means you can have a french translation with a german original, without either of them having a representation in the default english language tree. Caution: There is no versioning for translation groups, meaning associating an object with a group will affect both stage and live records.
SiteTree database table (abbreviated) ^ ID ^ URLSegment ^ Title ^ Locale ^ | 1 | about-us | About us | en_US | | 2 | ueber-uns | Über uns | de_DE | | 3 | contact | Contact | en_US |
SiteTree_translationgroups database table ^ TranslationGroupID ^ OriginalID ^ | 99 | 1 | | 99 | 2 | | 199 | 3 |
Character Sets
Caution: Does not apply any character-set conversion, it is assumed that all content is stored and represented in UTF-8 (Unicode). Please make sure your database and HTML-templates adjust to this.
Permissions
Authors without administrative access need special permissions to edit locales other than the default locale.
- TRANSLATE_ALL: Translate into all locales
- Translate_
: Translate a specific locale. Only available for all locales set in Translatable::set_allowed_locales().
Note: If user-specific view permissions are required, please overload SiteTree->canView().
Uninstalling/Disabling
Disabling Translatable after creating translations will lead to all pages being shown in the default sitetree regardless of their language. It is advised to start with a new database after uninstalling Translatable, or manually filter out translated objects through their "Locale" property in the database.
Constants
| QUERY_LOCALE_FILTER_ENABLED |
|
Properties
| protected | SS_Object | $owner | The object this extension is applied to. |
from Extension |
| protected | DataObject | $ownerBaseClass | The base class that this extension was applied to; $this->owner must be one of these |
from Extension |
| public | $class | from Extension | ||
| protected static | string | $default_locale | The 'default' language. |
|
| protected static | string | $current_locale | The language in which we are reading dataobjects. |
|
| protected static | mixed | $tableList | A cached list of existing tables |
|
| protected | array | $translatableFields | An array of fields that can be translated. |
|
| protected | array | $original_values | A map of the field values of the original (untranslated) DataObject record |
|
| protected static | bool | $locale_filter_enabled | If this is set to TRUE then augmentSQL() will automatically add a filter clause to limit queries to the current get_current_locale(). This camn be disabled using disable_locale_filter() |
|
| protected static | array | $allowed_locales | ||
| public static | bool | $enable_siteconfig_generation | Enables automatic population of SiteConfig fields using createTranslation if created outside of the Translatable module |
Methods
Called when this extension is added to a particular class
Helper method to strip eval'ed arguments from a string thats passed to DataObject::$extensions or Object::add_extension().
Changes any SELECT query thats not filtering on an ID to limit by the current language defined in get_current_locale().
Create
| Find | more appropriate place to hook into database building |
| This | is specific to SiteTree and CMSMain |
| Implement | a special "translation mode" which triggers display of the readonly fields, so you can translation INTO the "default language" while seeing readonly fields as well. |
| Re-implement | cookie and member option |
| 2.4 | Use {@link getTranslations()} |
| 2.4 | Use SiteTree::add_extension('Translatable') |
| 2.4 | Use SiteTree::remove_extension('Translatable') |
| 2.4 | Use SiteTree::has_extension('Translatable') |
| Integrate | with blacklist once branches/translatable is merged back. |
| 2.4 | Use {@link Translatable::get_homepage_link_by_locale()} |
| 2.4 | Use get_homepage_urlsegment_by_locale() |
| 2.4 | Use custom check: self::$default_locale == self::get_current_locale() |
| 2.4 | Use set_default_locale() |
| 2.4 | Use get_default_locale() |
| 2.4 | Use get_current_locale() |
| 2.4 | Use set_current_locale() |
| 2.4 | Use get_reading_locale() |
| 2.4 | Use default_locale() |
| 2.4 | Use get_by_locale() |
| 2.4 | Use get_one_by_locale() |
| 2.4 | |
| 2.4 | Use choose_site_locale() |
| 2.4 | Use getTranslatedLocales() |