Upgrading tmgmt_deepl from 2.2.x to 2.4.x with the DeepL setup wizard

In tmgmt_deepl 2.2.x, there were two plugins (DeepL API Free and Pro), and the API key was stored in plain text in the Translator plugin's configuration, meaning it was also included in every configuration export. Starting with version 2.3.x, there is only one plugin, which communicates with DeepL via the official deepl-php library. The Key module manages the key, for example as an environment variable.

To make the update as straightforward as possible, 2.4.x comes with a DeepL setup page. This page contains a wizard that takes over the parts of the upgrade that are prone to errors (d.o/3605451). 

Changes

  • Plugins change. deepl_free and deepl_pro are replaced by deepl_api, which derives the endpoint from the key.
  • Keys disappear. The plain-text key in tmgmt.translator.*.yml is removed by the update – every translator ends up without a key.
  • Defaults changed. 20 instead of 5 texts per request, tag handling v2, a selectable translation model – existing translators keep the old behaviour.
  • Custom code fails quietly. Removed hooks are simply no longer called, and a forgotten config export brings the legacy translators back.
The DeepL setup page: A better solution
  • Pre-flight checks block drush updb before anything changes.
  • Guided key migration per translator, validated against DeepL.
  • Before / now / recommended settings side by side.
  • Custom code scan with file, line and replacement.
  • Config export check, test translation and drush tmgmt-deepl:upgrade-status for CI.

Step-by-step upgrade guide

Step 1: Update the code

It is best to upgrade directly from version 2.2.x to version 2.4.x. Upgrading to version 2.3.x first removes the legacy plugins but does not include the upgrade wizard.

# Already on Drupal 11.4:
composer require drupal/tmgmt_deepl:^2.4.4 -W

# Moving from Drupal 10 / 11.3 to 11.4 – core and module together:
composer require drupal/core-recommended:^11.4 drupal/core-composer-scaffold:^11.4 drupal/tmgmt_deepl:^2.4.4 -W
Step 2: Run the database updates
drush updb

A pre-flight check stops the update if deepl-php or the Key module is missing, and warns about plain-text keys that will be removed. The update then rewrites the legacy translators:

Before (2.2.x)

plugin: deepl_pro
settings:
  auth_key: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

After (2.4.x, once the setup page is done)

plugin: deepl_api
settings:
  auth_key_entity: deepl_api_key
  tag_handling_version: v2
  max_queries: 20
Step 3: Open the setup page and check the environment

The page (/admin/tmgmt/translators/deepl-setup) is linked from the status report, the Providers overview and the translator edit form. Its first step checks deepl-php, the Key module, pending updates and legacy translators – also in the configuration to import.

Provider overview

Click "Add a key" leads to the DeepL setup page.

Check environment

In case all environment specific requirements are fine, you can proceed adding the key.

Step 4: Assign API keys

For each translator, select an existing key or create a new one. You can do this as an environment variable (the recommended option and the default setting is DEEPL_API_KEY), as a file or as a configuration setting (in which case it will end up in your config export, as in 2.2.x). Unused translators can be deleted here.

Add new key or select existing one

Create new API key or select existing key.

Step 5: Review the settings
Apply custom or recommended settings

Decide if you want to apply recommended settings or keep current settings.

Step 6: Sync glossaries (optional)

If the DeepL Glossary module is enabled, clicking Sync with DeepL will update the DeepL glossaries.

Sync glossaries
Step 7: Fix custom or contrib code

On upgraded sites the scan lists removed APIs or hooks for custom and contrib modules.

Custom/ contrib module check
Step 8: Test, finish and verify

The final step lists any configurations that have not been exported and allows you to test the translation. Once all the tests have been successful and the configuration has been exported, you can complete the upgrade by clicking Finish upgrade.
 

Test and finish the setup wizard
Export new config and rebuild caches

To finish the process, we need to export the config and run a cache rebuild.

drush config:export      # deploy new keys and translators with the code
drush tmgmt-deepl:upgrade-status   # non-zero exit while something blocks
drush tmgmt-deepl:upgrade-status --finish   # finish without the UI
drush cache:rebuild

Important notes

  • Export the configuration. Otherwise the next config:import restores the legacy translators.
  • Large jobs timing out? 5 texts per request is still available in the translator settings.
  • DeepL API Free/Pro subscriptions keep working; Free accounts are limited to one glossary.
  • Fresh installs use the same wizard without the custom code step and end with Done.

Additional resources

Steffen Rühlmann
  • Senior Drupal Developer

Steffen is a Drupal allrounder, with many years of experience in module development, as well as theming and sitebuilding. He is also Acquia certified.