Version: current

# Class i18n

Base-class for storage and retrieval of translated entities.

Please see the `Translatable` extension for managing translations of database-content.

Usage

PHP:

    _t('MyNamespace.MYENTITY', 'My default natural language value');
    _t('MyNamespace.MYENTITY', 'My default natural language value', PR_MEDIUM, 'My explanatory context');
    sprintf(_t('MyNamespace.MYENTITY', 'Counting %s things'), 42);

Templates:

    <% _t('MyNamespace.MYENTITY', 'My default natural language value') %>
    <% sprintf(_t('MyNamespace.MYENTITY','Counting %s things'),$ThingsCount) %>

Javascript (see sapphire/javascript/i18n.js):

    ss.i18n._t('MyEntity.MyNamespace','My default natural language value');

File-based i18n-translations always have a "locale" (e.g. 'en_US'). Common language names (e.g. 'en') are mainly used in `Translatable` for database-entities.

Text Collection

Features a "textcollector-mode" that parses all files with a certain extension (currently *.php and *.ss) for new translatable strings. Textcollector will write updated string-tables to their respective folders inside the module, and automatically namespace entities to the classes/templates they are found in (e.g. $lang['en_US']['AssetAdmin']['UPLOADFILES']).

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 files are created with the correct character-set, and your HTML-templates render UTF-8.

Caution: The language file has to be stored in the same module path as the "filename namespaces" on the entities. So an entity stored in $lang['en_US']['AssetAdmin']['DETAILSTAB'] has to in the language file cms/lang/en_US.php, as the referenced file (AssetAdmin.php) is stored in the "cms" module.

Locales

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.

  Object
  i18n

Package: sapphire\misc
Author: Bernat Foj Capell <bernat@silverstripe.com>
See: http://doc.silverstripe.org/i18n
See: http://www.w3.org/TR/i18n-html-tech-lang
Used by: ``i18nTextCollector``
Located at sapphire/core/i18n.php

## Methods summary

`public static` | # `set_js_i18n( boolean $bool )` Use javascript i18n through the ss.i18n class (enabled by default). If set to TRUE, includes javascript requirements for the base library (sapphire/javascript/i18n.js) and all necessary lang files (e.g. sapphire/lang/de_DE.js) plus fallbacks to the default locale (e.g. sapphire/lang/en_US.js). If set to FALSE, only includes a stub implementation which is necessary. Mainly disabled to save bandwidth in a frontend context when website is in single language. Use javascript i18n through the ss.i18n class (enabled by default). If set to TRUE, includes javascript requirements for the base library (sapphire/javascript/i18n.js) and all necessary lang files (e.g. sapphire/lang/de_DE.js) plus fallbacks to the default locale (e.g. sapphire/lang/en_US.js). If set to FALSE, only includes a stub implementation which is necessary. Mainly disabled to save bandwidth in a frontend context when website is in single language. Caution: This flag gets overwritten in `LeftAndMain::init()` to enforce javascript i18n for the CMS interfaces. #### Parameters $bool bool $bool #### See Requirements::process_i18n_javascript()
`public static boolean` | # `get_js_i18n( )` #### Returns `boolean` bool
`public static` | # `set_date_format( string $format )` #### Parameters $format string ISO date format
`public static string` | # `get_date_format( )` #### Returns `string` ISO date format
`public static locale` | # `strftime( mixed $format = '%e %B %Y', mixed $time = null )` #### Returns `locale` specific formated date Special for russian months names TODO move months names to language file
`public static` | # `set_time_format( string $format )` #### Parameters $format string ISO time format
`public static string` | # `get_time_format( )` #### Returns `string` ISO time format
`public static string` | # `_t( string $entity, string $string = "", string $priority = 40, string $context = "" )` This is the main translator function. Returns the string defined by $class and $entity according to the currently set locale. This is the main translator function. Returns the string defined by $class and $entity according to the currently set locale. #### Parameters $entity string $entity Entity that identifies the string. It must be in the form "Namespace.Entity" where Namespace will be usually the class name where this string is used and Entity identifies the string inside the namespace. $string string $string The original string itself. In a usual call this is a mandatory parameter, but if you are reusing a string which has already been "declared" (using another call to this function, with the same class and entity), you can omit it. $priority string $priority Optional parameter to set a translation priority. If a string is widely used, should have a high priority (PR_HIGH), in this way translators will be able to prioritise this strings. If a string is rarely shown, you should use PR_LOW. You can use PR_MEDIUM as well. Leaving this field blank will be interpretated as a "normal" priority (less than PR_MEDIUM). $context string $context If the string can be difficult to translate by any reason, you can help translators with some more info using this param #### Returns `string` The translated string, according to the currently set locale `i18n::set_locale()`
`public static list` | # `get_common_languages( boolean $native = false )` Get a list of commonly used languages Get a list of commonly used languages #### Parameters $native boolean $native Use native names for languages instead of English ones #### Returns `list` of languages in the form 'code' => 'name'
`public static list` | # `get_common_locales( boolean $native = false )` Get a list of commonly used locales Get a list of commonly used locales #### Parameters $native boolean $native Use native names for locale instead of English ones #### Returns `list` of languages in the form 'code' => 'name'
`public static list` | # `get_locale_list( )` Get a list of locales (code => language and country) Get a list of locales (code => language and country) #### Returns `list` of languages in the form 'code' => 'name'
`public static array` | # `get_existing_translations( )` Searches the root-directory for module-directories (identified by having a _config.php on their first directory-level). Returns all found locales. Searches the root-directory for module-directories (identified by having a _config.php on their first directory-level). Returns all found locales. #### Returns `array` array
`public static Name` | # `get_language_name( mixed $code, boolean $native = false )` Get a name from a language code (two characters, e.g. "en"). Get a name from a language code (two characters, e.g. "en"). #### Parameters $code mixed $code Language code $native boolean $native If true, the native name will be returned #### Returns `Name` of the language #### See ``i18n::get_locale_name()``
`public static Name` | # `get_locale_name( mixed $code )` Get a name from a locale code (xx_YY). Get a name from a locale code (xx_YY). #### Parameters $code mixed $code locale code #### Returns `Name` of the locale #### See ``i18n::get_language_name()``
`public static Language` | # `get_language_code( mixed $name )` Get a code from an English language name Get a code from an English language name #### Parameters $name mixed $name Name of the language #### Returns `Language` code (if the name is not found, it'll return the passed name)
`public static Language` | # `get_tinymce_lang( )` Get the current tinyMCE language Get the current tinyMCE language #### Returns `Language` Language
`public static array` | # `get_translatable_modules( )` Searches the root-directory for module-directories (identified by having a _config.php on their first directory-level and a language-file with the default locale in the /lang-subdirectory). Searches the root-directory for module-directories (identified by having a _config.php on their first directory-level and a language-file with the default locale in the /lang-subdirectory). #### Returns `array` array
`public static string` | # `get_lang_from_locale( string $locale )` Returns the "short" language name from a locale, e.g. "en_US" would return "en". This conversion is determined internally by the `i18n::$tinymce_lang` lookup table. If no match can be found in this lookup, the characters before the underscore ("_") are returned. Returns the "short" language name from a locale, e.g. "en_US" would return "en". This conversion is determined internally by the `i18n::$tinymce_lang` lookup table. If no match can be found in this lookup, the characters before the underscore ("_") are returned. #### Parameters $locale string $locale E.g. "en_US" #### Returns `string` Short language code, e.g. "en"
`public static string` | # `get_locale_from_lang( string $lang )` Provides you "likely locales" for a given "short" language code. This is a guess, as we can't disambiguate from e.g. "en" to "en_US" - it could also mean "en_UK". Based on the Unicode CLDR project. Provides you "likely locales" for a given "short" language code. This is a guess, as we can't disambiguate from e.g. "en" to "en_US" - it could also mean "en_UK". Based on the Unicode CLDR project. #### Parameters $lang string $lang Short language code, e.g. "en" #### Returns `string` Long locale, e.g. "en_US" #### See http://www.unicode.org/cldr/data/charts/supplemental/likely_subtags.html
`public static string` | # `convert_rfc1766( string $locale )` Gets a RFC 1766 compatible language code, e.g. "en-US". Gets a RFC 1766 compatible language code, e.g. "en-US". #### Parameters $locale string $locale #### Returns `string` string #### See http://www.ietf.org/rfc/rfc1766.txt http://tools.ietf.org/html/rfc2616#section-3.10
`public static string` | # `get_owner_module( string $name )` Given a file name (a php class name, without the .php ext, or a template name, including the .ss extension) this helper function determines the module where this file is located Given a file name (a php class name, without the .php ext, or a template name, including the .ss extension) this helper function determines the module where this file is located #### Parameters $name string $name php class name or template file name (including *.ss extension) #### Returns `string` Module where the file is located
`public static boolean` | # `validate_locale( mixed $locale )` Validates a "long" locale format (e.g. "en_US") by checking it against `i18n::$all_locales`. Validates a "long" locale format (e.g. "en_US") by checking it against `i18n::$all_locales`. To add a locale to `i18n::$all_locales`, use the following example in your mysite/_config.php:
    i18n::$allowed_locales['xx_XX'] = '<Language name>';
Note: Does not check for $allowed_locales. #### Returns `boolean` boolean
`public static` | # `set_locale( string $locale )` Set the current locale, used as the default for any localized classes, such as `FormField` or `DBField` instances. Locales can also be persisted in Member->Locale, for example in the `CMSMain` interface the Member locale overrules the global locale value set here. Set the current locale, used as the default for any localized classes, such as `FormField` or `DBField` instances. Locales can also be persisted in Member->Locale, for example in the `CMSMain` interface the Member locale overrules the global locale value set here. See Translatable::set_locale(). #### Parameters $locale string $locale Locale to be set. See http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html for a list of possible locales.
`public static string` | # `get_locale( )` Get the current locale. Used by `Member::populateDefaults()` Get the current locale. Used by `Member::populateDefaults()` #### Returns `string` Current locale in the system
`public static` | # `set_default_lang( mixed $lang )` #### Deprecated 2.4 Use Translatable::set_default_locale() or i18n::set_default_locale() #### Parameters $lang $lang String
`public static String` | # `default_lang( )` #### Deprecated 2.4 Use Translatable::default_locale() or i18n::default_locale() #### Returns `String` String
`public static String` | # `default_locale( )` This is the "fallback locale", in case resources with the "current locale" (set through `i18n::set_locale()`) can't be found. This is the "fallback locale", in case resources with the "current locale" (set through `i18n::set_locale()`) can't be found. If you just want to globally read/write a different locale (e.g. in a CMS interface), please use `i18n::get_locale()` and `i18n::set_locale()` instead. For example, `Requirements::add_i18n_javascript()` and `i18n::include_by_class()` use this "fallback locale" value to include fallback language files. #### Returns `String` String
`public static` | # `set_default_locale( String $locale )` See `i18n::default_locale()` for usage. See `i18n::default_locale()` for usage. #### Parameters $locale String $locale
`public static` | # `enable( )` Enables the multilingual content feature (proxy for Translatable::enable()). Enables the multilingual content feature (proxy for Translatable::enable()). #### Deprecated 2.4 Use Object::add_extension('Page', 'Translatable');
`public static` | # `disable( )` Disable the multilingual content feature (proxy for Translatable::disable()) Disable the multilingual content feature (proxy for Translatable::disable()) #### Deprecated 2.4 Use Object::add_extension('Page', 'Translatable');
`public static` | # `include_locale_file( string $module, string $locale )` Include a locale file determined by module name and locale Include a locale file determined by module name and locale #### Parameters $module string $module Module that contains the locale file $locale string $locale Locale to be loaded
`public static` | # `include_by_locale( string $locale, boolean $load_plugins = true, boolean $force_load = false )` Includes all available language files for a certain defined locale Includes all available language files for a certain defined locale #### Parameters $locale string $locale All resources from any module in locale $locale will be loaded $load_plugins boolean $load_plugins If true (default), load extra translations from registered plugins $force_load boolean $force_load If true (not default), we force the inclusion. Generally this should be off for performance, but enabling this is useful for interfaces like CustomTranslationAdmin which need to load more than the usual locales, and may need to reload them.
`public static` | # `include_by_class( string $class )` Given a class name (a "locale namespace"), will search for its module and, if available, will load the resources for the currently defined locale. If not available, the original English resource will be loaded instead (to avoid blanks) Given a class name (a "locale namespace"), will search for its module and, if available, will load the resources for the currently defined locale. If not available, the original English resource will be loaded instead (to avoid blanks) #### Parameters $class string $class Resources for this class will be included, according to the set locale.
`public` | # `removelang( )` This method will delete every SiteTree instance in the given language This method will delete every SiteTree instance in the given language
`public static` | # `register_plugin( mixed $name, mixed $callback, integer $priority = 10 )` Register a named translation plug-in function. Plug-ins are assumed to be registered before any call to _t. If registered after a call to _t for a given local, it will not be called. Register a named translation plug-in function. Plug-ins are assumed to be registered before any call to _t. If registered after a call to _t for a given local, it will not be called. #### Parameters $name $name String A unique name for the translation plug-in. If the plug-in is already registered, it is replaced, including if its a different priority. $callback $callback A callback function as given to call_user_func_array. $priority int $priority An integer priority, default 10. #### Throws ``Exception`` Exception
`public static `Boolean`` | # `unregister_plugin( mixed $name )` Unregister a plugin by name. Unregister a plugin by name. #### Parameters $name $name String Name of previously registered plugin #### Returns ``Boolean`` Returns true if remove, false if not.
`public static` | # `plugins_load( mixed $locale )` Load any translations from registered plugins. Merges them directly into $lang. Load any translations from registered plugins. Merges them directly into $lang. #### Parameters $locale $local
`public static` | # `merge_locale_data( mixed $locale, mixed $extra )` Merge an extra of language translations into $lang[$locale]. We'd use array_merge_recursive, except it doesn't work for translations that specify priorities and comments, because they are indexed by number. Merge an extra of language translations into $lang[$locale]. We'd use array_merge_recursive, except it doesn't work for translations that specify priorities and comments, because they are indexed by number. #### Parameters $locale $locale String The locale we are merging into $extra $extra Array An array of [locale][class][entity]=> translation, keyed on entity, that are to be merged for this locale.

### Methods inherited from Object

`__call()`, `__construct()`, `__toString()`, `__wakeup()`, `addMethodsFrom()`, `addStaticVars()`, `addWrapperMethod()`, `add_extension()`, `add_static_var()`, `allMethodNames()`, `cacheToFile()`, `cacheToFileWithArgs()`, `clearCache()`, `combined_static()`, `create()`, `createMethod()`, `create_from_string()`, `defineMethods()`, `exists()`, `extInstance()`, `extend()`, `getCustomClass()`, `getExtensionInstance()`, `getExtensionInstances()`, `get_extensions()`, `get_static()`, `hasExtension()`, `hasMethod()`, `has_extension()`, `invokeWithExtensions()`, `is_a()`, `loadCache()`, `parentClass()`, `parse_class_spec()`, `remove_extension()`, `sanitiseCachename()`, `saveCache()`, `set_stat()`, `set_static()`, `set_uninherited()`, `stat()`, `strong_create()`, `uninherited()`, `uninherited_static()`, `useCustomClass()`

### Magic methods summary

## Properties summary

`protected static string` | $current_locale | # This static variable is used to store the current defined locale. This static variable is used to store the current defined locale.
`protected static string` | $default_locale | #
`protected static boolean` | $js_i18n | #
`protected static string` | $date_format | #
`protected static string` | $time_format | #
`public static array` | $all_locales | # An exhaustive list of possible locales (code => language and country) An exhaustive list of possible locales (code => language and country)
`public static array` | $common_languages | # $common_languages A list of commonly used languages, in the form langcode => array( EnglishName, NativeName) $common_languages A list of commonly used languages, in the form langcode => array( EnglishName, NativeName)
`public static array` | $common_locales | # $common_locales Sorted alphabtically by the common language name, not the locale key. $common_locales Sorted alphabtically by the common language name, not the locale key.
`public static array` | $tinymce_lang | #
`public static array` | $likely_subtags | # $likely_subtags Provides you "likely locales" for a given "short" language code. This is a guess, as we can't disambiguate from e.g. "en" to "en_US" - it could also mean "en_UK". $likely_subtags Provides you "likely locales" for a given "short" language code. This is a guess, as we can't disambiguate from e.g. "en" to "en_US" - it could also mean "en_UK". #### See http://www.unicode.org/cldr/data/charts/supplemental/likely_subtags.html

### Properties inherited from Object

`$class`, `$extension_instances`, `$extensions`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -