Content translation plugin set

What is the Content translation plugin set?

The content translation plugin set is a set of plugins that enable in-line translation of content in a Moodle site or course. The plugin set allows users with appropriate permissions to provide translations for content which is not translated by language packs.

Permissions to use the plugin are set by a site administrator. Once permissions have been given to a user, they will have the ability to use the plugin set and translate content throughout all areas of the site that they have access to.

You can learn how to use the Content Translation plugin by taking the Translate Moodle Academy course, which contains webinar recordings and activities to teach you how to use this tool.

Quick Guide

• Set your language using the language menu in the navigation bar.
• Click the content translation icon in the navigation bar, and choose Start in-line translation.
• Translatable content throughout the page will have an associated translate icon which will indicate the status of the translation - missing, stale or translated.
• Click the translate icon for the piece of content you wish to translate.
• On the dialogue window that appears, click Edit translation.
• Provide the translation in the Translated content text area. Be careful not to break any formatting or links if the original text includes this.
• Click Save changes

Terminology

Before using the Content translation plugin set, it is important to be familiar with the terminology used.

The following terms are used to indicate the translation status for any piece of content:

• Missing - Content has not been translated.
• Stale - Translation is out of date. This occurs when the original content has been modified after a translation was provided.
• Translated - Content has been translated.

Using the plugin

The content translation function can be turned on using an icon in the top right hand corner of the screen.

Clicking the icon will present the following options:

• Start in-line translation - Enables in-line translation of content.
• Missing in this course - Shows a list of all content which is yet to be translated in the current course or context.
• Stale in this course - Shows a record of all stale translations in the current course or context.
• Missing on this page - Shows a record of all content which is yet to be translated on the current page.
• Stale on this page - Shows a record of all stale translations on the current page.
• All missing translations - Shows a record of all content which is yet to be translated in the entire site.
• All stale translations - Shows a record of all stale translations in the entire site.

---

Start in-line translation

Before starting in-line translation, it is important to set your language using the language menu in the navigation bar.

This ensures that site content will be displayed in your chosen language, and that any translations you create will be saved for that language. Selecting the Start in-line translation option from the plugin menu will enable in-line translations.

At this point all translatable text will have an icon injected next to it to show its current status and allow it to be translated.

Missing - The content has not been translated.

Stale - The translation is out of date.

Translated - The content has been translated.

Providing or editing a translation

Clicking a translate icon for any piece of content will open a dialog window showing translation details for that content.

NOTE: If the translate icon is within a link, you will need to right click, as left clicking the icon will open the link.

• Original content - The original untranslated content as it was written.
• Generated hash - A unique identifier that identifies the original piece of content.
• Found hash - A unique identifier for the translated content, if a translation exists.
• Translation ID - The ID number of the existing translation, if a translation exists.

To close the dialog window click OK.

To provide a translation for the content click Edit translation.

The next screen allows you to provide your translation.

• Translation hash key - A unique identifier for the translated content.
• Translation language - The language which you are translating content into.
• Original content - The original untranslated content as it was written.
• Original HTML - The HTML markup of the original untranslated content as it was written.
  • NOTE: “Original HTML” will only appear if the original content was created using a text editor, and therefore has HTML markup.
• Translated content - The translated content. This is where you will provide your translation. If the original content has been formatted using the text editor, be careful not to break any formatting or links when providing your translation.

Once you have provided your translation, click Save changes to save the translation, or Cancel to exit without saving.

If the content had previously been translated, you can click Delete which will delete the translation and revert the content back to the original untranslated version.

Editing a stale translation

If a piece of original content is modified after a translation is provided, the associated translation will be considered ‘stale’ and will be identifiable by the stale translate icon.

When clicking a stale translate icon for a piece of content and then clicking through to edit the translation, some fields related to the original content will be slightly different:

• Original content - The newer version of the original untranslated content, after it was modified.
• Diff - Shows the changes between the newer and older versions of the original content. NOTE: This field is displayed in HTML markup.
• Old content - The older version of the original content, before it was modified.
• Original HTML - The HTML markup of the newer version of the original untranslated content, after it was modified. NOTE: “Original HTML” will only appear if the original content was created using a text editor, and therefore has HTML markup.

You can edit the translated content as normal, and once saved, the status of the translation will change from stale to translated.

View and manage translations across a course or site

As well as providing translations on any page using the in-line translation option, you can also view and manage translations across a page, course or whole site by choosing from the other reports in the content translation menu:

Missing/Stale in this course

The Missing in this course and Stale in this course options provide reports of all content within the current course or context which has either not been translated (missing) or where the translation is outdated (stale).

Missing/Stale on this page

The Missing on this page and Stale on this page options provide reports of all content on the current page which has either not been translated (missing) or where the translation is outdated (stale).

All missing/stale translations

The All missing translations and All stale translations options provide reports of all content over the entire Moodle site which has either not been translated (missing) or where the translation is outdated (stale).

When viewing any of these reports, you can use Filter options to further narrow down the results:

• Status - Allows you to filter translations by their state: Any, Stale, or Missing.
• Translation language - Allows you to filter translations by language.
• Page - Allows you to show translations on a specific page by entering a URL.
• Hash - Shows results with a specific hash (unique identifier).
• Original content - Shows results where the original untranslated content includes a specific word or phrase.
• Translated content - Shows results where the translated content includes a specific word or phrase.  

Clicking Update will apply the filter(s) and show the results of the report. You can sort and organise the report by clicking on the column headings, and use the Edit translation button to provide a translation for a string.

How content translation works?

The Content translation filter (filter_translations) is the main plugin that handles content translation. The Atto translations plugin (atto_translations) adds a translation hash key (if it doesn't already exist) to the content whenever the Atto editor loads up.

The translation hash key is acts as a glue between a content and its translation. For new content that is created, a new hash will be automatically added to the content by the Translations Atto plugin. The content translation will reference the hash key when it is saved.

The translation hash key is added in a <span> tag such as the one shown below. Such span tags will be added to the content by the Atto translations plugin, and you should not remove them.

<span data-translationhash="3955adaaa004ebe9a919d8fb280e7c12"></span>

Note: In order for existing Moodle content to be translation ready, a command line updating tool needs to be run to add translation spans to existing content. If you don't run this before translating, then when you subsequently make updates to your content, it will lose the translation and revert to the original language content. This is not an issue for any new content added after installing the plugin. See the release notes for further information.

Translation hashes

A content and its translations are linked by a translation hash key. The translation hash key is automatically added (using a <span> tag) to the content when editing content using the Atto editor. The content translation filter is designed with a "translate once, use everywhere" model. This means that a translation for a content will be used for other occurrences of the same text in other places. While useful it can also have undesired effects, such as accidentally overwriting translations or showing incorrect translations.

To mitigate this effect, it is recommended to avoid having duplicate translation hash keys. There are two scheduled tasks (replace duplicate hashes and copy translations) that will replace duplicate hashes and copy translations under the new hashes. See Scheduled tasks section for more details about these tasks.

Having unique translation hashes will ensure that translations cannot be accidentally overwritten when translation a similar content in a different context.

Replacing duplicate translation hashes

Whenever, you duplicate an activity or resource on a site with content translation plugins enabled or backup and restore courses on the same site, you will end up with duplicate translation hashes. You can enable the replace duplicate hashes and copy translations scheduled tasks.

You can also use the "Replace content translation hash" button in the Atto editor to manually replace the translation hash key when editing content.

Installation

You can download the content translations plugins from the Moodle plugins database or install the code from GitHub - you need both the plugins from the set for this plugin to work.

• Content translations filter plugin (filter_translations)
• Translations atto plugin (atto_translations)

1. Install all the plugins from the plugin set:
   • moodle-filter_translations
   • moodle-atto_translations
2. Go to Plugins > Manage filters:
   1. Enable the Content translations filter (Active? = on)
   2. Set the filter to apply to Content and headings.
   3. Move the filter to the top of the filter list (you may need to play with the position of this filter depending on what other filters you use on your site).
3. Add the atto plugin to the atto editor toolbar by going to Administration > Plugins > Text editors >Manage editors >Atto > Settings:
   1. Add to the end of the toolbar config: , translations
4. If you want to log all the changes go to Plugins > Filters > Content translations > Settings > Logging:
   1. Log missing translations: yes
   2. Log stale translations: yes
5. Add a translator role or assign the edit translations permission/s to an existing role by going to Site administration > Users > Permissions > Define roles. Without this permission set, users will not see the content translation icon in the navbar.
   • Edit translations filter/translations:edittranslations
6. Optionally, you may also wish to assign one or more of these enhanced translation permissions to various roles, although if you are unsure we recommend you leave these unset.
   • Bulk delete translations filter/translations:bulkdeletetranslations Enables the user to delete translations in bulk.
   • Delete translations filter/translations:deletetranslations Enables the user to delete translations one by one.
   • Edit site default language translations filter/translations:editsitedefaulttranslations Enables the user to edit the site default language - e.g. you may wish to translate forum contributions written in other languages.
   • Edit hash keys filter/translations:edittranslationhashkeys Enables the user to change the hash key for a translation.

Insert hash span CLI

If you enable the content translation plugin set on a Moodle site that already has existing courses and content, then the existing content does not already have the translation hash spans. For content translation to work correctly, you need to add the hash keys to your content before translating existing content. If this is not done, the link between your content and translation will break when the content is updated. This is because when you update the content, a new hash will be generated.

Please see the Known issues section before running the CLI scripts or enabling the scheduled tasks.

On a site where there are existing courses, it is recommended to run a command line script to add hash keys to your content before translating.

php /filter/translations/cli/insert_spans.php

This script looks for all the places where an HTML editor can be used and inserts a translation hash span. You will need to run this script on your Moodle site and edit the JSON file to remove any columns that should be excluded.

php filter/translations/cli/insert_spans.php --mode=listcolumns > /path/to/file/cols.json

When you have finalised the JSON file, run the CLI script to process insert the hash spans. Please use this extreme caution.

php filter/translations/cli/insert_spans.php --mode=process --file=/path/to/file/cols.json

After the script has run successfully, you can start translating existing content.

Note: There is also an "insert translation spans" scheduled task that can automatically add the span tags if one does not exist. It is disabled by default, and can be enabled on sites that need it. When running the "insert translation spans" CLI script or scheduled task, ensure that the JSON value only contains fields/columns that can accept the translation <span> tags.

Caching mode

Since the filter makes database calls and, if Google Translate is enabled, web service calls, it is advisable to enable caching by working with the cachingmode setting. If you have a small volume of course material in active use then Application mode caching is advised, if you have a large volume then use Session mode caching. In any case, the default of Request is rarely the optimal choice.

To change the caching mode: go to Site Administration > Plugins > Filters > Content translations.

Pages to leave untranslated

When the content translation filter is enabled by default at the site-level then the filter applies to all pages. However, there are several pages in Moodle, such as admin pages, where it does not make sense to run this filter. Such pages can be left untranslated by adding them to the filter_translations | untranslatedpages setting.

Here is a list of pages that can excluded from translations. Depending on your site and the plugins you use, you can exclude additional pages to this list.

/user/index.php
/user/view.php
/user/profile.php
/group/index.php
/admin/settings.php
/admin/user.php
/admin/purgecaches.php
/course/management.php
/course/editcategory.php
/report/eventlist/index.php
/report/backups/index.php
/report/completionoverview/index.php
/report/configlog/index.php
/report/courseoverview/index.php
/report/insights/insights.php
/report/log/index.php
/report/loglive/index.php
/report/performance/index.php
/report/questioninstances/index.php
/report/security/index.php
/report/stats/index.php
/report/status/index.php
/filter/translations/managetranslationissues.php
/filter/translations/managetranslations.php
/filter/translations/edittranslation.php
/mod/quiz/report.php
/mod/feedback/analysis.php
/mod/feedback/show_entries.php

Languages to exclude from log

When you enable logging of missing and stale translations, then if a translation for a particular language does not exist, it gets logged in the translation_issues table. Generally it is a good idea to exclude the default language in which content is created on a site from logging. Otherwise, the translation_issues table unnecessarily logs records which do not need translation.

Languages to exclude from translation can be set in the setting: filter_translations | logexcludelang

Languages to exclude from translation

A user with permissions to translate content will be able to translate content in any of the languages enabled on the site. It is possible to "disallow" translations in selected languages. This will prevent all users from translating content in those languages.

Languages to exclude from translations can be set in the setting: filter_translations | excludelang

Note: Currently it is not possible to allow/disallow translation permissions per language.

Scheduled tasks

There are a number of scheduled tasks that can be enabled, if needed. These scheduled tasks are disabled by default and should only be enabled if content translation is to be applied to the whole site. The scheduled tasks run checks on table columns specified in JSON format. This JSON data is defined in the Content translation filter settings.

Note: Ensure that the tables and columns defined in the JSON data are the columns that you wish to run the content translation tasks on. Setting incorrect tables/columns can cause issues on your site.

If you use short answer or matching quiz questions on your site, then ensure that the question answer field/column is not part of the JSON data. The translation <span> tags added to the answer field in these question types breaks these quiz questions.

Insert translation spans

This task scans records in specified tables/columns and adds a translation span tag if one is not found.

This task should only be enabled if content translation is to be used on the entire site. The frequency of this task will depend on how often content is created and translated on your site.

Replace duplicate hashes

This task checks for duplicate translation hashes in specified tables/columns and replaces duplicate hashes with a new "unique" hash. The frequency of this task will depend on how often content is created and translated on your site.

In most cases, you do not want to have duplicate translation hashes, since they can lead to accidental overwriting of translations. You end up with duplicate translation hashes when you duplicate or import/restore a content that already has a translation span.

Copy translations

This task finds matching translations for each content in specified tables/columns and copies them under the translation hash for that content. The frequency of this task will depend on how often content is created and translated on your site. Enable this task if you enable the "Replace duplicate hashes" task.

Cleanup translation issues

This task cleans up the translation issues table by deleting records older than 7 days. You can run into performance issues if the translation issues table grows too large. The cleanup task is enabled by default and it is advisable to keep it enabled so that the translation issues table is kept at a manageable size.

Limitations

Some activities and question types currently cannot be translated using the inline translation option. Multi-choice and True or false question types are tested and supported. Other question types such as drag and drop, select missing words do not have full support yet. H5P content cannot be translated with inline translations.

The question text for short answer and matching questions can have the translation span tags (and support inline translation) but the answer fields for these questions should not have the translation span tags added.

See below for some more known issues.

Known issues

Tiles course format

If using the Tiles course format, the translation buttons do not currently appear on content appearing within the tiles (as at 8 June 2022)

Matching questions in lesson activity

Matching questions in Lesson activity cannot be translated with inline translation (as at 11 March 2024). The alternative way to translate matching questions in lessons is to allow translators Manage a lesson activity ("mod/lesson:manage") permission.

Matching questions in quiz

Matching questions in quiz activity cannot be translated with inline translation (as at 11 March 2024). Inline translation icons cannot be shown in the matching question dropdowns. You can use the "Missing on this page" report to translate matching questions.

Grading forms

Assignment grading forms currently cannot be translated (as at 11 March 2024).