1. class
  2. SilverStripe
  3. \
  4. i18n
  5. \
  6. i18n

i18n

class i18n implements TemplateGlobalProvider

Base-class for storage and retrieval of translated entities.

Please see the 'translatable' module for managing translations of database-content.

Usage

PHP: _t('MyNamespace.MYENTITY', 'My default natural language value'); _t('MyNamespace.MYENTITY', 'My default natural language value', 'My explanatory context'); _t('MyNamespace.MYENTITY', 'Counting {number} things', ['number' => 42]);

Templates: <%t MyNamespace.MYENTITY 'My default natural language value' %> <%t MyNamespace.MYENTITY 'Counting {count} things' count=$ThingsCount %>

Javascript (see framework/client/dist/js/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 the 'translatable' module 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.

Traits

Configurable
Provides extensions to this object to integrate it with standard config API methods.

Config options

default_locale string
date_format string System-wide date format. Will be overruled for CMS UI display by the format defaults inferred from the browser as well as any user-specific locale preferences.
time_format string System-wide time format. Will be overruled for CMS UI display by the format defaults inferred from the browser as well as any user-specific locale preferences.
plurals array Map of rails plurals into standard order (fewest to most) Note: Default locale only supplies one|other, but non-default locales can specify custom plurals.
missing_default_warning bool Warn if _t() invoked without a default.

Methods

static Config_ForClass
config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .

from Configurable
mixed
stat(string $name) deprecated

Get inherited config value

from Configurable
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

from Configurable
$this
set_stat(string $name, mixed $value) deprecated

Update the config value for a given property

from Configurable
static string
_t($entity, $arg = null)

This is the main translator function. Returns the string defined by $entity according to the currently set locale.

static array
parse_plurals(string $string)

Split plural string into standard CLDR array form.

static string
encode_plurals(array $plurals)

Convert CLDR array plural form to | pipe-delimited string.

static string
get_closest_translation(string $locale)

Matches a given locale with the closest translation available in the system

static string
convert_rfc1766(string $locale)

Gets a RFC 1766 compatible language code, e.g. "en-US".

static 
set_locale(string $locale)

Set the current locale, used as the default for any localized classes, such as {@link FormField} or {@link DBField} instances. Locales can also be persisted in {@link Member->Locale}, for example in the {@link CMSMain} interface the Member locale overrules the global locale value set here.

static mixed
with_locale(string $locale, callable $callback)

Temporarily set the locale while invoking a callback

static string
get_locale()

Get the current locale.

static string
get_script_direction(string $locale = null)

Returns the script direction in format compatible with the HTML "dir" attribute.

static array
get_template_global_variables()

Called by SSViewer to get a list of global variables to expose to the template, the static method to call on this class to get the value for those variables, and the class to use for casting the returned value for use in a template

static MessageProvider
getMessageProvider()

No description

static Locales
getData()

Localisation data source

static Sources
getSources()

Get data sources for localisation strings

Details

in Configurable at line 20
static Config_ForClass config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .

....).

Return Value

Config_ForClass

in Configurable at line 32
mixed stat(string $name) deprecated

deprecated 5.0 Use ->config()->get() instead

Get inherited config value

Parameters

string $name

Return Value

mixed

in Configurable at line 44
mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

in Configurable at line 57
$this set_stat(string $name, mixed $value) deprecated

deprecated 5.0 Use ->config()->set() instead

Update the config value for a given property

Parameters

string $name
mixed $value

Return Value

$this

at line 159
static string _t($entity, $arg = null)

This is the main translator function. Returns the string defined by $entity according to the currently set locale.

Also supports pluralisation of strings. Pass in a count argument, as well as a default value with | pipe-delimited options for each plural form.

Parameters

$entity
$arg

Return Value

string

at line 239
static array parse_plurals(string $string)

Split plural string into standard CLDR array form.

A string is considered a pluralised form if it has a {count} argument, and a single | pipe-delimiting character.

Note: Only splits in the default (en) locale as the string form contains limited metadata.

Parameters

string $string Input string

Return Value

array List of plural forms, or empty array if not plural

at line 258
static string encode_plurals(array $plurals)

Convert CLDR array plural form to | pipe-delimited string.

Unlike parse_plurals, this supports all locale forms (not just en)

Parameters

array $plurals

Return Value

string Delimited string, or null if not plurals

at line 276
static string get_closest_translation(string $locale)

Matches a given locale with the closest translation available in the system

Parameters

string $locale locale code

Return Value

string Locale of closest available translation, if available

at line 304
static string convert_rfc1766(string $locale)

Gets a RFC 1766 compatible language code, e.g. "en-US".

Parameters

string $locale

Return Value

string

See also

http://www.ietf.org/rfc/rfc1766.txt
http://tools.ietf.org/html/rfc2616#section-3.10

at line 320
static set_locale(string $locale)

Set the current locale, used as the default for any localized classes, such as {@link FormField} or {@link DBField} instances. Locales can also be persisted in {@link Member->Locale}, for example in the {@link CMSMain} interface the Member locale overrules the global locale value set here.

Parameters

string $locale Locale to be set. See http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html for a list of possible locales.

at line 334
static mixed with_locale(string $locale, callable $callback)

Temporarily set the locale while invoking a callback

Parameters

string $locale
callable $callback

Return Value

mixed

at line 351
static string get_locale()

Get the current locale.

Used by {@link Member::populateDefaults()}

Return Value

string Current locale in the system

at line 366
static string get_script_direction(string $locale = null)

Returns the script direction in format compatible with the HTML "dir" attribute.

Parameters

string $locale Optional locale incl. region (underscored)

Return Value

string "rtl" or "ltr"

See also

http://www.w3.org/International/tutorials/bidi-xhtml/

at line 371
static array get_template_global_variables()

Called by SSViewer to get a list of global variables to expose to the template, the static method to call on this class to get the value for those variables, and the class to use for casting the returned value for use in a template

If the method to call is not included for a particular template variable, a method named the same as the template variable will be called

If the casting class is not specified for a particular template variable, ViewableData::$default_cast is used

The first letter of the template variable is case-insensitive. However the method name is always case sensitive.

Return Value

array Returns an array of items. Each key => value pair is one of three forms: - template name (no key) - template name => method name - template name => array(), where the array can contain these key => value pairs - "method" => method name - "casting" => casting class to use (i.e., Varchar, HTMLFragment, etc)

at line 383
static MessageProvider getMessageProvider()

Return Value

MessageProvider

at line 393
static Locales getData()

Localisation data source

Return Value

Locales

at line 403
static Sources getSources()

Get data sources for localisation strings

Return Value

Sources