Skip to main content

General overview

Decidim Machine Translation in Decidim can be configured with any translation backend you want. They work this way:

  1. In the admin side only the default language is required
  2. In the admin side, if there is an empty value for one of the available language, machine translation will be done and the admin field will be kept empty.
  3. If an admin define a translation, it will takes priority over the machine translated content.

Tradeoffs we want to attend

  • If an admin specified a custom translation, it get fast out-of sync (as there is no notice original string get updated)
  • If you want your plateform in 15+languages, this is a lot of overload in the admin side.
  • Machine translation is not always good, specially for small texts as they lack context

Voca solution
We call our solution a "minimalistic" machine translation, as we will remove features more than adding.

When machine translation is activate:

  • All other languages won't be displayed in the admin side. The values in other languages will always be saved "empty" to let machine translation do its job
  • In the admin side, you do not see any locale chooser. It looks like you edit only one language.

Setup

First, you need to setup the available_locales for your Decidim installation. You can set it up through environment variables, or in the intializers/decidim.rb.

bundle exec rails c
Decidim.available_locales # List of available languages

Then access to /system and create your organization. You won't see any machine translation settings, that's normal. Once created, you can set this new organization to use machine translation:

Decidim::Organization.last.update(
  enable_machine_translations: true,
  machine_translation_display_priority: "translation"
)

Last step, you need to get a Deepl API token and set the environment variable DECIDIM_DEEPL_API_KEY. A credit card and a subscription is required for most of the cases.

Once you have done this, restart the server.

Environment Variables​

Environment VariableDescriptionDefault
DECIDIM_DEEPL_API_KEYDeepL API key``
DECIDIM_DEEPL_HOSTDeepL hosts, for on-premise installhttps://api.deepl.com
DECIDIM_DEEPL_VERSIONDeepL API versionv2
VOCA_DUMMY_TRANSLATEFor testing purpose, avoids calling DeepL and renders debug textfalse (not explicitly stated)

Translate missing .yml with machine translations​

You can use the gem `i18n-rasks" in your rails application to translate any missing I18n values. To do so:

  • add config/i18n-tasks.yml (link to the file)
  • run bundle binstub i18n-tasks
  • run bin/i18n-tasks translate-missing --from=en -l=ru --backend=deepl (for more option do a bin/i18n-tasks translate-missing --help )

Use the Machine Translation without a minimalist approach​

If the minimalistic approach does not fit to your project, you can disable it through a configuration in an initializer.

Decidim::Voca.configure do |config|
  config.enable_minimalistic_deepl = false
end

And restart your server

Test translations without actually call deepl​

For testing purpose, you can setup the environment variable VOCA_DUMMY_TRANSLATE to true. This will avoid calling deepl and render a debug text every time the machine translation is called. (You can then setup DECIDIM_DEEPL_API_KEY to whatever)

# Example of debug text
DUMMY TRANSLATION [date=12/02/2025 14:05:16,mode=html,context="This is a text from a participatory platform organized in space and then components. \n - Plateform Name: My participatory plateform\n - Plateform Description: undefined\n - space title: My process \n- space description: undefined\n - component name: Proposals\n - Author nickname: doctolib\n- Author bio: Medics @doctolib "]

You can then check:

  • If updates does update the date of the translation
  • The mode is correct (text/html)
  • The context is right

Known pitfall​

  • Decidim Awesome custom proposals use jquery.formbuilder, that do not support multilinguage labels. Thus, it won't be translated.
  • When a user writes content on a machine-translated locale, it gets translated in default locale but do not show a notice to users (looks like content was written in default locale)
  • Component title are not translated (yet). Resolution is in progress.