Note: This documentation is for Moodle 2.7. For up-to-date documentation see Language customization.

Language customization: Difference between revisions

From MoodleDocs
(Described the work with the language customization tool)
(changes copied from 31 docs)
 
(36 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{stub}}{{Moodle 2.0}}
{{Language}}
==Changing words or phrases==


''Note: This page describes the process of language customization for Moodle 2.0 and higher versions. For information for older versions please see [[Local language]].''
Words or phrases (in any language) used on the site may be easily changed by an administrator using the language customisation feature. For example, you may want to change the word "Course" to "Unit".  


== Background ==
# Go to ''Site administration > Language > Language customisation'' and choose the language you wish to customise.
# Click the "Open language pack for editing" button.  (This may take some time to process.)
# Once the language pack has loaded, click the "Continue" button.
# Find the string you wish to customise using the filter settings, then clicking "Show strings". See below for details of how to find the component and string identifier.
# Make your changes in the "Local customisation" box.
# Click "Apply changes and continue editing" if you want to use another filter or edit other file(s), otherwise click "Save changes to the language pack" to save all of the changes you have made.


Moodle is translated into many languages - see [http://download.moodle.org/langpack/2.0/] for their list and the translation completion status. The translations are distributed in so called language packages (or just lang packs) that are maintained by kind volunteers, community contributors and Moodle partners. Please read the page [[Translation]] first to understand how the whole localization machinery works.
==Finding the component and string identifier==
[[File:Show origin of lang strings.png|thumb|Lang string origins]]
# Go to ''Site administration > Development > Debugging''.
# Tick the 'Show origin of languages strings' tickbox then save changes.
# Go to the page containing the string you want to customise and in the address bar, append the following to the URL: either <pre>?strings=1</pre> or <pre>&amp;strings=1</pre> (depending whether there is already a parameter).
# Reload the page.  


Moodle site administrators can customize any language pack to fit their individual needs (for example to use the term "Unit" instead of "Course"). You are discouraged from direct editing the files coming as a part official language pack. Such changes would be silently overwritten during the next upgrade. Instead, you should create a local language pack that holds all your changes from the official pack.
The page will then be displayed with component and string identifies in curly brackets after each string, for example "{rememberusername/admin}". The first part, before the /, is the string identifier. The last part is the component e.g admin.php. If there is nothing after the / then the string is in moodle.php.  


Local language packs have the same structure as the official ones. They are saved in your Moodle data directory in moodledata/lang/xx_local/ folder where 'xx' is the code of the language. You have to have the official language pack installed before you can customize it. Local language pack should contain just strings you have customized - you should not copy whole official language packs.
==Filter settings==


When displaying a string, Moodle first looks if a local customization of it exists in moodledata/lang/xx_local/component_file.php. If so, it is used. If not, the string from the official language pack is used (eventually, if the string has not been translated yet, the original English version is displayed). Please note that the strings are cached for better performance so you have to purge Moodle caches after you modify a file in your xx_local pack (caches are purged automatically if you use the tool described below).
[[Image:Language_string_M2_filter.png|thumb|Language filter]]


== Using Language customization tool ==
* ''Show strings of these components'' - Click or Ctrl+click to select one or more files.
* ''Customised only'' - tick the box to display only those strings that are already present in your xx_local pack.
* ''Help only''' - tick the box to display only help strings, that is the texts used when clicking the yellow question mark icon.
* ''Modified only'' - tick the box to display only the strings that are modified since the last checked in string into the language pack.
* ''Only strings containing'' - insert a phrase that must appear in the string. For example, if you put a word 'student' here, you will get only those strings that contain this word.
* ''String identifier'' - see above.


Moodle comes with a tool that allows you to edit your local language pack via web interface. This tool is available for the site administrators via block ''Settings > Site administration > Language > Language customization''. Please refer to the following workflow diagram.
==Local customisation highlighting==


[[image:customlang-process.png|800px|thumb|left|Workflow of the language customization (click to enlarge)]]
* Customised strings (already saved in a file) are highlighted in green.
* Modified strings (not saved in a file yet) are highlighted in blue.
* Customised strings for deletion are highlighted in red.
 
== More about language packs ==
 
Moodle is translated into many languages - see [https://download.moodle.org/langpack/3.1/ Language packs for Moodle 3.1] for their list and the translation completion status. The translations are distributed as language packages (or just lang packs) that are maintained by kind volunteers, community contributors and Moodle Partners.
 
Moodle site administrators can customise any language pack to fit their individual needs. Editing the language pack files directly is not recommended, since any changes would be silently overwritten during the next upgrade. Instead, you should use the language customisation feature, which automatically creates a local language pack that holds all your changes from the official pack.
 
Local language packs have the same structure as official ones. They are saved in your Moodle data directory in moodledata/lang/xx_local/ folder where 'xx' is the code of the language. You have to have the official language pack installed before you can customise it. A local language pack should contain just strings you have customised - there is no need to create a copy of a whole official language pack.
 
When displaying a string, Moodle first looks whether a local customisation exists in moodledata/lang/xx_local/component_file.php. If so, it is used. If not, the string from the official language pack is used. (If the string has not been translated yet, the original English version is displayed). Please note that the strings are cached for better performance so if you modify a file directly in your xx_local pack then you will have to purge Moodle caches afterwards. Caches are purged automatically when using the language customisation feature.
 
[[image:customlang-process.png|800px|thumb|left|Workflow of the language customisation (click to enlarge)]]
<br clear="both" />
<br clear="both" />


=== Check out strings into translator ===
==How to backup and restore a customised language pack==
 
This is handy when you have made customisations of your language pack and you want to install these changes on another server.
 
If you customised a language pack xx, the only folder you need to back up is $CFG->dataroot/lang/xx_local. All others without the _local suffix are standard packages that can be installed and uninstalled via the admin tool.


At the Language customization first page, select a language to customize and press the button 'Check out string into translator'. During the checkout, Moodle loads the language strings from PHP files into its database. The language customization tool works with this database so the files in your xx_local pack are not touched unless your proceed to the final step of this workflow. If the xx_local language pack does not exist yet, Moodle automatically creates an empty one for you.
Once the folder is restored on another server, you will have to manually purge caches from the admin interface to allow the in-built string manager to re-read the *_local folders and start using them.


=== Filter the strings you want to customize ===
==Sharing a language customisation==


After the checkout, use the filter form provided to find strings you want to customize for your site. The following filter options are available:
* If you have made a language customisation for a specific need, which is shared by other people (e.g. a kids version of your national language, intended for your school, but also useful for other schools), please consider sharing it as a child language in AMOS.
* If your country uses a language that is not exactly the same as an existing language pack listed in the [http://lang.moodle.org/local/amos/credits.php translation credits], and you have made a customisation that better suits the needs of your fellow country Moodle users, you might want to consider starting a child language pack in AMOS (e.g. Canadian French, which has over 1000 changes from the French parent language).  


* ''Show strings of these components'' - if you know which component defines the string you look for (it is a second parameter of the get_string() function), choose it here. Eventually, select all options to search across all components.
In either case, contact the parent language pack maintainer listed in the [http://lang.moodle.org/local/amos/credits.php translation credits] and/or our translation coordinator, Koen, [mailto:translation@moodle.org translation@moodle.org].
* ''Customized only'' - check this field to display only those strings that are already present in your xx_local pack.
* ''Help only''' - check this field to display only help tooltips, that is the texts used when clicking the yellow question mark icon. Started in Moodle 2.0, help string identifiers must end with _help suffix.
* ''Modified only'' - displays only the strings that are modified in the current session. Note the difference between 'customized string' and 'modified string' here. We use the term 'customized' for strings that are saved on disk in your xx_local pack directory. While the term 'modified' represents the changes you have done since the last checkout. Customized strings (already saved in a file) are highlighted with green. Modified strings (not saved in a file yet) are highlighted with blue. You may want to use this option to overview your current work before you check it in.
* ''Only strings containing'' - insert a phrase that must appear in the string, either the English or the translated. For example, if you put a word 'student' here, you will get only those strings that mention this word. This can be effectively used for mass search and replace to change the terminology you use in your Moodle site.
* ''String identifier'' - if you know the string identifier (it is the first parameter of the get_string() function), type it here. For example, the names of activity modules are defined in strings 'modulename'.


Use any combination of filter settings to get the required set of strings and press the button 'Show strings'. We believe that the filter is powerful part of the whole tool and with clever settings it will allow you to find the required strings effectively.
==Troubleshooting==


=== Input your own translation ===
===Database error===


The strings that pass all the conditions defined in the filter are displayed in a table. To replace the standard translation, put your own into the field in the last column 'Local customization'. Do not forget to save the text you input via 'Save and continue editing' button.
[[File:Database error while language customization.png|400px]]
If you encounter a database error when you try to customise a language pack, then it may be due to a recent plugin that corrupted the database. You are advised to check all plugins recently added to your site, and check whether removing a plugin prevents this error. If that is the case, please contact the maintainer for the involved plugin and [https://moodle.org/mod/forum/discuss.php?d=222815 report the error]. Most cases seen in 2013 were fixed by the maintainers of those plugins. [https://moodle.org/mod/forum/discuss.php?d=254464#unread One case seen in 2014] was related to the Essential (additional) theme and language packs other than English; it was caused by a a bug with the notification language handling, and was fixed with a plugin update.


If you want to delete your current customization, just delete the content of the input field and save the translator form. The modifications that are going to remove a customized string are highlighted in red.
Or, you can [https://moodle.org/mod/forum/discuss.php?d=208012 execute a database query] on your server in order to track down the plugin causing the problem.


=== Saving your work into files ===
==See also==


Repeat the last two steps as needed to find all the strings you want to change. When you are ready to save your work into files in xx_local language pack, press 'Save and check in strings into files' button.
* [https://moodle.org/mod/forum/discuss.php?d=219504 Duplicate entry 'en-373-AM'] forum discussion about error when attempting to edit a lang pack
* [https://moodle.org/mod/forum/discuss.php?d=272950 Changing one word across the whole site] forum discussion
*[http://youtu.be/0v72GKn2Wuk Moodle 2 Language Administration settings]  MoodleBites video on YouTube 


=== Writing the modifications into files ===
==Any questions?==


During the checkin, the contents of the translator database are dumped into files in moodledata/lang/xx_local/ directory. Note this operation removes this directory first and then re-creates it with the actual data. Therefore it is reasonable to not to touch the files directly after you have checked out them into the translator.
Please post in the [https://moodle.org/mod/forum/view.php?id=43 Languages forum] on moodle.org.


[[Category:Language]]
[[de:Sprachanpassung]]
[[es:Personalización del idioma]]

Latest revision as of 15:00, 12 October 2016

Changing words or phrases

Words or phrases (in any language) used on the site may be easily changed by an administrator using the language customisation feature. For example, you may want to change the word "Course" to "Unit".

  1. Go to Site administration > Language > Language customisation and choose the language you wish to customise.
  2. Click the "Open language pack for editing" button. (This may take some time to process.)
  3. Once the language pack has loaded, click the "Continue" button.
  4. Find the string you wish to customise using the filter settings, then clicking "Show strings". See below for details of how to find the component and string identifier.
  5. Make your changes in the "Local customisation" box.
  6. Click "Apply changes and continue editing" if you want to use another filter or edit other file(s), otherwise click "Save changes to the language pack" to save all of the changes you have made.

Finding the component and string identifier

  1. Go to Site administration > Development > Debugging.
  2. Tick the 'Show origin of languages strings' tickbox then save changes.
  3. Go to the page containing the string you want to customise and in the address bar, append the following to the URL: either
    ?strings=1
    or
    &strings=1
    (depending whether there is already a parameter).
  4. Reload the page.

The page will then be displayed with component and string identifies in curly brackets after each string, for example "{rememberusername/admin}". The first part, before the /, is the string identifier. The last part is the component e.g admin.php. If there is nothing after the / then the string is in moodle.php.

Filter settings

Language filter
  • Show strings of these components - Click or Ctrl+click to select one or more files.
  • Customised only - tick the box to display only those strings that are already present in your xx_local pack.
  • Help only' - tick the box to display only help strings, that is the texts used when clicking the yellow question mark icon.
  • Modified only - tick the box to display only the strings that are modified since the last checked in string into the language pack.
  • Only strings containing - insert a phrase that must appear in the string. For example, if you put a word 'student' here, you will get only those strings that contain this word.
  • String identifier - see above.

Local customisation highlighting

  • Customised strings (already saved in a file) are highlighted in green.
  • Modified strings (not saved in a file yet) are highlighted in blue.
  • Customised strings for deletion are highlighted in red.

More about language packs

Moodle is translated into many languages - see Language packs for Moodle 3.1 for their list and the translation completion status. The translations are distributed as language packages (or just lang packs) that are maintained by kind volunteers, community contributors and Moodle Partners.

Moodle site administrators can customise any language pack to fit their individual needs. Editing the language pack files directly is not recommended, since any changes would be silently overwritten during the next upgrade. Instead, you should use the language customisation feature, which automatically creates a local language pack that holds all your changes from the official pack.

Local language packs have the same structure as official ones. They are saved in your Moodle data directory in moodledata/lang/xx_local/ folder where 'xx' is the code of the language. You have to have the official language pack installed before you can customise it. A local language pack should contain just strings you have customised - there is no need to create a copy of a whole official language pack.

When displaying a string, Moodle first looks whether a local customisation exists in moodledata/lang/xx_local/component_file.php. If so, it is used. If not, the string from the official language pack is used. (If the string has not been translated yet, the original English version is displayed). Please note that the strings are cached for better performance so if you modify a file directly in your xx_local pack then you will have to purge Moodle caches afterwards. Caches are purged automatically when using the language customisation feature.

Workflow of the language customisation (click to enlarge)


How to backup and restore a customised language pack

This is handy when you have made customisations of your language pack and you want to install these changes on another server.

If you customised a language pack xx, the only folder you need to back up is $CFG->dataroot/lang/xx_local. All others without the _local suffix are standard packages that can be installed and uninstalled via the admin tool.

Once the folder is restored on another server, you will have to manually purge caches from the admin interface to allow the in-built string manager to re-read the *_local folders and start using them.

Sharing a language customisation

  • If you have made a language customisation for a specific need, which is shared by other people (e.g. a kids version of your national language, intended for your school, but also useful for other schools), please consider sharing it as a child language in AMOS.
  • If your country uses a language that is not exactly the same as an existing language pack listed in the translation credits, and you have made a customisation that better suits the needs of your fellow country Moodle users, you might want to consider starting a child language pack in AMOS (e.g. Canadian French, which has over 1000 changes from the French parent language).

In either case, contact the parent language pack maintainer listed in the translation credits and/or our translation coordinator, Koen, translation@moodle.org.

Troubleshooting

Database error

Database error while language customization.png If you encounter a database error when you try to customise a language pack, then it may be due to a recent plugin that corrupted the database. You are advised to check all plugins recently added to your site, and check whether removing a plugin prevents this error. If that is the case, please contact the maintainer for the involved plugin and report the error. Most cases seen in 2013 were fixed by the maintainers of those plugins. One case seen in 2014 was related to the Essential (additional) theme and language packs other than English; it was caused by a a bug with the notification language handling, and was fixed with a plugin update.

Or, you can execute a database query on your server in order to track down the plugin causing the problem.

See also

Any questions?

Please post in the Languages forum on moodle.org.