From f2efb12bdd78dee082278c5783ef04fcf6f8955e Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Thu, 30 Apr 2009 02:51:17 +0000 Subject: [PATCH] MINOR Updated Translatable and i18n documentation git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@75707 467b73ca-7a2a-4603-9d3b-597d59a354a9 --- core/i18n.php | 4 ++ core/model/Translatable.php | 76 +++++++++++++++++++++++++------------ 2 files changed, 55 insertions(+), 25 deletions(-) diff --git a/core/i18n.php b/core/i18n.php index 42ed4d127..0916e9d53 100755 --- a/core/i18n.php +++ b/core/i18n.php @@ -40,6 +40,10 @@ * * Please see the {Translatable} DataObjectDecorator for managing translations of database-content. * + * For the i18n 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. + * * @see http://www.w3.org/TR/i18n-html-tech-lang * * @author Bernat Foj Capell diff --git a/core/model/Translatable.php b/core/model/Translatable.php index 14d35a845..35575171e 100755 --- a/core/model/Translatable.php +++ b/core/model/Translatable.php @@ -4,30 +4,47 @@ * defining which fields are can be translated. Translatable can be applied * to any {@link DataObject} subclass, but is mostly used with {@link SiteTree}. * Translatable is compatible with the {@link 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. + * Locales (e.g. 'en_US') are used in Translatable for identifying a record by language, + * see section "Locales and Language Tags". * *

Configuration

* - * Enabling Translatable in the $extension array of a DataObject - * + *

Through Object::add_extension()

+ * Enabling Translatable through {@link Object::add_extension()} in your _config.php: + * + * Object::add_extension('MyClass', 'Translatable'); + * + * This is the recommended approach for enabling Translatable. + * + *

Through $extensions

+ * * class MyClass extends DataObject { * static $extensions = array( * "Translatable" * ); * } - * - * - * Enabling Translatable through {@link Object::add_extension()} in your _config.php: - * - * Translatable::set_default_locale('en_US'); - * Object::add_extension('MyClass', 'Translatable'); - * + * * * Make sure to rebuild the database through /dev/build after enabling translatable. * Use the correct {@link 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(); // 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: @@ -44,8 +61,10 @@ * Getting translations through {@link Translatable::set_reading_locale()}. * This is *not* a recommended approach, but sometimes inavoidable (e.g. for {@link Versioned} methods). * - * $obj = DataObject::get_by_id('MyObject', 99); // original language - * $translatedObj = $obj->getTranslation('de_DE'); + * $origLocale = Translatable::get_reading_locale(); + * Translatable::set_reading_locale('de_DE'); + * $obj = Versioned::get_one_by_stage('MyObject', "ID = 99"); + * Translatable::set_reading_locale($origLocale); * * * Creating a translation: @@ -68,15 +87,14 @@ * through the {@link Versioned} extension. * * Note: You can't get Children() for a parent page in a different language - * through set_reading_lang(). Get the translated parent first. + * through set_reading_locale(). Get the translated parent first. * * * // wrong - * Translatable::set_reading_lang('de'); + * Translatable::set_reading_lang('de_DE'); * $englishParent->Children(); * // right - * Translatable::set_reading_lang('de'); - * $germanParent = $englishParent->getTranslation('de'); + * $germanParent = $englishParent->getTranslation('de_DE'); * $germanParent->Children(); * * @@ -90,6 +108,18 @@ * 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

* @@ -97,13 +127,6 @@ * is stored and represented in UTF-8 (Unicode). Please make sure your database and * HTML-templates adjust to this. * - *

"Default" languages

- * - * Important: If the "default language" of your site is not 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(); - * *

Uninstalling/Disabling

* * Disabling Translatable after creating translations will lead to all @@ -112,12 +135,14 @@ * or manually filter out translated objects through their "Locale" property * in the database. * - * @author Michael Gall + * @see http://doc.silverstripe.com/doku.php?id=multilingualcontent + * * @author Ingo Schommer + * @author Michael Gall * @author Bernat Foj Capell * * @package sapphire - * @subpackage misc + * @subpackage i18n */ class Translatable extends DataObjectDecorator { @@ -1031,6 +1056,7 @@ class Translatable extends DataObjectDecorator { * of a page. * * @see http://www.w3.org/TR/html4/struct/links.html#edef-LINK + * @see http://www.w3.org/International/articles/language-tags/ * * @return string HTML */