Visa källa för Content translation plugin set

{{Infobox plugin
|type = admin tools / filter
|entry = https://moodle.org/plugins/filter_translations
|discussion = tbc
|maintainer = [https://moodle.org/user/profile.php?id=1396756 Andrew Hancox]
|float = right
}}
==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. 
==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.

[[File:missing.jpg|frameless|55x55px|link=Special:FilePath/missing.jpg]] Missing - The content has not been translated.

[[File:stale.jpg|frameless|55x55px|link=Special:FilePath/stale.jpg]] Stale - The translation is out of date.

[[File:translated.jpg|frameless|55x55px|link=Special:FilePath/translated.jpg]] 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.
== Installation ==
This plugin will soon be available on the Moodle plugins database. In the meantime you can install the code from github - you need all the plugins from the set for this plugin to work. 
=== 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 hash key (if it doesn’t already exist) to the content whenever the Atto editor loads up.

The 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.

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 back 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. 
# Install all the plugins from the plugin set:
#*[https://github.com/andrewhancox/moodle-filter_translations moodle-filter_translations]
#*[https://github.com/andrewhancox/moodle-atto_translations moodle-atto_translations]
# Go to '''Plugins''' > '''Manage filters''':
## Enable the Content translations filter (Active? = on)
## Set the filter to apply to '''Content and headings'''.
## 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).
# Add the atto plugin to the atto editor toolbar by going to '''Administration''' > '''Plugins''' > '''Text editors''' >'''Manage editors''' >'''Atto''' > '''Settings:'''
## Add to the end of the '''toolbar config''': , translation
# If you want to log all the changes go to '''Plugins''' > '''Filters''' > '''Content translations''' > '''Settings''' > '''Logging''':
##'''Log missing translations''': yes
##'''Log stale translations''': yes
# 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
# 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 hash keys. 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.

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.<syntaxhighlight lang="shell">
php /filter/translations/cli/insert_spans.php
</syntaxhighlight>This script looks for all the places where an HTML editor can be used and inserts a hash key.
You will need to run this script on your Moodle site and edit the JSON file to remove any columns that should be excluded.<syntaxhighlight lang="shell">
php filter/translations/cli/insert_spans.php --mode=listcolumns > /path/to/file/cols.json
</syntaxhighlight>When you have finalised the JSON file, run the CLI script to process insert the hash spans. Please use this extreme caution.<syntaxhighlight lang="shell">
php filter/translations/cli/insert_spans.php --mode=process --file=/path/to/file/cols.json
</syntaxhighlight>After the script has run successfully, you can start translating existing content.
== 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.
== Known issues ==
=== Tiles course format ===
If using the [https://moodle.org/plugins/format_tiles Tiles course format], the translation buttons do not currently appear on content appearing within the tiles (as at 8th June 2022)
=== Matching questions in lesson activity ===
Matching questions in Lesson activity cannot be translated with inline translation (as at 18 August 2022). 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 18 August 2022). 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 18 August 2022).