i18n
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
Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).
Gets the uninherited value for the given config option
This is the main translator function. Returns the string defined by $entity according to the currently set locale.
Split plural string into standard CLDR array form.
Convert CLDR array plural form to | pipe-delimited string.
Matches a given locale with the closest translation available in the system
Gets a RFC 1766 compatible language code, e.g. "en-US".
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.
Temporarily set the locale while invoking a callback
Get the current locale.
Returns the script direction in format compatible with the HTML "dir" attribute.
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
No description
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, .....).
mixed
stat(string $name)
deprecated
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
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.
Also supports pluralisation of strings. Pass in a count argument, as well as a
default value with | pipe-delimited options for each plural form.
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.
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)
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.
Used by {@link Member::populateDefaults()}
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
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.
static MessageProvider
getMessageProvider()
static Locales
getData()
Localisation data source
static Sources
getSources()
Get data sources for localisation strings