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

Packages

Classes

Class i18n

Methods summary

Parameters

See

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Parameters

Returns

See

Parameters

Returns

See

Parameters

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

See

Parameters

Returns

See

Parameters

Returns

Returns

Parameters

Returns

Deprecated

Parameters

Deprecated

Returns

Returns

Parameters

Deprecated

Deprecated

Parameters

Parameters

Parameters

Parameters

Throws

Parameters

Returns

Parameters

Parameters

Methods inherited from Object

Magic methods summary

Properties summary

See

Properties inherited from Object