2014-09-28 05:59:48 +02:00
title: i18n
2014-09-21 02:07:58 +02:00
summary: Display templates and PHP code in different languages based on the preferences of your website users.
2011-02-07 07:48:44 +01:00
# i18n
2011-03-08 22:05:51 +01:00
The i18n class (short for "internationalization") in SilverStripe enables you to display templates and PHP code in
2011-02-07 07:48:44 +01:00
different languages based on your global settings and the preferences of your website users. This process is also known
as l10n (short for "localization").
2014-09-28 05:59:48 +02:00
For translating any content managed through the CMS or stored in the database, please use the
[translatable ](http://github.com/silverstripe/silverstripe-translatable ) module.
2011-02-07 07:48:44 +01:00
2014-09-28 05:59:48 +02:00
This page aims to describe the low-level functionality of the i18n API. It targets developers who:
2011-02-07 07:48:44 +01:00
2014-09-28 05:59:48 +02:00
* Are involved in creating templates in different languages.
* Want to build their own modules with i18n capabilities.
* Want to make their PHP-code (e.g. form labels) i18n-ready
2011-02-07 07:48:44 +01:00
## Usage
### Enabling i18n
The i18n class is enabled by default.
### Setting the locale
2016-02-17 22:21:59 +01:00
To set the locale you just need to call [api:i18n::set_locale()] passing, as a parameter, the name of the locale that
2014-09-28 05:59:48 +02:00
you want to set.
2011-02-07 07:48:44 +01:00
:::php
2014-09-28 05:59:48 +02:00
// mysite/_config.php
i18n::set_locale('de_DE'); // Setting the locale to German (Germany)
i18n::set_locale('ca_AD'); // Setting to Catalan (Andorra)
2011-02-07 07:48:44 +01:00
Once we set a locale, all the calls to the translator function will return strings according to the set locale value, if
2014-09-28 05:59:48 +02:00
these translations are available. See [unicode.org ](http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html )
for a complete listing of available locales.
2011-02-07 07:48:44 +01:00
### Getting the locale
2016-02-17 22:21:59 +01:00
As you set the locale you can also get the current value, just by calling [api:i18n::get_locale()].
2011-02-07 07:48:44 +01:00
### Declaring the content language in HTML {#declaring_the_content_language_in_html}
To let browsers know which language they're displaying a document in, you can declare a language in your template.
:::html
//'Page.ss' (HTML)
< html lang = "$ContentLocale" >
2014-09-21 02:07:58 +02:00
2011-02-07 07:48:44 +01:00
//'Page.ss' (XHTML)
< html lang = "$ContentLocale" xml:lang = "$ContentLocale" xmlns = "http://www.w3.org/1999/xhtml" >
2014-09-28 05:59:48 +02:00
Setting the `<html>` attribute is the most commonly used technique. There are other ways to specify content languages
2011-02-07 07:48:44 +01:00
(meta tags, HTTP headers), explained in this [w3.org article ](http://www.w3.org/International/tutorials/language-decl/ ).
2014-09-21 02:07:58 +02:00
You can also set the [script direction ](http://www.w3.org/International/questions/qa-scripts ),
2013-10-14 11:27:53 +02:00
which is determined by the current locale, in order to indicate the preferred flow of characters
and default alignment of paragraphs and tables to browsers.
:::html
< html lang = "$ContentLocale" dir = "$i18nScriptDirection" >
2011-02-07 07:48:44 +01:00
### Date and time formats
2014-09-21 02:07:58 +02:00
Formats can be set globally in the i18n class. These settings are currently only picked up by the CMS, you'll need
2011-02-07 07:48:44 +01:00
to write your own logic for any frontend output.
:::php
2013-03-27 20:42:46 +01:00
Config::inst()->update('i18n', 'date_format', 'dd.MM.YYYY');
Config::inst()->update('i18n', 'time_format', 'HH:mm');
2011-02-07 07:48:44 +01:00
2016-02-17 22:21:59 +01:00
Most localization routines in SilverStripe use the [Zend_Date API ](http://framework.zend.com/manual/1.12/en/zend.date.overview.html ).
2011-02-07 07:48:44 +01:00
This means all formats are defined in
2016-02-17 22:21:59 +01:00
[ISO date format ](http://framework.zend.com/manual/1.12/en/zend.date.constants.html ),
2011-02-07 07:48:44 +01:00
not PHP's built-in [date() ](http://nz.php.net/manual/en/function.date.php ).
2013-03-27 20:42:46 +01:00
### Language Names
SilverStripe comes with a built-in list of common languages, listed by locale and region.
2015-02-28 01:09:15 +01:00
They can be accessed via the `i18n.common_languages` and `i18n.common_locales` [config setting ](/developer_guides/configuration ).
2013-03-27 20:42:46 +01:00
In order to add a value, add the following to your `config.yml` :
:::yml
i18n:
2014-05-25 21:09:06 +02:00
common_locales:
2013-03-27 20:42:46 +01:00
de_CGN:
name: German (Cologne)
native: Kölsch
2014-05-25 21:09:06 +02:00
Similarly, to change an existing language label, you can overwrite one of these keys:
2014-09-21 02:07:58 +02:00
2014-05-25 21:09:06 +02:00
:::yml
2013-03-27 20:42:46 +01:00
i18n:
2014-05-25 21:09:06 +02:00
common_locales:
2013-03-27 20:42:46 +01:00
en_NZ:
native: Niu Zillund
2011-11-14 12:26:51 +01:00
### i18n in URLs
2014-09-21 02:07:58 +02:00
By default, URLs for pages in SilverStripe (the `SiteTree->URLSegment` property)
are automatically reduced to the allowed allowed subset of ASCII characters.
2013-01-09 01:41:40 +01:00
If characters outside this subset are added, they are either removed or (if possible) "transliterated".
2011-11-14 12:26:51 +01:00
This describes the process of converting from one character set to another
2014-09-21 02:07:58 +02:00
while keeping characters recognizeable. For example, vowels with french accents
2011-11-14 12:26:51 +01:00
are replaced with their base characters, `pâté` becomes `pate` .
2016-09-05 07:54:45 +02:00
It is advisable to set the `SS_Transliterator.use_iconv` setting to true via config for systems
which have `iconv` extension enabled and configured.
See [the php documentation on iconv ](http://php.net/manual/en/book.iconv.php ) for more information.
2011-11-14 12:26:51 +01:00
In order to allow for so called "multibyte" characters outside of the ASCII subset,
2013-03-21 19:48:54 +01:00
limit the character filtering in the underlying configuration setting,
by setting `URLSegmentFilter.default_use_transliterator` to `false` in your YAML configuration.
2011-11-14 12:26:51 +01:00
Please refer to [W3C: Introduction to IDN and IRI ](http://www.w3.org/International/articles/idn-and-iri/ ) for more details.
2011-02-07 07:48:44 +01:00
### i18n in Form Fields
Date- and time related form fields support i18n ([api:DateField], [api:TimeField], [api:DatetimeField]).
:::php
i18n::set_locale('ca_AD');
$field = new DateField(); // will automatically set date format defaults for 'ca_AD'
$field->setLocale('de_DE'); // will not update the date formats
2011-05-25 11:24:33 +02:00
$field->setConfig('dateformat', 'dd. MMMM YYYY'); // sets typical 'de_DE' date format, shows as "23. Juni 1982"
2014-09-21 02:07:58 +02:00
2013-03-21 19:48:54 +01:00
Defaults can be applied globally for all field instances through the `DateField.default_config`
2015-02-28 01:09:15 +01:00
and `TimeField.default_config` [configuration arrays ](/developer_guides/configuration ).
2013-03-21 19:48:54 +01:00
If no 'locale' default is set on the field, [api:i18n::get_locale()] will be used.
2011-05-25 11:24:33 +02:00
2013-01-09 01:41:40 +01:00
**Important:** Form fields in the CMS are automatically configured according to the profile settings for the logged-in user (`Member->Locale`, `Member->DateFormat` and `Member->TimeFormat` ). This means that in most cases,
2011-05-25 11:24:33 +02:00
fields created through [api:DataObject::getCMSFields()] will get their i18n settings from a specific member
2011-02-07 07:48:44 +01:00
2014-09-21 02:07:58 +02:00
The [api:DateField] API can be enhanced by JavaScript, and comes with
2011-05-25 11:24:33 +02:00
[jQuery UI datepicker ](http://jqueryui.com/demos/datepicker/ ) capabilities built-in.
The field tries to translate the date formats and locales into a format compatible with jQuery UI
(see [api:DateField_View_JQuery::$locale_map_] and [api:DateField_View_JQuery::convert_iso_to_jquery_format()]).
:::php
2014-09-21 02:07:58 +02:00
$field = new DateField();
2011-05-25 11:24:33 +02:00
$field->setLocale('de_AT'); // set Austrian/German locale
$field->setConfig('showcalendar', true);
$field->setConfig('jslocale', 'de'); // jQuery UI only has a generic German localization
$field->setConfig('dateformat', 'dd. MMMM YYYY'); // will be transformed to 'dd. MM yy' for jQuery
2011-02-07 07:48:44 +01:00
2012-04-14 00:16:30 +02:00
## Translating text
2011-02-07 07:48:44 +01:00
Adapting a module to make it localizable is easy with SilverStripe. You just need to avoid hardcoding strings that are
language-dependent and use a translator function call instead.
:::php
// without i18n
echo "This is a string";
// with i18n
echo _t("Namespace.Entity","This is a string");
2013-01-09 01:41:40 +01:00
All strings passed through the `_t()` function will be collected in a separate language table (see [Collecting text ](#collecting-text )), which is the starting point for translations.
2011-02-07 07:48:44 +01:00
### The _t() function
2014-09-21 02:07:58 +02:00
The `_t()` function is the main gateway to localized text, and takes four parameters, all but the first being optional.
2013-01-09 01:41:40 +01:00
It can be used to translate strings in both PHP files and template files. The usage for each case is described below.
2011-02-07 07:48:44 +01:00
2017-01-18 04:58:48 +01:00
* **$entity:** Unique identifier, composed by a namespace and an entity name, with a dot
separating them. Both are arbitrary names, although by convention we use the name of
the containing class or template. Use this identifier to reference the same translation
elsewhere in your code.
* **$default:** The original language string to be translated. This should be declared
whenever used, and will get picked up the [text collector ](#collecting-text ).
2017-01-25 04:35:13 +01:00
* **$string:** (optional) Natural language comment (particularly short phrases and individual words)
are very context dependent. This parameter allows the developer to convey this information
to the translator.
2017-01-18 04:58:48 +01:00
* **$injection::** (optional) An array of injecting variables into the second parameter
2017-01-25 04:35:13 +01:00
2017-01-18 04:58:48 +01:00
## Pluralisation
i18n also supports locale-respective pluralisation rules. Many languages have more than two plural forms,
unlike English which has two only; One for the singular, and another for any other number.
More information on what forms these plurals can take for various locales can be found on the
[CLDR documentation ](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html )
2017-01-25 04:35:13 +01:00
The ability to pluralise strings is provided through the `i18n::_t` method when supplied with a
`{count}` argument and `|` pipe-delimiter provided with the default string.
Plural forms can also be explicitly declared via the i18nEntityProvider interface in array-format
with both a 'one' and 'other' key (as per the CLDR for the default `en` language).
2017-01-18 04:58:48 +01:00
For instance, this is an example of how to correctly declare pluralisations for an object
:::php
class MyObject extends DataObject, implements i18nEntityProvider
{
public function provideI18nEntities()
{
return [
'MyObject.SINGULAR_NAME' => 'object',
'MyObject.PLURAL_NAME' => 'objects',
'MyObject.PLURALS' => [
'one' => 'An object',
'other' => '{count} objects',
],
];
}
}
In YML format this will be expressed as the below. This follows the
[ruby i18n convention ](guides.rubyonrails.org/i18n.html#pluralization ) for plural forms.
:::yaml
en:
MyObject:
SINGULAR_NAME: 'object'
PLURAL_NAME: 'objects'
PLURALS:
one: 'An object',
other: '{count} objects'
Note: i18nTextCollector support for pluralisation is not yet available.
Please ensure that any required plurals are exposed via provideI18nEntities.
2011-02-07 07:48:44 +01:00
2013-01-09 01:41:40 +01:00
#### Usage in PHP Files
2011-02-07 07:48:44 +01:00
:::php
2014-09-21 02:07:58 +02:00
2013-01-09 01:41:40 +01:00
// Simple string translation
_t('LeftAndMain.FILESIMAGES','Files & Images');
2014-09-21 02:07:58 +02:00
2013-01-09 01:41:40 +01:00
// Using injection to add variables into the translated strings.
2012-04-18 08:14:03 +02:00
_t('CMSMain.RESTORED',
"Restored {value} successfully",
array('value' => $itemRestored)
);
2017-01-25 04:35:13 +01:00
// Plurals are invoked via a `|` pipe-delimeter with a {count} argument
_t('MyObject.PLURALS', 'An object|{count} objects', [ 'count' => '$count ]);
2011-02-07 07:48:44 +01:00
2017-01-18 04:58:48 +01:00
2013-01-09 01:41:40 +01:00
#### Usage in Template Files
2011-02-07 07:48:44 +01:00
2013-01-09 01:41:40 +01:00
< div class = "hint" markdown = '1' >
The preferred template syntax has changed somewhat since [version 2.x ](http://doc.silverstripe.org/framework/en/2.4/topics/i18n#usage-2 ).
< / div >
2011-02-07 07:48:44 +01:00
2013-01-09 01:41:40 +01:00
In `.ss` template files, instead of `_t(params)` the syntax `<%t params %>` is used. The syntax for passing parameters to the function is quite different to
the PHP version of the function.
2011-02-07 07:48:44 +01:00
2013-01-09 01:41:40 +01:00
* Parameters are space separated, not comma separated
* The original language string and the natural language comment parameters are separated by ` on ` .
* The final parameter (which is an array in PHP) is passed as a space separated list of key/value pairs.
2011-02-07 07:48:44 +01:00
:::ss
2013-01-09 01:41:40 +01:00
// Simple string translation
< %t Namespace.Entity "String to translate" %>
2014-09-21 02:07:58 +02:00
2013-01-09 01:41:40 +01:00
// Using injection to add variables into the translated strings (note that $Name and $Greeting must be available in the current template scope).
< %t Header.Greeting "Hello {name} {greeting}" name=$Name greeting=$Greeting %>
2017-01-18 04:58:48 +01:00
2017-01-25 04:35:13 +01:00
// Plurals follow the same convention, required a `|` and `{count}` in the default string
< %t MyObject.PLURALS 'An item|{count} items' count=$Count %>
2017-01-18 04:58:48 +01:00
2014-09-21 02:07:58 +02:00
2013-09-07 16:10:52 +02:00
#### Caching in Template Files with locale switching
2014-09-28 05:59:48 +02:00
When caching a `<% loop %>` or `<% with %>` with `<%t params %>` . It is important to add the Locale to the cache key
otherwise it won't pick up locale changes.
2013-09-07 16:10:52 +02:00
2014-09-28 05:59:48 +02:00
:::ss
2013-09-07 16:10:52 +02:00
< % cached 'MyIdentifier', $CurrentLocale %>
< % loop $Students %>
$Name
< % end_loop %>
< % end_cached %>
2011-02-07 07:48:44 +01:00
## Collecting text
2014-09-28 05:59:48 +02:00
To collect all the text in code and template files we have just to visit: `http://localhost/dev/tasks/i18nTextCollectorTask`
2011-02-07 07:48:44 +01:00
Text collector will then read the files, build the master string table for each module where it finds calls to the
underscore function, and tell you about the created files and any possible entity redeclaration.
2014-09-28 05:59:48 +02:00
If you want to run the text collector for just one module you can use the 'module' parameter:
2013-10-23 21:24:52 +02:00
`http://localhost/dev/tasks/i18nTextCollectorTask/?module=cms`
2011-02-07 07:48:44 +01:00
2013-01-09 01:41:40 +01:00
< div class = "hint" markdown = '1' >
2016-01-14 11:59:53 +01:00
You'll need to install PHPUnit to run the text collector (see [testing-guide ](/developer_guides/testing )).
2011-03-08 22:05:51 +01:00
< / div >
2011-02-07 07:48:44 +01:00
2013-04-09 02:39:45 +02:00
## Module Priority
The order in which i18n strings are loaded from modules can be quite important, as it is pretty common for a site
developer to want to override the default i18n strings from time to time. Because of this, you will sometimes need to specify the loading priority of i18n modules.
By default, the language files are loaded from modules in this order:
* Your project (as defined in the `$project` global)
* admin
* framework
* All other modules
This default order is configured in `framework/_config/i18n.yml` . This file specifies two blocks of module ordering: `basei18n` , listing admin, and framework, and `defaulti18n` listing all other modules.
2014-09-21 02:07:58 +02:00
To create a custom module order, you need to specify a config fragment that inserts itself either after or before those items. For example, you may have a number of modules that have to come after the framework/admin, but before anyhting else. To do that, you would use this
2013-04-09 02:39:45 +02:00
---
Name: customi18n
Before: 'defaulti18n'
---
i18n:
module_priority:
- module1
- module2
- module3
The config option being set is `i18n.module_priority` , and it is a list of module names.
There are a few special cases:
* If not explicitly mentioned, your project is put as the first module.
* The module name `other_modules` can be used as a placeholder for all modules that aren't
specifically mentioned.
2013-01-09 01:41:40 +01:00
## Language definitions
2012-04-14 00:16:30 +02:00
Each module can have one language table per locale, stored by convention in the `lang/` subfolder.
2016-02-17 22:21:59 +01:00
The translation is powered by [Zend_Translate ](http://framework.zend.com/manual/current/en/modules/zend.i18n.translating.html ),
2012-04-14 00:16:30 +02:00
which supports different translation adapters, dealing with different storage formats.
2011-02-07 07:48:44 +01:00
2017-01-18 04:58:48 +01:00
By default, SilverStripe uses a YAML format which is loaded via the
[symfony/translate ](http://symfony.com/doc/current/translation.html ) library.
2012-04-14 01:01:59 +02:00
2012-06-28 11:43:56 +02:00
Example: framework/lang/en.yml (extract)
2012-04-14 01:01:59 +02:00
en:
ImageUploader:
2017-01-18 04:58:48 +01:00
Attach: 'Attach {title}'
2012-06-28 11:43:56 +02:00
UploadField:
2012-04-14 01:01:59 +02:00
NOTEADDFILES: 'You can add files once you have saved for the first time.'
2012-06-28 11:43:56 +02:00
Translation table: framework/lang/de.yml (extract)
2012-04-14 01:01:59 +02:00
de:
ImageUploader:
2017-01-18 04:58:48 +01:00
ATTACH: '{title} anhängen'
2012-06-28 11:43:56 +02:00
UploadField:
2012-04-14 01:01:59 +02:00
NOTEADDFILES: 'Sie können Dateien hinzufügen sobald Sie das erste mal gespeichert haben'
2012-04-15 18:03:51 +02:00
Note that translations are cached across requests.
The cache can be cleared through the `?flush=1` query parameter,
or explicitly through `Zend_Translate::getCache()->clean(Zend_Cache::CLEANING_MODE_ALL)` .
2011-02-07 07:48:44 +01:00
## Javascript Usage
2014-01-23 23:12:23 +01:00
The i18n system in JavaScript is similar to its PHP equivalent.
Languages are typically stored in `<my-module-dir>/javascript/lang` .
Unlike the PHP logic, these files aren't auto-discovered and have to be included manually.
2011-02-07 07:48:44 +01:00
### Requirements
2014-09-21 02:07:58 +02:00
Each language has its own language table in a separate file.
2014-01-23 23:12:23 +01:00
To save bandwidth, only two files are actually loaded by
2014-09-21 02:07:58 +02:00
the browser: The current locale, and the default locale as a fallback.
The `Requirements` class has a special method to determine these includes:
2013-10-23 17:53:08 +02:00
Just point it to a directory instead of a file, and the class will figure out the includes.
2011-02-07 07:48:44 +01:00
:::php
Requirements::add_i18n_javascript('< my-module-dir > /javascript/lang');
### Translation Tables in JavaScript
2014-01-23 23:12:23 +01:00
Translation tables are automatically included as required, depending on the configured locale in `i18n::get_locale()` .
As a fallback for partially translated tables we always include the master table (`en.js`) as well.
2011-02-07 07:48:44 +01:00
2014-01-23 23:12:23 +01:00
Master Table (`< my-module-dir > /javascript/lang/en.js`)
2011-02-07 07:48:44 +01:00
:::js
if(typeof(ss) == 'undefined' || typeof(ss.i18n) == 'undefined') {
console.error('Class ss.i18n not defined');
} else {
2014-01-23 23:12:23 +01:00
ss.i18n.addDictionary('en', {
2011-02-07 07:48:44 +01:00
'MYMODULE.MYENTITY' : "Really delete these articles?"
});
}
2014-01-23 23:12:23 +01:00
Example Translation Table (`< my-module-dir > /javascript/lang/de.js`)
2011-02-07 07:48:44 +01:00
:::js
2014-01-23 23:12:23 +01:00
ss.i18n.addDictionary('de', {
2011-02-07 07:48:44 +01:00
'MYMODULE.MYENTITY' : "Artikel wirklich löschen?"
});
2014-09-21 02:07:58 +02:00
For most core modules, these files are generated by a
[build task ](https://github.com/silverstripe/silverstripe-buildtools/blob/master/src/GenerateJavascriptI18nTask.php ),
2014-01-23 23:12:23 +01:00
with the actual source files in a JSON
2013-10-23 17:53:08 +02:00
format which can be processed more easily by external translation providers (see `javascript/lang/src` ).
2011-02-07 07:48:44 +01:00
### Basic Usage
:::js
alert(ss.i18n._t('MYMODULE.MYENTITY'));
2014-06-01 15:15:52 +02:00
### Advanced Use
The `ss.i18n` object contain a couple functions to help and replace dynamic variable from within a string.
#### Legacy sequential replacement with sprintf()
`sprintf()` will substitute occurencies of `%s` in the main string with each of the following arguments passed to the function. The substitution is done sequentially.
2011-02-07 07:48:44 +01:00
:::js
2014-06-01 15:15:52 +02:00
// MYMODULE.MYENTITY contains "Really delete %s articles by %s?"
2013-03-04 08:48:16 +01:00
alert(ss.i18n.sprintf(
ss.i18n._t('MYMODULE.MYENTITY'),
42,
'Douglas Adams'
2014-01-23 23:12:23 +01:00
));
2011-02-07 07:48:44 +01:00
// Displays: "Really delete 42 articles by Douglas Adams?"
2014-06-01 15:15:52 +02:00
#### Variable injection with inject()
`inject()` will substitute variables in the main string like `{myVar}` by the keys in the object passed as second argument. Each variable can be in any order and appear multiple times.
:::js
// MYMODULE.MYENTITY contains "Really delete {count} articles by {author}?"
alert(ss.i18n.inject(
ss.i18n._t('MYMODULE.MYENTITY'),
{count: 42, author: 'Douglas Adams'}
));
// Displays: "Really delete 42 articles by Douglas Adams?"
2011-02-07 07:48:44 +01:00
## Limitations
* No detecting/conversion of character encodings (we rely fully on UTF-8)
* Translation of graphics/assets
* Usage of gettext (too clumsy, too many requirements)
2011-03-08 22:05:51 +01:00
* Displaying multiple languages/encodings on the same page
2011-02-07 07:48:44 +01:00
## Links
2015-02-28 01:09:15 +01:00
* [Help to translate ](../../contributing/translations ) - Instructions for online collaboration to translate core
* [Help to translate ](../../contributing/translation_process ) - Instructions for adding translation to your own modules
2011-02-07 07:48:44 +01:00
* [http://www.i18nguy.com/ ](http://www.i18nguy.com/ )
2016-02-17 22:21:59 +01:00
* [balbus.tk i18n notes ](http://www.balbuss.com/internationalize/ )
