• Drupal configuration cannot be translated or localized.
  • All contributed solutions and efforts happen after the fact and thus impose idempotent problems; i.e., things cannot be safely loaded and saved.


  • Make configuration translatable.
  • Make configuration idempotent; safe to be written regardless of current language.


Language-specific configuration
Configuration that is limited to a specific language condition and only exists in that context/condition.
Multilingual configuration
Configuration values (not necessarily human-readable strings) can be different per language.
Translatable configuration
Human-readable string values in configuration can be translated into different languages.

Given this terminology, read the Goal again.


Translatable configuration architecture

  • Architectural design considerations:
    • [withdrawn] Translators should not change configuration. Configuration should not change just because it was translated.
    • Modules should be able to ship with pre-translated configuration.
    • Monolingual (single-language) non-English sites do not necessarily need English configuration values. Only default configuration shipped with modules may be in English.
    • Retain easy Developer Experience (DX) and performance for monolingual English-only sites.
    • Keep the configuration system clean and lean. Language support must not turn it into a complex beast.
    • A single request may require configuration values in any number of languages/translations (e.g., for sending e-mails).
    • The configuration file format might lead to escaped Unicode string garbage for translated configuration values (e.g., JSON).
    • Not all values in a configuration object are translatable.
    • Each translation of a configuration value has to go through the same validation as the original/source value.
    • Localized and multilingual (language-specific) values will be required in addition to translations of human-readable strings (e.g., date formats, or language-specific recipient e-mail addresses for a contact form). While business logic for localized/multilingual values differ (configured by site administrators, not translators), the storage handling/requirements are the same.
    • Loading » saving » loading a configuration object must be idempotent, regardless of current language. Configuration values must not be altered or overloaded after loading.
  • Especially the last two points mean that language-specific values are best stored and maintained within a configuration object (like field translations).

Design / Implementation

Translatable configuration design implementation

  • Language is part of the configuration key names.
  • The configuration system internally handles and negotiates the language keys. Not specified manually.
  • Each configuration value always has a fallback value for any language. Used if there is no translation/language-specific value.
  • Configuration values can be untranslatable. But that does not matter for the configuration system/storage. The configuration system will not care for that business logic.
  • The language key is always the first key for each key/value in a configuration object. This allows to generate the translated/language-specific values more easily (overloading all fallback values with all language-specific values.)

    (Disregard the second language key in the photo; result of brainstorming.)

  • An additional/separate system to identify translatable/multilingual configuration values is required.
    • An (XML-alike) schema approach to identify translatable values in a configuration object will not work, because configuration objects may be extended with sub-values by other modules.
    • Configuration for which configuration values are translatable/multilingual will not be supported. The information about translatable/multilingual configuration values will be hard-coded. (for D8)
    • Identification of translatable/multilingual configuration values does not matter for the implementation, will be figured out later.
  • An additional/separate system for the User Interface for translatable/multilingual configuration values is required.
  • Conclusion: Decouple the property API from the entity system, to make it not only work for fields and entity properties, but also for configuration object properties. This gives us:
    • Type: The data type of a configuration value is clearly specified.
    • Widget: A dedicated widget for each configuration value. (unblocks a separate translation interface)
    • Validation: Each configuration value can be validated independently. (unblocks a separate translation interface)
    • Meta information: Required values, single/multiple values (cardinality), identification of translatable values.
CommentFileSizeAuthor KBsun
config.architecture.jpg152.78 KBsun
Members fund testing for the Drupal project. Drupal Association Learn more


Gábor Hojtsy’s picture

Issue tags: +sprint
Gábor Hojtsy’s picture

In fact, there is an existing issue for this at #1448330: [META] Discuss internationalization of configuration. I think we should merge this there and mark this as duplicate.

Gábor Hojtsy’s picture

Status: Active » Closed (duplicate)

Copied issue summary as a comment to #1448330: [META] Discuss internationalization of configuration in fact.

Gábor Hojtsy’s picture

Issue tags: -sprint

Should not be on sprint either. All followers, please move to #1448330: [META] Discuss internationalization of configuration. See you there!

Gábor Hojtsy’s picture

Issue summary: View changes

Updated issue summary.