Using machine translations

For multilingual organizations, Decidim includes a way to integrate with a machine translation service. The aim of this integration is to provide machine translations for any user-generated content.

Flow description

Every time a user creates or updates a translatable resource (that is, an instance of a resource that implements the Decidim::TranslatableResource concern), this workflow is triggered:

  • A background job starts for the resource. This background job lists the fields that have been changed, and checks if any of the fields is considered translatable.

  • For each translatable field that is changed, it lists the locales that need to be translated.

  • For each combination field/locale a new job is fired.

  • This job calls the machine translation service, which will handle how to translate that given text.

This workflow will only start if the machine translation service is configured in the installation, and the organization has the service enabled.

Create your own machine translation service

You can use the Decidim::Dev::DummyTranslator service as a base. Any new translator service will need to implement the same API as this class. In order to test the Decidim::Dev::DummyTranslator you will need to add at the top of config/initializers/decidim.rb the following line: require "decidim/dev/dummy_translator"

Integrating with async services

Some translation services are async, which means that some extra work is needed. This is the main overview:

  • The Translation service will only send the translation request. It should have a way to send what resource, field and target locale are related to that translation.

  • You’ll need to create a custom controller in your application to receive the callback from the translation service when the translation is finished

  • From that new endpoint, find a way to find the related resource, field and target locale. Then start a Decidim::MachineTranslationSaveJob with that data. This job will handle how to save the data in the DB.

Enabling the integration, installation-wise

This is an option in the Decidim initializer:

config.enable_machine_translations = true
config.machine_translation_service = "MyApp::MyOwnTranslationService"
config.machine_translation_delay = 0.seconds

The class will need to be implemented, or reuse one from the community. Check the docs on how to implement a machine translation service.

Enabling the integration, organization-wise

Each organization will be able to enable / disable the machine translations if they want to. The administrators of the organization perform the action from Settings → Configuration admin menu, where they can enable or disable the machine translation system, and also they can select the priority.

  • Original text first means that the platform will always display the original content as it has been added by contributors

  • Translated text first means that the platform will always display the translation first.