DeepLer is a local Moodle plugin that provides automatic machine translation or text improvement (not available with ©DeepL free api accounts) using the ©DeepL Pro Translation api.
It is developed for those who want to translate or rephrase a course all on one page, without having to navigate to each module and update manually translations and the {mlang} tags. Translation workflow being the following:
- Upload your prefered terminologies (DeepL glossaries)
- Set Moodle current language as your source language.
- Fine tune your ©DeepL's settings.
- Select the target language.
- Select the fields to translate and if need different source than the current main (Moodle's).
- Send to ©DeepL.
- Review and or amend automated translations.
- Save translations to Moodle's DB (with the multilang {mlang XX} tags).
- Your course is multilingual.
- ...
Multi-Language Content (v2) is a dependency of this plugin and will not work without it.
- Installation
- Configuration
- Permissions (Moodle capability)
- Main Admin settings
- API Key for DeepL Translate - Allow Fallback key.
- Tell the browser not to render embed iframes by default.
- Default value Escape LaTeX (in the courses translation page "Advanced Settings")
- Default value Escape PRE (in the courses translation page "Advanced Settings")
- Minimum textfield size
- Max length of breadcrumb's sub
- Token manager (mapping user to DeepL's API keys)
- Glossaries' management (NEW since v1.9)
- Translating
- User tour (inline tutorial)
- WARNINGS
- Compatibility
- How does this plugin differs from Content Translation Manager and Content Translation Filter?
- Future (todos)
- Submit an issue
- Changelog
- Coding, Debugging and Contributing
Clone or download this plugin to /moodlewww/local/deepler and run through the database
upgrade process.
You need a ©DeepL API Free or Pro account when you want to translate your content from one source to a distinct target. You need a ©DeepL API Improve text Pro account should your need be to rephrase your source in the same language. Multi-Language Content (v2) is a dependency of this plugin and will not work without it.
see Coding, Debugging and Contributing if you intend to help improving this plugin, or just if you are an admin and want to do some test in a dedicated sandbox.
Course Translator will extend Moodle with the local/deepler:edittranslations capability. Assign the capability to a new Translator role or add it to one of your
existing roles.
The context for this capability is set to USER so that you can also assign it to a user directly (provided it will have capabilities to access the course and modules).
To configure the plugin, navigate to Site Administration -> Plugins -> Local plugins -> DeepL Translator.
From this page you can configure ©DeepL settings, specify wether you are using ©DeepL API Free or ©DeepL API Pro. Visit the ©DeepL API page to signup for an api key that you can enter into local plugin settings.
The main API key now can be used for all users if you do tick Allow fallback key
If you untick Allow fallback key than a user must have an attribute mapped to a token in the Token manager
Sometimes iframes can overlap the user interface toggle this to show/hide all iframes in the source text display.
Set to true will check "escape LaTeX formulas", in the course translation form. This will have the effect to enable by default the Non translation of LaTeX formulas in course (when set here to true). Unchecking it here if your organisation rarely uses LaTeX formulas in the courses to slightly improve Deepler's performances,
Do not send <pre>...</pre> to translation by default.
Workaround to Allow "beta languages". DeepL API https://developers.deepl.com/api-reference/languages/retrieve-supported-languages does not (yet) return the full language list that it supports https://developers.deepl.com/docs/getting-started/supported-languages ... Those missing languages are now added hardcoded in the plugin.
Small text field are often limited in the database. The text content grows quite fast (plus the mlang tags) at each translation steps. After translation, if the text is too big, the DB will through an error.
Size this here based on your main language properties and the number on languages your Moodle supports.
The plugin adds a little breadcrumb when you scroll down the translation page. As some titles can be lengthy you can set a max length for each breadcrumb sub. Set to zero if you'd prefer no limiting.
Out of the box, DeepLer auto-discovers the text fields of every standard Moodle activity and question type. However, custom plugins, third-party question types, or activities with unusual DB structures may have additional text fields that the auto-discovery mechanism cannot find, or fields that should be shown as read-only, or fields whose values should never be translated at all.
The Additional field configuration admin setting lets a Moodle administrator describe those extra fields without touching the server filesystem. Navigate to Site Administration → Plugins → Local plugins → DeepL Translator and scroll to the Additional field configuration (JSON) textarea.
Changes take effect for all users immediately after saving. Leave the textarea empty to fall back to the bundled additional_conf.json defaults.
** Note :** it will only work with activity or questions components indeed.
The configuration is a flat JSON object. Each top-level key is a plugin component name (e.g. mod_url, qtype_essay, mod_customactivity). Its value is an object whose keys are database table names (without the mdl_ prefix) and whose values are table definitions.
{
"<plugin_component>": {
"<table_name>": {
"id": "<fk_column>",
"fields": {
"<field_name>": null,
"<field_name>": { "editable": false },
"<field_name>": { "exclude": "<value_to_skip>" }
}
}
}
}| Key | Required | Default | Description |
|---|---|---|---|
id |
No | id |
Name of the foreign-key column that links rows in this table back to the activity/question instance. Use "questionid" for question sub-tables, or a custom column name for non-standard plugins. |
fields |
No | (auto-discover) | Object of field names to expose. Omitting fields (or supplying an empty object {}) means the plugin will auto-discover all text columns in the table. |
Minimal example — expose two fields of a custom URL-based activity:
{
"mod_myactivity": {
"myactivity": {
"fields": {
"name": null,
"intro": null
}
}
}
}Multi-table example — question type with a separate answers table and a non-standard FK:
{
"qtype_myquestion": {
"qtype_myquestion_options": {
"id": "questionid",
"fields": {
"correctfeedback": null,
"incorrectfeedback": null
}
},
"qtype_myquestion_answers": {
"id": "questionid",
"fields": {
"answertext": null,
"feedback": null
}
}
}
}Each entry inside fields is either null (plain field, fully translatable) or an object with one or both of the following optional properties:
| Property | Type | Description |
|---|---|---|
editable |
false |
Display the field content in the translation UI but prevent editing or translating it. Useful for read-only reference fields (e.g. an external URL that must not be machine-translated). |
exclude |
string or true |
Skip rows where this field matches the given value. Use "*" to always skip the field regardless of its content (equivalent to true). Use a specific string to skip only rows whose content equals that string exactly. |
Examples:
"fields": {
"externalurl": { "editable": false },
"answer": { "exclude": "*" },
"feedback": null
}externalurlwill be shown in the translation table but cannot be translated.answerrows are never shown (all values are excluded).feedbackis shown and fully translatable.
When an admin saves the configuration, the plugin performs a two-pass validation:
-
JSON syntax — uses PHP's native
json_decode. Any syntax error (missing comma, unquoted key, trailing comma, etc.) blocks saving and displays the exact parse-error message. -
Structural and database schema check — the decoded object is validated against the expected shape and cross-checked live against the Moodle database:
- Plugin not installed: a yellow warning is shown (the entry is still saved — it becomes active once the plugin is installed).
- Table not found in DB: a yellow warning is shown (useful during development or when a plugin update renames tables).
- Unknown table-level keys (anything other than
idandfields): yellow warning. - Unknown field attributes (anything other than
editableandexclude): yellow warning. - Field not found in DB table: yellow warning (the field is still saved and will be silently skipped at runtime).
Errors (wrong JSON types for fields, id, or the root object) block saving and must be fixed before the configuration is accepted. Warnings are informational only and do not prevent saving.
links see below
DeepL API allows you to generate several API keys mainly for cost control and reporting.
To map, You need to save a main API key/token first, then the additional page links will display:
- Select a User attribute.
- Add a simple filter (* % and _ wild cards can be used).
- Add it to the list.
Now a user having the required capability, when translating a course will get affected a token.
Glossaries are added to your Moodle instance in 3 different ways:
- Downloaded from your DeepL API account.
- The plugin will synchronise the glossaries automatically.
- If a Glossary is added via DeepL.com's UI, then it will be added to Moodle.
- Should you delete a Glossary via the DeepL.com the plugin will delete it from the plugin upon admin visting the plugin page? So it might be better to only Delete glossary from the plugin and not from DeepL's UI.
- Admin can make these Glossaries 'public' meaning every translator will be able to use them.
- The plugin will synchronise the glossaries automatically.
- Uploaded by Moodle admins.
- Admin can make these Glossaries 'public' meaning every translator will be able to use them.
- Once uploaded they will be just as the ones downloaded from DeepL.
- Uploaded by translators via their user's preferences.
- Can be made available to the translators in the same pool (sharing the same token as seen above).
- Can be kept private (only available to the translator that uploaded it).
You can upload glossaries in the following formats 'csv', 'tsv', 'xlsx', 'xls', 'ods'
Bidirectional glossaries are not allowed yet.
The spreadsheet must contain a single sheet with 2 columns and either (1):
- Valid 2-letter code column headers (expl EN and JA) in upper or lowercase letters.
- Valid file name following the conventions below.
(1)The file naming has priority. So if you want to use the header way and add the lang pairs in the file name, make sure the name has no suffixe like _SOURCE-TARGET, avoid using a '_' folowed by a '-'. Do something like GLOSSARYNAME-SOURCE-TARGET.EXTENSION for example.
This has priority when assigning the Glossary's language pair.
- Rename the GLOSSARYNAME_SOURCE-TARGET.EXTENSION
- Name it meaningfully but not too long (for a nice display in tables).
- No header in the csv file.
- SOURCE and TARGET in the file name must be 2 character language code.
- DeepL does not manage bi directional glossaries.
(When not using the file naming conventions describde above)
Simply add valid 2-letter code in the first row of your spreadsheet.
| ES | FR |
|---|---|
| hermosa | belle |
| exquisito | delicieux |
| mouse | mouse |
| FR | ES |
|---|---|
| belle | hermosa |
| delicieux | exquisito |
| mouse | mouse |
File: 'litérature_fr-es.csv'
| belle | hermosa |
| delicieux | exquisito |
| mouse | mouse |
File: 'literatura-es-francia.csv'
| ES | FR |
|---|---|
| hermosa | belle |
| exquisito | delicieux |
| mouse | mouse |
Expl OK
- 私の用語集**_en-ja.xls**
- Tech_jargon**_FR-ES.CSV**
- myGlossary**-**en-fr.csv (ok only if it has EN FR header row)
Expl NOT OK (when not using the headers)
- myGlossary**-**en-fr.csv (here it will search for langs in the header row)
- Tech_jargon_FRA-SPA.ods (3-letter codes, but will not search for the header row)
- myHistoricalGlo_fr-es.txt (unsupported extension)
Once the admin has set the main api key, 2 additional links will display.
Click on "Deepler glossaries" to manage them.
Unless you remember it.
Select here a file on your file system and upload it. If the file does not match the conventions, or no lang pair header is found, error messages will display.
Upon successful upload, the Glossary is transmitted to DeepL, its metadata stored in Moodle DB and listed on the same page below.
The first column displays the names of both Glossaries retrieved from DeepL and those uploaded from Moodle:
- The one you gave the CSV file without the suffix.
- The name given when created in DeepL's interface.
Below the name is DeepL's glossary uuid, this is what will be transmitted when calling the translations.
Displays the glossary's source and target language.
Clicking on the +magnifier will display all the pairs defined.
Here you can set who can use the glossary.
- Private 2. Only the user that uploaded it. 3. Glossaries uploaded via your DeepL.com account have no user, so setting it 'private' would be like disabling it.
- Pool 5. All users mapped to a DeepL API token will have access to that glossary (see token management). 6. Glossaries uploaded via your DeepL.com account are mapped to the main API token (id 0). So only admin or users that are not mapped to a sub token (providing you set "Allow fallback key" to true) will have access to that glossary.
- Public 8. Public glossaries are accessible by any user. 9. Only Admins can set this visibility.
The is the DB id of the token the user that uploaded is affiliated with. When you set the visibility to 'Pool' all users in mapped to the same token will access the glossary.
Each time a translator uses a Glossary (by selecting it in the advanced settings) a time stamp is stored in DB. This is usefull mainly to cleanup unused glossaries.
For now only deletion.
Deleting a glossary here will delete it from DeepL.com too
Non admin users, hence translators, can manage their won set of glossaries.
These are Glossaries shared by the site admin or one of the translators sharing the same API token as the current user.
Are the ones uploaded by the current user. The visibility can be:
- Private: not shared
- Pool: shared with other translators sharing the same token.
To begin translating content, visit a course, open the course settings action menu, and then go to DeepL Translator.
You will be sent to the translation page for the course.
There you can fine tune ©DeepL's commands. Usually the default as set below should work fine with Moodle activity content.
Glossaries (DeepL's) are managed by the plugin. ONLY single source>target glossaries (v2) can be used with the plugin
Available glossaries are added to a dropdown list if they match the current language pair. Once you select a glossary it will be stored in the course/source/target cookie.
Clicking on the magnifier icon will display glossary mappings:
This is a Pro feature that will rephrase the source text. This is not available with the free API key.
Text improvement is beta and currently supported for the following target languages:
- de,
- en-GB, en-US,
- es,
- fr,
- it,
- pt-BR, pt-PT.
For German and english (de, en-GB and en-US) there are some options to choose from to define the tone or writing style.
Because Deepl is not very Good at that, iow we experienced that it would behave with inconsistency.
When this is set, Deepler will seek
Toggle this to show/hide iframes in the source texts.
All of the advanced settings are saved by course id + source/target lang pairs in the Cookie for one month (each call for sevices resets it).
Deepl API language portfolio differs from Moodle language packs.
Currently Deepl doesn't support sub language for source lanagues. See https://developers.deepl.com/docs/resources/supported-languages.
But forces sub languages for targets with :
- EN-GB - English (British)
- EN-US - English (American)
- PT-BR - Portuguese (Brazilian)
- PT-PT - Portuguese (all Portuguese variants excluding Brazilian Portuguese)
- ZH-HANS - Chinese (simplified)
- ZH-HANT - Chinese (traditional)
If your installation has sub local language, for example de_ch, it will be considered as its main (de).
So the plugin behaviour is the following : The proposed source languages will main languages of your Moodle instance lang list. The proposed targets will be all you available languages if they have a main Deepl compatible main language and the matching sub languages. But will then save it as the main language in the DB.
For example if you have a EN package you will be able to choose either EN-GB or EN-US as your target language, but it will save it as {mlang en}
Make sure you set the correct Multilang-V2 setting for that matter.
The source language will be set to the actual Moodle language selection, which will automatically set it as the other fallback language.
nb: In a future release you'll be able to assign the other fallback language to your choosing for more flexibility.
To change the source language you'd change Moodle's lang. It is important, from a translation standpoint, to select the source language from the language it was initially written (and to stick with it).
When first translating your content the plugin will insert {mlang other}Your Content...{mlang} tags .
Please check out the mlang docs if you are not familiar with Moodle's MLANG concept more.
To change the language you want to translate to, choose a language from the Target language {mlang XX} dropdown. Note: indeed you cannot translate from and to the same language so buttons and checkboxes would be disabled if so.
DeepL API pro account can now use the rephrase feature to improve the source text.
When selecting a target language that is supported and that is the same as the source language, the ® sign will be enabled in front of the target languages.
When you selected a target language and a field has outstanding content in another source language than the ® sign will display in front of the single source.
Language that are not supported by ©DeepL are checked at each session so if your Moodle instance have unsupported languages, you will not be able to select it.
Also if you have a Free account, you cannot select a same source and target languages.
In order to organise your translations, there 2 types filters :
- Course's sections and Activities.
- Translation status.
You can filter the rows to hide/show the ones that need to be translated as wished. Clicking on the "Status" checkbox will select all visible. These filter show/hide the textual content found in the course.
By default the plugin will start by showing the course's settings only as with heavy courses loading all activity text fields in a single page can bloat the browser.
Then you can either display ALL SECTIONS
Or select one of your course section and narrow down to an activity.
These are the content that are already translated and that no change were made in the source.
They will appear with the GREEN DOT indicator.
These are the textual contents that were never translated or that were modified after being translated.
They appear with the RED DOT indicator when they were never translated.
They appear with the ORANGE DOT indicator when they were already translated but the source text change since.
Hidden:
Toggle this filter to show/hide hidden (to users) sections or modules.
When you scroll down the breadcrumbs status give you an indication on where you are in the course.
_ in the expl below we are editing the 'Question text' field of the multichoice question titled 'Multi choice ABC' of the quiz 'Test MDL-84560' located in the course's
'Quizzes' section.
Each row has a little colored dot to indicate a status:
- Red -> This field was never translated. (no {mlang xx} tag for the xx target language found)
- Green -> The filed was already translated and up to date (in the target language).
- Orange -> This field was translated but there were some updates made in the Database. (Needs a review)
It is not possible to edit the source content from this plugin's interface. Nevertheless, clicking on the PENCIL icon will jump you to the regular place for you to do so.
_
Clicking on the TRANSLATION icon will toggle the display of multilang tags and all available translations.
Hovering the button shows you all the tags/languages already present in the field.
The plugin will try to fetch and display embedded images. (this should be improved soon so that image are displayed in the source) When not found it will highlight the alt text in yellow and italicised as seen above.
- The text is not selected. No translation will occur. ( ... )
- The text is selected but not sent to ©DeepL yet. (hourglass)
- By default, the main source language is selected. It will be stored within {mlang other}* tag.
- You set another language as source if your content had some content written in different lang. It will be stored within {mlang xx}* tag.
- Translation is retrieved from ©DeepL and filed in the text editor. (floppy)
- Now the translator can review ©DeepL's work and amend the translation if necessary.
- Once happy with the content a click on the floppy button will save the text.
(Save all saves all selected translations by batch)
- Translation is saved in the database, with the {mlang} filter surrounding it. (DB icon)
_Note* the following process when saving to the database _
The original content has no MLANG tag and the source lang is the main:
{mlang other}SOURCE_CONTENT{mlang} {mlang target_lang}TRANSLATED_CONTENT{mlang}
The original content has no MLANG tag and the source lang is different from the main:
{mlang other}SOURCE_CONTENT{mlang} {mlang special_source_lang}SOURCE_CONTENT{mlang} {mlang target_lang}TRANSLATED_CONTENT{mlang}
The original content has already MLANG tag and the source lang is the main:
{mlang other}SOURCE_CONTENT{mlang} {mlang target_lang}TRANSLATED_CONTENT{mlang}
The original content has already MLANG tag and the source lang is different from the main and there were no {mlang other}:
{mlang other}SOURCE_CONTENT{mlang} {mlang special_source_lang}SOURCE_CONTENT{mlang} {mlang target_lang}TRANSLATED_CONTENT{mlang}
The original content has already MLANG tag and the source lang is different from the main and there were already a {mlang other:
{mlang other}ANOTHER_SOURCE{mlang} {mlang special_source_lang}SOURCE_CONTENT{mlang} {mlang target_lang}TRANSLATED_CONTENT{mlang}
Moodle has this script limitation of field sizes. (understandable for db optimization)
When translating you can find yourself generating more characters than the Database can handle.
Then the Plugin would yield a "Database error".
But this can be annoying if you already called the DeepL API as you would have consumed the translation.
To warn you the plugin will display a message with the actual character count and the DB mas field size.
Soon the plugin will compute this base on the source/target expansion ratio to roughly predict the resulting size. You will also be able to see the total size once the translated content will be returned from DeepL and receive a warning should the total length exceed the database capacity so that you could shrink it accordingly.
If you have sub-languages installed in your Moodle instance, you can select one of them so that when you will save the translation it will be stored in the relative mlang tag.
Content's texts fields are displayed in the order of appearance of the course. A module (course settings, topics etc.) separator corresponding to the activities grouping is displayed with its title, underneath you can see it available for translation.
Note that: for now, the naming of the instances as well ads the fields are the DB ones, it will soon be replaced by the one used in Moodle's course layout for a better usability.
You can install a tour guide to simplify your translators' trainings.
See Moodle's instructions here : User tours
Activities/resources with complex sub content may not all work. We currently plan to support all the core mods and would be happy to add more (send us a PR) Book does, wiki too but beware when translating [[links]] as it will break the page link. (this should be fixed in future releas)
At this time, Deepler does not have the ability to translate advanced usage of mlang in content. For example, this includes the use of multiple mlang tags spread throughout content that utilize the same language._
Note: Still you can add untranslated content, after a first insertion of mlang tags, before and/or after, the parser should then leave them in place.
Currently, images are only displayed in the preview but not in the text editor. Instead, the alt attribute content is highlighted. The Alt attribute is not sent to ©DeepL. This should be added in further improvement for better accessibility.
question's image are still not displayed we are getting there...
This plugin has been tested on Moodle 4.1+ php >= 8.1
Should work with the following editors:
- Plaintext
- Atto
- Tiny°
- Marklar
°Tiny editor: When a user has TinyMCE as prefered editor (Default behaviour since 4.4+) and if your moodle instance added TinyMCE funky plugin, it makes tons of http call upon loading. NEW since v1.7.1: If TinyMCE is your prefered editor the plugin will initiate the page with a simple editable div. Only should you need to modify the recieved translation from DeepL, the plugin will load a basic TinyMCE for you to do so upon clicking inside the field. In a future version you will have the choice between the above behaviour and loading a modal with the full TinyMCE with all your fancy plugins.
It uses the default Moodle JS library and is tested with Boost and Classic. So there could be incompatibilities with other themes.
see Coding, Debugging and Contributing should you intend to help improving this plugin or just should you be an admin and want to do some test in a dedicated sandbox.
This plugin will add a local_deepler_update_translation web service for the translation page to perform ajax requests against.
This plugin does not translate every string on your site. It is only meant for translating courses and Questions. It uses Moodle's built-in multilingual features along with {mlang} to
translate your content. When you backup and restore courses, your translations will migrate with your content. Updating your source content will provide a "Update Needed" status
message on the course translation page.
See Enhancements
Please submit issues here.
See the CHANGES.md documentation.
This plugin relies on javascript. So if you set test environment with Moodle's debugging features, make sure debugdisplay (Display debug messages) is set to 'No'. This because as debugdisplay breaks the xhtml. So message from elsewhere could break the process.
On the other hand with debug (Debug messages) there is already a comprehensive messaging that should inform you what is going wrong with the plugin's process. Depending on the level DEVELOPPER, ALL, NORMAL, MINIMAL or NONE, the plugin's debugging messages adapt to it.
Check your browser's dev tools (F12) to see the detailed logs.
https://github.com/brunobaudry/moodle-local_deepler/issues
Make sure you describe:
- Your environment (PHP, Moodle version, database, browser used etc.)
- The current behaviour.
- The expected behaviour.
Pull requests, adhering to Moodle's coding guidelines, are welcome !
See the CONTRIBUTING.md default documentation, for how-to with GIT and github and push some code.
This plugins tries to have descent testing setup.
Some additional PHPUNIT, as well as BEHAT test can run be done provided you have a valid key. rename .env-dist to .env and set there your own api key DEEPL_API_TOKEN=DEFAULT DEEPL_API_TOKEN=YOUR_OWN_DEEPL_API_KEY (You can add both a pro or a free key, we recommend that you do the tests with a free one).
If you intend to test in your forked repo this code with Moodle CI. Ensure you also add a Repository secret with the DEEPL_API_TOKEN (as with the .env) (Repo > Settings > Security > Secrets and variable > Actions > New repository secret)