How do you translate custom theme settings in Drupal 8?

I use hook_form_system_theme_settings_alter to add custom settings to a theme. One setting is the text string (e.g. 'Menu') to display beside the menu icon for a responsive menu. How can I integrate with the configuration translation system to allow the text to be translated?

All of the examples I have found describe how to translate a custom module's settings. I have not found any examples about how to translate a themes's settings, but there are a few hints in the Drupal code base that suggest it should be possible to create a THEME.config_translation.yml file.

I have taken a lead from this article on Gábor Hojtsy's blog and created the following files:

  • config/install/mytheme.settings.yml
  • config/schema/mytheme.schema.yml
  • mytheme.config_translation.yml

The schema is valid (tested using Configuration Inspector) and I have managed to get a Translate button for my theme's settings to show up on the Configuration translation admin page (/admin/config/regional/config-translation). That's as far as I've got.

I don't know what to use for base_route_name in mytheme.config_translation.yml. Here's what I have:

  title: 'My Theme Settings'
  base_route_name: system.theme_settings

For base_route_name I used system.theme_settings which results in a Translate button that links to /admin/appearance/settings/translate, but clicking on it leads to an Access denied, I assume because there is no translate page for theme settings. Also, I think the base_route_name should be system.theme_settings_theme and the Translate button should map to /admin/appearance/settings/mytheme/translate, but I get an error when I try that.

Am I on the right track? How would I go about creating a /admin/appearance/settings/mytheme/translate page and integrate it with the config translation system?

  • 1
    – user21641
    Commented Mar 8, 2016 at 14:13
  • I'm getting the same error as above. How to enable translation for theme settings?
    – wilNev
    Commented Jul 19, 2019 at 11:43
  • 4
    check my answer here - it helped me to translate theme settings drupal.stackexchange.com/a/283930/50320 Commented Jul 29, 2019 at 16:44
  • 1
    Also, important to understand the difference between string and text. A string does not translate, while text can be translated. I haven't experimented much with this other than fixing a custom module where my setting was being translated every time I enabled/disabled a module and translations were updated. I do believe that the addition of translatable: true is also important. Commented Mar 10, 2020 at 4:40
  • Admittedly not a fully qualified answer to OP's question but based on the example string 'Menu' they mentioned it's good to remember that all strings of Drupal core are always available on a site for translation. In other words: until your custom code uses only strings already used by core itself they'll be translatable. For example, string 'Menu' is definitely included in core.
    – Balu Ertl
    Commented Apr 21, 2022 at 14:44


Browse other questions tagged or ask your own question.