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.


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:

  • UI text is always put into code and related files in English.
  • Any time UI text is displayed using PHP code, it should be passed through either the global t() function or a t() method on the class. If it involves plurals, it should be passed through either the global formatPlural() function or a formatPlural() method on the class. Use \Drupal\Core\StringTranslation\StringTranslationTrait to get these methods into a class.
  • Dates displayed in the UI should be passed through the 'date' service class's format() method. Again see the Services topic; the method to call is \Drupal\Core\Datetime\Date::format().
  • Some YML files contain UI text that is automatically translatable:
    • *.routing.yml files: route titles. This also applies to *.links.task.yml, *.links.action.yml, and *.links.contextual.yml files.
    • *.info.yml files: module names and descriptions.
  • For configuration, make sure any configuration that is displayable to users is marked as translatable in the configuration schema. Configuration types label, text, and date_format are translatable; string is non-translatable text. See the Config API topic for more information.
  • For annotation, make sure that any text that is displayable in the UI is wrapped in @Translation(). See the Plugin translatables topic for more information.
  • Content entities are translatable if they have
  translatable = TRUE,

in their annotation. The use of entities to store user-editable content to be displayed in the site is highly recommended over creating your own method for storing, retrieving, displaying, and internationalizing content.

  • For Twig templates, use 't' or 'trans' filters to indicate translatable text. See for more information.
  • In JavaScript code, use the Drupal.t() and Drupal.formatPlural() functions (defined in core/misc/drupal.js) to translate UI text.
  • If you are using a custom module, theme, etc. that is not hosted on, see Interface translation properties topic for information on how to make sure your UI text is translatable.


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):

  • Language (language): Define which languages are active on the site.
  • Interface Translation (locale): Translate UI text.
  • Content Translation (content_translation): Translate content entities.
  • Configuration Translation (config_translation): Translate configuration.

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

See also



Namesort descending Location Description
Date drupal/core/lib/Drupal/Core/Datetime/Date.php Provides a service to handler various date related functionality.


Namesort descending Location Description
TranslationInterface drupal/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php Interface for the translation.manager translation service.


drupal/core/modules/system/core.api.php, line 605
Documentation landing page and topics, plus core library hooks.