The edX Learning Management System (LMS) is the application in the edX Platform that learners use to view and interact with courseware.
Because it presents XBlocks to learners and records their interactions, the LMS is also an XBlock runtime application.
As an XBlock developer, you must understand what XBlock properties the LMS requires.
The LMS requires XBlocks to have the following properties.
A view method named student_view
. This is the view that renders
the XBlock in the LMS for learners to see and interact with.
In addition, the student_view
method is used to render the XBlock in the
Studio preview mode, unless the XBlock also has an author_view
method.
For more information, see EdX Studio as an XBlock Runtime.
A class property named has_score
with a value of True
if the XBlock
is to be graded.
A class property named icon_class
, which controls the icon that displays
to learners in the unit navigation bar on the Course page when the XBlock
is in that unit. The variable must have one of the following values.
Value | Icon |
---|---|
problem |
|
video |
|
other |
The LMS is currently capable of supporting internationalization (i18n) and localization (l10n) of static UI text included in your XBlock – also known as “chrome” or “labels”. Translation of user-generated content stored as XBlock state is not currently supported.
To present XBlock language translations in the LMS you must include the translated strings for your chosen “locale” in the GNU Gettext Portable Object file format. Translated strings must be stored in a “domain” file named “text.po”.
Each “text.po” domain file consists of one or more string/translation pairs for the language/locale. Further, each translation pair consists of two fields: “msgid” for the base string, and “msgstr” for its corresponding translation.
There is no limit on the number of locales/domains that can be included with your XBlock. However, your specific Open edX installation may not be configured to support every locale that you provide.
You can learn more about the GNU Gettext Portable Object file format and download the GNU Gettext software using the following resources:
In addition to GNU Gettext, it is also possible to utilize the Open edX “i18n-tools” GNU Gettext wrapper to work with your XBlock locales and domains. You will need to modify the i18n-tools YAML configuration file to work with your XBlock project. More information about the i18n-tools project and its configuration file can be found at:
Create a directory within your XBlock code project named “translations”. This directory should be located at the same level in your code project as your XBlock implementation file. For example:
http://github.com/my_org/my_xblock/my_xblock/my_xblock.py
http://github.com/my_org/my_xblock/my_xblock/translations/
Create a set of language directories for each of your locales within this new “translations” directory. You may specify either a general language code or a specific language locale code for the name of each directory. Include an “LC_MESSAGES” directory with each language directory.
../my_xblock/translations/ar/LC_MESSAGES/
../my_xblock/translations/es-es/LC_MESSAGES/
Create a domain file named “text.po”. You can use the Gettext xgettext
command directly, or another tool
of your choosing, such as Django’s makemessages
utility, or i18n-tools. For more information on how to use
these tools, see the following resources.
Repeat the domain file creation process for each language/locale you support.
In the following example, we will use the i18n-tools utilites to generate a “text.po” file.
i18n_tool extract
to automatically find strings and populate the PO file.i18n_tool generate
to compile your human-readable PO file to a machine-readable “MO” binary fileOpen each “text.po” domain file and, for each “msgid” string, add a corresponding “msgstr” translation. PO files can be edited by hand, with a tool such as Pedit or Emacs, or through a third party service such as Transifex.
Place each locale’s “text.po” domain file within the corresponding “LC_MESSAGES” directory.
../my_xblock/translations/ar/LC_MESSAGES/text.po
../my_xblock/translations/es-es/LC_MESSAGES/text.po
Compile your “text.po” files into binary “text.mo” files using the Gettext msgfmt
command (or via the tool of
your choice), and include these “text.mo” files alongside your “text.po” files in your code project.
../my_xblock/translations/ar/LC_MESSAGES/text.mo
../my_xblock/translations/ar/LC_MESSAGES/text.po
The resulting directory/file structure should look like this.
/my_xblock
├── my_xblock.py
└── translations
├── ar
| └── LC_MESSAGES
| ├── text.mo
| └── text.po
├── es-es
| └── LC_MESSAGES
| ├── text.mo
| └── text.po
├── ru
| └── LC_MESSAGES
| ├── text.mo
| └── text.po
└── zh-cn
└── LC_MESSAGES
├── text.mo
└── text.po
You can now run the LMS and update your preferred language via Account Settings in order to observe the translated strings for your chosen locale.
Note
In the absence of an available language locale and domain file, the LMS XBlock runtime will attempt to match strings marked for translation within your XBlock using its own set of language locales and domains. However, it is not recommended that you rely on the LMS mechanism for internationalization support. There is no guarantee your strings will be matched by the LMS, and even if matches are found, the translations may be incorrect in the context of your specific XBlock.