Drupal 8  8.0.2
Internationalization

Data Structures

class  DateFormatter
 
interface  TranslationInterface
 

Variables

trait StringTranslationTrait
 

Detailed Description

Internationalization and translation

The principle of internationalization is that it should be possible to make a Drupal site in any language (or a multi-lingual site), where only content in the desired language is displayed for any particular page request. In order to make this happen, developers of modules, themes, and installation profiles need to make sure that all of the displayable content and user interface (UI) text that their project deals with is internationalized properly, so that it can be translated using the standard Drupal translation mechanisms.

Internationalization

Different types of information in Drupal have different methods for internationalization, and different portions of the UI also have different methods for internationalization. Here is a list of the different mechanisms for internationalization, and some notes:

Translation

Once your data and user interface are internationalized, the following Core modules are used to translate it into different languages (machine names of modules in parentheses):

The Interface Translation module deserves special mention, because besides providing a UI for translating UI text, it also imports community translations from the Drupal translation server. If UI text and provided configuration in Drupal Core and contributed modules, themes, and installation profiles is properly internationalized (as described above), the text is automatically added to the translation server for community members to translate, via *.po files that are generated by scanning the project files.

Translation string sharing and context

By default, translated strings are only translated once, no matter where they are being used. For instance, there are many forms with Save buttons on them, and they all would have t('Save') in their code. The translation system will only store this string once in the translation database, so that if the translation is updated, all forms using that text will get the updated translation.

Because the source of translation strings is English, and some words in English have multiple meanings or uses, this centralized, shared translation string storage can sometimes lead to ambiguous translations that are not correct for every place the string is used. As an example, the English word "May", in a string by itself, could be part of a list of full month names or part of a list of 3-letter abbreviated month names. So, in languages where the month name for May is longer than 3 letters, you'd need to translate May differently depending on how it's being used. To address this problem, the translation system includes the concept of the "context" of a translated string, which can be used to disambiguate text for translators, and obtain the correct translation for each usage of the string.

Here are some examples of how to provide translation context with strings, so that this information can be included in *.po files, displayed on the localization server for translators, and used to obtain the correct translation in the user interface:

// PHP code
t('May', array(), array('context' => 'Long month name');
format_plural($count, '1 something', '@count somethings',
array(), array('context' => 'My context'));
// JavaScript code
Drupal.t('May', {}, {'context': 'Long month name'});
Drupal.formatPlural(count, '1 something', '@count somethings', {},
{'context': 'My context'});
// *.links.yml file
title: 'May'
title_context: 'Long month name'
// *.routing.yml file
my.route.name:
pattern: '/something'
defaults:
_title: 'May'
_title_context: 'Long month name'
// Config schema to say that a certain piece of configuration should be
// translatable using the Config Translation API. Note that the schema label
// is also translatable, but it cannot have context.
date_format:
type: string
label: 'PHP date format'
translatable: true
translation context: 'PHP date format'
// Twig template
{% trans with {'context': 'Long month name'} %}
May
{% endtrans %}
See Also
Transliteration
t()
format_plural()

Variable Documentation

trait StringTranslationTrait
Initial value:
{
protected $stringTranslation

Wrapper methods for .

Using this trait will add t() and formatPlural() methods to the class. These must be used for every translatable string, similar to how procedural code must use the global functions t() and ::translation()->formatPlural(). This allows string extractor tools to find translatable strings.

If the class is capable of injecting services from the container, it should inject the 'string_translation' service and assign it to $this->stringTranslation.

See Also
Services and Dependency Injection Container