class i18n implements TemplateGlobalProvider (View source)

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

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

Properties

static private string $default_locale
static private string $date_format

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.

static private string $time_format

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.

static private array $plurals

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.

static private bool $missing_default_warning

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, .....).

mixed
stat(string $name) deprecated

Get inherited config value

mixed
uninherited(string $name)

Gets the uninherited value for the given config option

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

Update the config value for a given property

static string
_t(string $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

static Config_ForClass config()

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

Return Value

Config_ForClass

mixed stat(string $name) deprecated

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

Get inherited config value

Parameters

string $name

Return Value

mixed

mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

$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

static string _t(string $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

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.

$arg

Return Value

string

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

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

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

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

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.

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

Temporarily set the locale while invoking a callback

Parameters

string $locale
callable $callback

Return Value

mixed

static string get_locale()

Get the current locale.

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

Return Value

string

Current locale in the system

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/

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)

static MessageProvider getMessageProvider()

Return Value

MessageProvider

static Locales getData()

Localisation data source

Return Value

Locales

static Sources getSources()

Get data sources for localisation strings

Return Value

Sources