Language customisation: Difference between revisions

From MoodleDocs
(Added a little information to the tip "Can't find the string you wish to change?" which makes it possible to actually use this tip.)
 
(24 intermediate revisions by 5 users not shown)
Line 2: Line 2:
==Changing words or phrases==
==Changing words or phrases==


Words or phrases (in any language) used on the site may be easily changed by an administrator using the language customization feature. For example, you may want to change the word "Course" to "Unit". The process consists of 4 steps:
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".  


# Check-out the strings
# Go to ''Site administration > Language > Language customisation'' and choose the language you wish to customise.
# Filter the strings you wish to customize
# Click the "Open language pack for editing" button.  (This may take some time to process.)
# Customize the strings
# Once the language pack has loaded, click the "Continue" button.
# Save and check-in the strings
# 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.
===Importing and exporting language customisations===


== Quick instructions for the impatient ==
Custom strings may be imported and (with the capability [[Capabilities/tool/customlang:export|tool/customlang:export]]) exported from Site administration > Language > Language customisation.


# Go to the ''Administration > Site administration > Language> Language customisation'' page.
==Finding the component and string identifier==
# Pick the language to customise from the pull down list.
* We will use an example where the user wants to replace 'Courses' with 'Assessments' in the Dashboard of Moodle 3.3 Boost theme.
# Click on the "Open language pack for editing" button. This may take some time to process.
[[File:Lang string origins in Boost theme 01.png|400px|This is the text want to change]]
# Once the language pack has loaded, click on the "Continue" button.
* Go to ''Site administration > Development > Debugging''.
# Click or Ctrl+Click to select the files in the "Show strings of these components" list.  Notice that the files are grouped.  For example, you will find the lesson strings under "mod" and moodle.php under "core".
* Tick the 'Show origin of languages strings' tickbox then save changes.
# After selecting the file(s), it is possible to use the "Only strings containing" filter along with other filters.  For example, to look at only the string text that has the word "teacher" the file(s) you selected.
* 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).
# Click on "Show strings".
* Reload the page.  
# Make your changes in the appropriate "Local customisation" box.
# Click on "Apply changes and continue editing" if you want to use another filter or edit other file(s).
# Click on "Save changes to the language pack" to save all of the changes you have made.


:''Tip:'' Do not see any string changes?  Did you remember to use the "Save changes to the language pack" button?  Did you refresh your browser so that it is not looking at a cached page?  Did you edit the language file that is actually being used on your site, course or by the user?
[[File:Lang string origins in Boost theme 02.png|400px|These are the strings we need to change]]


:''Tip:'' Can't find the string you wish to change? Tick the 'Show origin of languages strings' checkbox in ''Administration > Site administration > Development > Debugging'' then visit the page containing the string you want to customise. Add <pre>&amp;strings=1</pre> to the url and reload the page. If you still don't see the 'origin of languages strings' try adding <pre>?strings=1</pre> to the end of the url instead.
* The page will then be displayed with component and string identifies in curly brackets after each string, for example "{nocourses/block_myoverview}". The first part, before the /, is the string identifier. The last part is the component e.g. block_myoverview.php. If there is nothing after the / (e.g. "{courses/}" ) then the string is in moodle.php.
* You will then use this information to customize your language strings.


== Background ==
===Using the obtained information in order to change the intended strings===


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 in so called language packages (or just lang packs) that are maintained by kind volunteers, community contributors and Moodle partners.  
# Go to ''Site administration > Language > Language customization''.
# Choose the English (en) language pack.
# Open language pack for editing.
# Click on the 'Continue' button.
# Select the moodle.php component (in this particular case)
# Type courses as the string identifier (in this case)
# Click on the 'Show strings' button
# Type your locally customized string, replacing 'Courses' with 'Assessments'.


Moodle site administrators can customize any language pack to fit their individual needs (for example to use the term "Unit" instead of "Course"). Editing the language pack files is not recommended, since any 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.
[[File:Lang string origins in Boost theme 03.png|400px|We will replace 'Courses' with 'Assessments']]


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.
* After saving the changes into the language pack, you can check that you achieved the intended change:
[[File:Lang string origins in Boost theme 04.png|400px|We have replaced 'Courses' with 'Assessments']]


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).
* Remember to always check that you have only changed the intended strings in the intended places.
* Repeat the procedure with all the strings that you want changed (e.g. course, no courses,...)
* Clear language string caches by going to ''Site administration > Development > Purge all caches''.


== Using Language customization tool ==
==Filter settings==


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 in ''Settings > Site administration > Language > Language customization''. Please refer to the following workflow diagram.
[[Image:Language_string_M2_filter.png|thumb|Language filter]]


[[image:customlang-process.png|800px|thumb|left|Workflow of the language customization (click to enlarge)]]
* ''Show strings of these components'' - Click or Ctrl+click to select one or more files.
<br clear="both" />
* ''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.


=== Check out strings into translator ===
==Local customisation highlighting==


At the Language customization first page, select a language to customize and press the button 'Open language pack for editing'. 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.
* 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.


=== Use filter to find the strings you want to customize ===
== More about language packs ==


[[Image:Language_string_M2_filter.png|thumb|right|Moodle 2.0 language filter]]
Moodle is translated into many languages - see [https://download.moodle.org/langpack/{{Version}}/ Language packs for Moodle {{Version}}] 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.  
After the checkout, use the "filter strings" form to find strings you want to customize for your site. Not selecting any filters will display all strings in the language pack.


* ''Show strings of these components'' - Click or Ctrl+click to select one or more files that contain the string you want.
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.
* ''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.
* ''Modified only'' - displays only the strings that are modified in the current session.  
:''Note:'' The term 'customized' means strings that are saved on disk in your xx_local pack directory. The term 'modified' represents the changes made since the last checkin string into the language pack. Customized strings (already saved in a file) are highlighted with green. Modified strings (not saved in a file yet) are highlighted with blue.
:''Tip:'' You may want to use this option look at your current work before you check it in.
* ''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.
:''Tip:'' The 'Only strings' filter can be used for a total search for a term used in your Moodle site for the selected language pack.
* ''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'. Finding where a particular string is saved can be difficult sometimes. The administrator can start a debugging function: Site administration > Development > Debugging and choose "Show origin of language strings". Then if you append "?strings=1" (or "&strings=1" if there is already a parameter) to the end of the page URL, beside each string will be shown something like "{rememberusername/admin}". The last part says which php file uses the string, so this one is in admin.php. If there is nothing after the / look in moodle.php. The first part, before the /, is the string identifier.


Use combination of filter settings to get the required set of strings.
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.


Click button 'Show strings' for potential editing.
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.


=== Input your own translation ===
[[image:customlang-process.png|800px|thumb|left|Workflow of the language customisation (click to enlarge)]]


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 'Local customization' field.
==How to backup and restore a customised language pack==
:''Tip:''If you want to delete your current customization , just delete the content of the 'Local customization' field and click the "Save and continue editing". The modifications that are going to be removed a customized string are highlighted in red.  If you made changes to a field previously "Save and continue editing" it will be highlighted in blue.


Click "Save and continue" button before you change the filter settings and show a new set of strings.
This is handy when you have made customisations of your language pack and you want to install these changes on another server.


=== Saving your work into files ===
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.


As necessary, you may repeat the "show strings", "local customization" and "Save and continue" process.  When you have made all the changes you want to make:
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.


Click "Save and check in strings into files" to process all changes made in the translator database to your local language pack.
==Sharing a language customisation==


=== Writing the modifications into files ===
* 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).


During the checkin, the contents of the translator database are dumped into files in moodledata/lang/xx_local/ directory.  
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].


Click "Save and check in strings into files" to process all changes made into your local language pack.
==Adding formatting==
:''Note:'' this operation removes the 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.


==Database error seen when attempting a language customization==
Help strings (with names ending in _help) allow for the use of [[Markdown]] for basic formatting (paragraphs and lists).
The language customization tool normally takes a fairly long time to execute the very first time (for each language pack) it is used  in a Moodle site. This is because it needs to access the Moodle DataBase. Later uses of the Language customization tool are rather quick.


[[File:Database error while language customization.png|400px]]
For all strings, you can add formatting using [https://en.wikipedia.org/wiki/HTML HTML tags].


Sometimes you may encounter a DataBase error when you try to customize your language pack. This error may be caused by a recent plugin that corrupted the database. You are advised to check all plugins recently added to your site, and test if 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.
==Changing the font size and colour of a language string==


Or, you can [https://moodle.org/mod/forum/discuss.php?d=208012 execute a DataBase query] at your server in order to track down the plugin causing the problem.
You can use language customization to change the font size and colour for any (core or additional plugin) Moodle string.
See the following example taken from [https://moodle.org/mod/forum/discuss.php?d=351446#p1418409 a Spanish forum] user who wanted to have a distinct large red coloured text for the 'Answer the questions...' prompt in the feedback activity:


==How to backup and restore a customized language pack==
[[File:Language customization changing font size and colour.png|600px]]
This is handy when you have made customizations of your language pack and you want to install these changes in another server.


If you customized 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.
You could also add an image to a customized language string, as in [https://moodle.org/mod/forum/discuss.php?d=354029#unread this forum post].


Once the folder is restored at another server, you also have to manually purge caches from the admin interface to let the in-built string manager to re-read the *_local folders and start using them.
==Moodle Mobile language strings customisation==
==Sharing a language customization==
See [[Moodle Mobile guide for admins#Custom language strings|Custom language strings]] in the Moodle Mobile guide for admins.
If you have made a language customization for a specific need, which is shared by other people (e g, a kid's version of your national language, intended for your school, but also useful for other schools), you might consider sharing it as a child language in AMOS. Contact the parent language pack maintainer listed in [http://lang.moodle.org/local/amos/credits.php translation credits] and/or our translation coordinator, Koen, [mailto:translation@moodle.org translation@moodle.org].


If your country uses a language that is not exactly the same as an existing language pack listed in [http://lang.moodle.org/local/amos/credits.php translation credits], and you have made a customization 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, as Canadian French, which has 1024 changes from the French parent language). If the parent language pack maintainer listed in [http://lang.moodle.org/local/amos/credits.php translation credits]  do not share your point of view, contact our translation coordinator, Koen, [mailto:translation@moodle.org translation@moodle.org]. Moodle is open source, and anyone can request a fork of a language pack if this would improve the use of Moodle for a country, even if other users do not agree.
== Language customization of langconfig.php file ==
 
You must keep in mind that starting and maintaining a new language pack might be a very time-demanding task, and a couple of child languages in AMOS have recently been [https://moodle.org/mod/forum/discuss.php?d=246152 eliminated] for lack of maintainance in several years.


Using language customization for parentlanguage inside langconfig.php in an existing Moodle server, where you add a parent language (while the AMOS parentlanguage string is actually empty) will ask for the installation of said parent language in the server, but will not substitute the missing translations in the child language with those of the parent language; English will be shown.


==See also==
==See also==
Line 113: Line 118:
* [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=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
* [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 
 
==Any questions?==
 
Please post in the [https://moodle.org/mod/forum/view.php?id=43 Languages forum] on moodle.org.


[[de:Sprachanpassung]]
[[de:Sprachanpassung]]
[[es:Personalización del idioma]]
[[es:Personalización del idioma]]
[[fr:Personnalisation de la langue]]

Latest revision as of 14:13, 18 March 2024

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.

Importing and exporting language customisations

Custom strings may be imported and (with the capability tool/customlang:export) exported from Site administration > Language > Language customisation.

Finding the component and string identifier

  • We will use an example where the user wants to replace 'Courses' with 'Assessments' in the Dashboard of Moodle 3.3 Boost theme.
This is the text want to change
  • 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
    ?strings=1
    or
    &strings=1
    (depending whether there is already a parameter).
  • Reload the page.

These are the strings we need to change

  • The page will then be displayed with component and string identifies in curly brackets after each string, for example "{nocourses/block_myoverview}". The first part, before the /, is the string identifier. The last part is the component e.g. block_myoverview.php. If there is nothing after the / (e.g. "{courses/}" ) then the string is in moodle.php.
  • You will then use this information to customize your language strings.

Using the obtained information in order to change the intended strings

  1. Go to Site administration > Language > Language customization.
  2. Choose the English (en) language pack.
  3. Open language pack for editing.
  4. Click on the 'Continue' button.
  5. Select the moodle.php component (in this particular case)
  6. Type courses as the string identifier (in this case)
  7. Click on the 'Show strings' button
  8. Type your locally customized string, replacing 'Courses' with 'Assessments'.

We will replace 'Courses' with 'Assessments'

  • After saving the changes into the language pack, you can check that you achieved the intended change:

We have replaced 'Courses' with 'Assessments'

  • Remember to always check that you have only changed the intended strings in the intended places.
  • Repeat the procedure with all the strings that you want changed (e.g. course, no courses,...)
  • Clear language string caches by going to Site administration > Development > Purge all caches.

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

Adding formatting

Help strings (with names ending in _help) allow for the use of Markdown for basic formatting (paragraphs and lists).

For all strings, you can add formatting using HTML tags.

Changing the font size and colour of a language string

You can use language customization to change the font size and colour for any (core or additional plugin) Moodle string.

See the following example taken from a Spanish forum user who wanted to have a distinct large red coloured text for the 'Answer the questions...' prompt in the feedback activity:

Language customization changing font size and colour.png

You could also add an image to a customized language string, as in this forum post.

Moodle Mobile language strings customisation

See Custom language strings in the Moodle Mobile guide for admins.

Language customization of langconfig.php file

Using language customization for parentlanguage inside langconfig.php in an existing Moodle server, where you add a parent language (while the AMOS parentlanguage string is actually empty) will ask for the installation of said parent language in the server, but will not substitute the missing translations in the child language with those of the parent language; English will be shown.

See also

Any questions?

Please post in the Languages forum on moodle.org.