class i18n implements TemplateGlobalProvider (View source)

Base-class for storage and retrieval of translated entities.

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

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.

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.

default_plurals array

Plural forms in default (en) locale

missing_default_warning bool

Warn if _t() invoked without a default.

Properties

protected static string $current_locale

This static variable is used to store the current defined locale.

Methods

public static 
config()

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

public
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

public static 
string
_t(string $entity, mixed $arg = null)

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

public static 
array
parse_plurals(string $string)

Split plural string into standard CLDR array form.

public static 
string
encode_plurals(array $plurals)

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

public static 
string
get_closest_translation(string $locale)

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

public static 
string
convert_rfc1766(string $locale)

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

public static 
set_locale(string $locale)

Set the current locale, used as the default for any localized classes, such as FormField} or {@link 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.

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

Temporarily set the locale while invoking a callback

public static 
string
get_locale()

Get the current locale.

public static 
string
get_script_direction(string $locale = null)

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

public 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

public static 
getMessageProvider()

No description

public static 
getData()

Localisation data source

public static 
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 uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

static string _t(string $entity, mixed $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.

mixed $arg

Additional arguments are parsed as such:

  • Next string argument is a default. Pass in a | pipe-delimited value with {count} to do pluralisation.
  • Any other string argument after default is context for i18nTextCollector
  • Any array argument in any order is an injection parameter list. Pass in a count injection parameter to pluralise.

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 FormField} or {@link 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.

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 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 => [], 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()

No description

Return Value

MessageProvider

static Locales getData()

Localisation data source

Return Value

Locales

static Sources getSources()

Get data sources for localisation strings

Return Value

Sources