This XBlock comes with a Docker test environment ready to build, based on the xblock-sdk workbench. To build and run it:
$ make dev.run
The XBlock SDK Workbench, including this XBlock, will be available on the list of XBlocks at http://localhost:8000
Internationalization (i18n) is when a program is made aware of multiple languages. Localization (l10n) is adapting a program to local language and cultural habits.
Use the locale directory to provide internationalized strings for your XBlock project. For more information on how to enable translations, visit the Open edX XBlock tutorial on Internationalization.
This cookiecutter template uses django-statici18n
to provide translations to static javascript using gettext
.
The included Makefile contains targets for extracting, compiling and validating translatable strings. The general steps to provide multilingual messages for a Python program (or an XBlock) are:
- Mark translatable strings.
- Run i18n tools to create raw message catalogs.
- Create language specific translations for each message in the catalogs.
- Use
gettext
to translate strings.
Mark translatable strings in python:
from django.utils.translation import ugettext as _ # Translators: This comment will appear in the `.po` file. message = _("This will be marked.")
See edx-developer-guide for more information.
You can also use gettext
to mark strings in javascript:
// Translators: This comment will appear in the `.po` file. var message = gettext("Custom message.");
See edx-developer-guide for more information.
This cookiecutter template offers multiple make targets which are shortcuts to use edx-i18n-tools.
After marking strings as translatable we have to create the raw message catalogs.
These catalogs are created in .po
files. For more information see
GNU PO file documentation.
These catalogs can be created by running:
$ make extract_translations
The previous command will create the necessary .po
files under
poll-xblock/poll_xblock/conf/locale/en/LC_MESSAGES/text.po
.
The text.po
file is created from the django-partial.po
file created by
django-admin makemessages
(makemessages documentation),
this is why you will not see a django-partial.po
file.
After creating the raw message catalogs, all translations should be filled out by the translator.
One or more translators must edit the entries created in the message catalog, i.e. the .po
file(s).
The format of each entry is as follows:
# translator-comments A. extracted-comments #: reference… #, flag… #| msgid previous-untranslated-string msgid 'untranslated message' msgstr 'mensaje traducido (translated message)'
For more information see GNU PO file documentation.
To use translations from transifex use the follow Make target to pull translations:
$ make pull_translations
See config instructions for information on how to set up your transifex credentials.
See transifex documentation for more details about integrating django with transiflex.
Once translations are in place, use the following Make target to compile the translation catalogs .po
into
.mo
message files:
$ make compile_translations
The previous command will compile .po
files using
django-admin compilemessages
(compilemessages documentation).
After compiling the .po
file(s), django-statici18n
is used to create language specific catalogs. See
django-statici18n
documentation for more information.
To upload translations to transiflex use the follow Make target:
$ make push_translations
See config instructions for information on how to set up your transifex credentials.
See transifex documentation for more details about integrating django with transiflex.
Note: The
dev.run
make target will automatically compile any translations.Note: To check if the source translation files (
.po
) are up-to-date run:$ make detect_changed_source_translations
Django will automatically use gettext
and the compiled translations to translate strings.
If there are any errors compiling .po
files run the following command to validate your .po
files:
$ make validate
See django's i18n troubleshooting documentation for more information.