Difference between revisions of "Language customization"

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 2.2. Up-to-date documentation for the latest stable version is available here: Language customization.

m (Merged the 2.0 instructions from the Language editing page)
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<p class="note">'''Note:''' This page describes how to change words or phrases in Moodle 2.0 onwards. For details of the process in versions prior to 2.0, see [[Language editing]].</p>
+
{{Language}}
 
+
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:
{{Moodle 2.0}}Location: ''Site administration > Language > Language customization''
 
 
 
In Moodle 2.0 onwards, words or phrases (in any language) used on the site may be easily changed using the language customization feature. For example, you may want to change the word "Course" to "Unit". The process consists of 4 steps:
 
  
 
# Check-out the strings
 
# Check-out the strings
Line 9: Line 6:
 
# Customize the strings
 
# Customize the strings
 
# Save and check-in the strings
 
# Save and check-in the strings
 
  
 
== Quick instructions for the impatient ==
 
== Quick instructions for the impatient ==
  
* Go to the ''Site administration > Language> Language customization'' page.
+
# Go to the ''Settings > Site administration > Language> Language customization'' page.
* Pick the language to customize from the pull down list.
+
# Pick the language to customize from the pull down list.
* Click the "Check out strings to translator" button. And get ready for the change.
+
# Click the "Check out strings to translator" button. This may take time to process.
* Use the new "filter strings" interface to select the file to edit. Notice the files are grouped. For example, you will find the lesson strings under "mod" and moodle.php under core.
+
# Click or Ctrl+Click to select files on the "Filter strings" interface. Notice files are grouped. For example, you will find the lesson strings under "mod" and moodle.php under core.
* After selecting the file, it is possible to use "string must contain" and other filters. For example, look at only string text that has "add" in the lesson.php set.
+
# After selecting the file(s), it is possible to use "string must contain" and other filters. For example, look at only string text that has "teacher" the file(s) you selected.
* Once you are done, you can save changes and pick another filter or PHP file to edit.
+
# Click "Save changes and continue editing" if you want to pick another filter or PHP file(s) to edit.
* When you want to save your edits, select "Save and check in string into files".  This will store the changes you have made so all users will see them.   
+
# Click "Save and check in string into files" to save all changes you have made.   
  
 
:''Tip:'' Do not see any string changes?  Did you remember to use the "Save and check in string into files" button? Did you refresh your browser so it is not looking at a cached page? Did you edit the language file that is actually being used in your site, course or by the user?
 
:''Tip:'' Do not see any string changes?  Did you remember to use the "Save and check in string into files" button? Did you refresh your browser so it is not looking at a cached page? Did you edit the language file that is actually being used in your site, course or by the user?
 +
 +
:''Tip:'' Can't find the string you wish to change? Tick the 'Show origin of languages strings' checkbox in ''Settings > Site administration > Development > Debugging'' then visit the page containing the string you want to customize.
  
 
== Background ==
 
== Background ==
  
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.
+
Moodle is translated into many languages - see [http://download.moodle.org/langpack/ Moodle.org: Language packs] 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.
  
 
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.
 
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.
Line 35: Line 33:
 
== Using Language customization tool ==
 
== Using Language customization tool ==
  
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.
+
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:customlang-process.png|800px|thumb|left|Workflow of the language customization (click to enlarge)]]
 
[[image:customlang-process.png|800px|thumb|left|Workflow of the language customization (click to enlarge)]]
Line 43: Line 41:
  
 
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.
 
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.
 +
:''Tip:'' There is currently a problem with "execution time". If you get the "Fatal error: Maximum execution time of 180 seconds exceeded" message, you will have to press the button 'Check out string into translator' several times to get the operation completed. See [http://moodle.org/mod/forum/discuss.php?d=163375 forum discussion].
  
There is currently a problem with "execution time". If you get the "Fatal error: Maximum execution time of 180 seconds exceeded" message, you will have to press the button 'Check out string into translator' several times to get the operation completed. See [http://moodle.org/mod/forum/discuss.php?d=163375 forum discussion].
+
=== Use filter to find the strings you want to customize ===
 
 
=== Filter the strings you want to customize ===
 
  
 
[[Image:Language_string_M2_filter.png|thumb|right|Moodle 2.0 language filter]]
 
[[Image:Language_string_M2_filter.png|thumb|right|Moodle 2.0 language filter]]
After the checkout, use the filter form provided to find strings you want to customize for your site. The following filter options are available:
+
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'' - 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.
+
* ''Show strings of these components'' - Click or Ctrl+click to select one or more files that contain the string you want.  
 
* ''Customized only'' - check this field to display only those strings that are already present in your xx_local 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. Started in Moodle 2.0, help string identifiers must end with _help suffix.
+
* ''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 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.
+
:''Note:'' Starting in Moodle 2.0, help string identifiers must end with _help suffix.
* ''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.
+
* ''Modified only'' - displays only the strings that are modified in the current session.  
* ''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'.
+
:''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.
  
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.
+
Click button 'Show strings' for potential editing.
  
 
=== Input your own translation ===
 
=== Input your own translation ===
  
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.
+
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.
 +
:''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.  
  
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.
+
Click "Save and continue" button before you change the filter settings and show a new set of strings.
  
 
=== Saving your work into files ===
 
=== Saving your work into files ===
  
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.
+
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:
 +
 
 +
Click "Save and check in strings into files" to process all changes made in the translator database to your local language pack.
  
 
=== Writing the modifications into files ===
 
=== Writing the modifications into files ===
  
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.
+
During the checkin, the contents of the translator database are dumped into files in moodledata/lang/xx_local/ directory.  
 
 
==See also==
 
  
* [[Language editing]] - for versions of Moodle prior to 2.0
+
Click "Save and check in strings into files" to process all changes made into your local language pack.
 +
:''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.
  
[[Category:Language]]
+
[[de:Sprachanpassung]]

Latest revision as of 14:44, 12 May 2012

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:

  1. Check-out the strings
  2. Filter the strings you wish to customize
  3. Customize the strings
  4. Save and check-in the strings

Quick instructions for the impatient

  1. Go to the Settings > Site administration > Language> Language customization page.
  2. Pick the language to customize from the pull down list.
  3. Click the "Check out strings to translator" button. This may take time to process.
  4. Click or Ctrl+Click to select files on the "Filter strings" interface. Notice files are grouped. For example, you will find the lesson strings under "mod" and moodle.php under core.
  5. After selecting the file(s), it is possible to use "string must contain" and other filters. For example, look at only string text that has "teacher" the file(s) you selected.
  6. Click "Save changes and continue editing" if you want to pick another filter or PHP file(s) to edit.
  7. Click "Save and check in string into files" to save all changes you have made.
Tip: Do not see any string changes? Did you remember to use the "Save and check in string into files" button? Did you refresh your browser so it is not looking at a cached page? Did you edit the language file that is actually being used in your site, course or by the user?
Tip: Can't find the string you wish to change? Tick the 'Show origin of languages strings' checkbox in Settings > Site administration > Development > Debugging then visit the page containing the string you want to customize.

Background

Moodle is translated into many languages - see Moodle.org: Language packs 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.

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.

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.

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

Using Language customization tool

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.

Workflow of the language customization (click to enlarge)


Check out strings into translator

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.

Tip: There is currently a problem with "execution time". If you get the "Fatal error: Maximum execution time of 180 seconds exceeded" message, you will have to press the button 'Check out string into translator' several times to get the operation completed. See forum discussion.

Use filter to find the strings you want to customize

Moodle 2.0 language filter

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.
  • 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.
Note: Starting 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 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.

Click button 'Show strings' for potential editing.

Input your own translation

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.

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.

Saving your work into files

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:

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

Writing the modifications into files

During the checkin, the contents of the translator database are dumped into files in moodledata/lang/xx_local/ directory.

Click "Save and check in strings into files" to process all changes made into your local language pack.

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.