4c33944bb9
- the new variable makes it easier to implement language buttons - a short howto on language buttons is also provided - the dictionary mapping template vars are now OrderedDict for consistent-looking language buttons
143 lines
6.5 KiB
ReStructuredText
143 lines
6.5 KiB
ReStructuredText
-----------------------------
|
|
Localizing themes with Jinja2
|
|
-----------------------------
|
|
|
|
1. Localize templates
|
|
---------------------
|
|
|
|
To enable the |ext| extension in your templates, you must add it to
|
|
*JINJA_EXTENSIONS* in your Pelican configuration
|
|
|
|
.. code-block:: python
|
|
|
|
JINJA_EXTENSIONS = ['jinja2.ext.i18n', ...]
|
|
|
|
Then follow the `Jinja2 templating documentation for the I18N plugin <http://jinja.pocoo.org/docs/templates/#i18n>`_ to make your templates localizable. This usually means surrounding strings with the ``{% trans %}`` directive or using ``gettext()`` in expressions
|
|
|
|
.. code-block:: jinja
|
|
|
|
{% trans %}translatable content{% endtrans %}
|
|
{{ gettext('a translatable string') }}
|
|
|
|
For pluralization support, etc. consult the documentation
|
|
|
|
To enable `newstyle gettext calls <http://jinja.pocoo.org/docs/extensions/#newstyle-gettext>`_ the *I18N_GETTEXT_NEWSTYLE* config variable must be set to ``True`` (default).
|
|
|
|
.. |ext| replace:: ``jinja2.ext.i18n``
|
|
|
|
2. Specify translations location
|
|
--------------------------------
|
|
|
|
The |ext| extension uses the `Python gettext library <http://docs.python.org/library/gettext.html>`_ for translating strings.
|
|
|
|
In your Pelican config you can give the path in which to look for translations in the *I18N_GETTEXT_LOCALEDIR* variable. If not given, it is assumed to be the ``translations`` subfolder in the top folder of the theme specified by *THEME*.
|
|
|
|
The domain of the translations (the name of each translation file is ``domain.mo``) is controlled by the *I18N_GETTEXT_DOMAIN* config variable (defaults to ``messages``).
|
|
|
|
Example
|
|
.......
|
|
|
|
With the following in your Pelican settings file
|
|
|
|
.. code-block:: python
|
|
|
|
I18N_GETTEXT_LOCALEDIR = 'some/path/'
|
|
I18N_GETTEXT_DOMAIN = 'my_domain'
|
|
|
|
… the translation for language 'cz' will be expected to be in ``some/path/cz/LC_MESSAGES/my_domain.mo``
|
|
|
|
|
|
3. Extract translatable strings and translate them
|
|
--------------------------------------------------
|
|
|
|
There are many ways to extract translatable strings and create ``gettext`` compatible translations. You can create the ``*.po`` and ``*.mo`` message catalog files yourself, or you can use some helper tool as described in `the Python gettext library tutorial <http://docs.python.org/library/gettext.html#internationalizing-your-programs-and-modules>`_.
|
|
|
|
You of course don't need to provide a translation for the language in which the templates are written which is assumed to be the original *DEFAULT_LANG*. This can be overridden in the *I18N_TEMPLATES_LANG* variable.
|
|
|
|
Recommended tool: babel
|
|
.......................
|
|
|
|
`Babel <http://babel.pocoo.org/>`_ makes it easy to extract translatable strings from the localized Jinja2 templates and assists with creating translations as documented in this `Jinja2-Babel tutorial <http://pythonhosted.org/Flask-Babel/#translating-applications>`_ [#flask]_ on which the following is based.
|
|
|
|
1. Add babel mapping
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Let's assume that you are localizing a theme in ``themes/my_theme/`` and that you use the default settings, i.e. the default domain ``messages`` and will put the translations in the ``translations`` subdirectory of the theme directory as ``themes/my_theme/translations/``.
|
|
|
|
It is up to you where to store babel mappings and translation files templates (``*.pot``), but a convenient place is to put them in ``themes/my_theme/`` and work in that directory. From now on let's assume that it will be our current working directory (CWD).
|
|
|
|
To tell babel to extract translatable strings from the templates create a mapping file ``babel.cfg`` with the following line
|
|
|
|
.. code-block:: cfg
|
|
|
|
[jinja2: ./templates/**.html]
|
|
|
|
|
|
2. Extract translatable strings from templates
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Run the following command to create a ``messages.pot`` message catalog template file from extracted translatable strings
|
|
|
|
.. code-block:: bash
|
|
|
|
pybabel extract --mapping babel.cfg --output messages.pot ./
|
|
|
|
|
|
3. Initialize message catalogs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you want to translate the template to language ``lang``, run the following command to create a message catalog
|
|
``translations/lang/LC_MESSAGES/messages.po`` using the template ``messages.pot``
|
|
|
|
.. code-block:: bash
|
|
|
|
pybabel init --input-file messages.pot --output-dir translations/ --locale lang --domain messages
|
|
|
|
babel expects ``lang`` to be a valid locale identifier, so if e.g. you are translating for language ``cz`` but the corresponding locale is ``cs``, you have to use the locale identifier. Nevertheless, the gettext infrastructure should later correctly find the locale for a given language.
|
|
|
|
4. Fill the message catalogs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The message catalog files format is quite intuitive, it is fully documented in the `GNU gettext manual <http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files>`_. Essentially, you fill in the ``msgstr`` strings
|
|
|
|
|
|
.. code-block:: po
|
|
|
|
msgid "just a simple string"
|
|
msgstr "jenom jednoduchý řetězec"
|
|
|
|
msgid ""
|
|
"some multiline string"
|
|
"looks like this"
|
|
msgstr ""
|
|
"nějaký více řádkový řetězec"
|
|
"vypadá takto"
|
|
|
|
You might also want to remove ``#,fuzzy`` flags once the translation is complete and reviewed to show that it can be compiled.
|
|
|
|
5. Compile the message catalogs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The message catalogs must be compiled into binary format using this command
|
|
|
|
.. code-block:: bash
|
|
|
|
pybabel compile --directory translations/ --domain messages
|
|
|
|
This command might complain about "fuzzy" translations, which means you should review the translations and once done, remove the fuzzy flag line.
|
|
|
|
(6.) Update the catalogs when templates change
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you add any translatable patterns into your templates, you have to update your message catalogs too.
|
|
First you extract a new message catalog template as described in the 2. step. Then you run the following command [#pybabel_error]_
|
|
|
|
.. code-block:: bash
|
|
|
|
pybabel update --input-file messages.pot --output-dir translations/ --domain messages
|
|
|
|
This will merge the new patterns with the old ones. Once you review and fill them, you have to recompile them as described in the 5. step.
|
|
|
|
.. [#flask] Although the tutorial is focused on Flask-based web applications, the linked translation tutorial is not Flask-specific.
|
|
.. [#pybabel_error] If you get an error ``TypeError: must be str, not bytes`` with Python 3.3, it is likely you are suffering from this `bug <https://github.com/mitsuhiko/flask-babel/issues/43>`_. Until the fix is released, you can use babel with Python 2.7.
|