Places to search for lang strings

From MoodleDocs
Jump to: navigation, search

Moodle has a mechanism that allows a number of places to be searched (in order) to find language strings or help files. This enables language strings and help to be packaged with optional plugins and avoids the step of having to copy the language files over to the language directory when a plugin is installed. This page provides some information about this mechanism which might be useful to plugin developers or those wishing to add a completely new pluggable feature to moodle.

This page covers both how to set up (core) Moodle to support a new plugabble resource and how to incorporate language elements in a plugin. Plugin writers really only need to read the last bit.


Basic concepts

When it is required to lookup a string or point to a help file, two basic items of information are required. The first is the name of the string (or the help filename) and the name of the module in which it can be found. For example, get_string('editingquiz','quiz') returns "Editing Quiz" in the current language; a call to help.php?module=label&file=mods.html displays the help for a label, again in the current language.

Plugin support extends this by defining a new format for the module name so that certain resources can both exist in core, the core distribution (and language packs) and be installed as options. The module name becomes type_plugin, where type is a generic name common to the plugin type and plugin is the name of the individual item. To illustrate this, here is an example. Blocks are a pluggable resource - the type name is block_ and the plugin name is the name of the individual block. Some examples of block module names are block_search (type is block_ and plugin is search) and block_online_users (type is block_ and plugin is online_users).

It is important to grasp that every block is now a discrete module type. This applies to all pluggable resources, so every, e.g., questiontype, authentication plugin, grade report is a separate module and will have its own language file and it's own directory for its help files. Not all plugin types define both language strings and help files but here is an example of what you might find for a pluggable resource that is included in core:

   Description: questiontype plugin for multichoice
   Module name: qtype_multichoice
   Language strings (English): question/type/multichoice/lang/en/qtype_multichoice.php
   Help files directory (English): question/type/multichoice/lang/en/help/qtype_multichoice/

All of the above must be in place for pluggable language and help strings to be a possibility for optional plugins.

NOTE: Module names cannot have numbers in them (only A-Z, a-z and underscore). This might be an issue to consider if you are moving from an existing architecture.

Defining the search path(s)

The next step is to define the search locations for the plugin. This is only needed to define where the optional plugins will be installed, the standard help locations will be searched automatically. This is done by adding an entry to the array defined in the function places_to_search_for_lang_strings located in lib/moodlelib.php. This should be obvious from viewing the code but don't forget to include the underscore!

In the past, some plugins define multiple locations for the same plugin type. For example, admin reports, course reports and quiz reports all have the plugin type report_. However, from Moodle 2.0 onwards, this is no longer allowed. Admin reports are report_, Course reports are coursereport_ and quiz reports are quiz_.

Viewing this function will also show you what Moodle elements currently support language string searching. This varies somewhat from version to version of Moodle as new locations are added.

Adding language support to a plugin

If you are a plugin writer and you didn't read the first part of this you just need to be aware that your plugin name needs to start with the generic type for the plugin. For example all questiontype plugins must be prefixed qtype_, all authentication plugins auth_. Moodle uses this prefix to identify the language search path.

All that remains is now to add the language support to the optional plugin(s). This is done by creating a lang subdirectory in the plugin directory. The structure of the lang directory is then the same as the "main" language directory with one exception - the help directory name should not have the type_ part of the module name (this might be a bug really!). Example...

   Description: Drag & Drop optional question type
   Module type: qtype_
   Module name: qtype_dragdrop
   Language file location (English): contrib/plugins/question/type/dragdrop/lang/en/qtype_dragdrop.php
   Help file directory (English): contrib/plugins/question/type/dragdrop/lang/en/help/dragdrop/

(Note: the help file directory is called dragdrop in the plugin. Compare this with the multichoice question type in core where the help folder is qtype_multichoice)

See also

Personal tools
User docs (English)