mirror of
https://github.com/webrecorder/pywb.git
synced 2025-03-14 15:53:28 +01:00
12fcc87962
* add localization utilities: - add locmanager to support extract, update, remove, list using pybabel - add po2csv/csv2po conversion with translate-utils - docs: add localization.rst to manual! * add language switch header (via header.html) to all pages if more than one locale is present. * localization: wrap more text strings in templates in existing templates * docs: - document `wb-manager i18n` commands - mention `<html lang>` setting - include csv example - add info about adding localizable text in templates * add localization to CHANGES
148 lines
5.3 KiB
ReStructuredText
148 lines
5.3 KiB
ReStructuredText
.. _localizaation:
|
|
|
|
Localization / Multi-lingual Support
|
|
------------------------------------
|
|
|
|
pywb supports configuring different language locales and loading different language translations, and dynamically switching languages.
|
|
|
|
pywb can extract all text from templates and generate CSV files for translation and convert them back into a binary format used for localization/internationalization.
|
|
|
|
(pywb uses the `Babel library <http://babel.pocoo.org/en/latest/>`_ which extends the `standard Python i18n system <https://docs.python.org/3/library/gettext.html>`_)
|
|
|
|
Locales to use are configured in the ``config.yaml``.
|
|
|
|
The command-line ``wb-manager`` utility provides a way to manages locales for translation, including generatin extracted text, update translated text.
|
|
|
|
Adding a Locale and Extracting Text
|
|
===================================
|
|
|
|
To add a new locale for translation and automatically extract all text that needs to be translated, run::
|
|
|
|
wb-manager i18n extract <loc>
|
|
|
|
The ``<loc>`` can be one or more supported two-letter locales or CLDR language codes. To list available codes, you can run ``pybabel --list-locales``.
|
|
|
|
Localization data is placed in the ``i18n`` directory, and translatable strings can be found in ``i18n/translations/<locale>/LC_MESSAGES/messages.csv``
|
|
|
|
Each CSV file looks as follows, listing source string and an empty string for the translated version::
|
|
|
|
"location","source","target"
|
|
"pywb/templates/banner.html:6","Live on",""
|
|
"pywb/templates/banner.html:8","Calendar icon",""
|
|
"pywb/templates/banner.html:9 pywb/templates/query.html:45","View All Captures",""
|
|
"pywb/templates/banner.html:10 pywb/templates/header.html:4","Language:",""
|
|
"pywb/templates/banner.html:11","Loading...",""
|
|
...
|
|
|
|
|
|
This CSV can then be passed to translators to translate the text.
|
|
|
|
(The extraction parameters arae configured to load data from ``pywb/templates/*.html`` in ``babel.ini``)
|
|
|
|
|
|
For example, the following will generate translation strings for ``es`` and ``pt`` locales::
|
|
|
|
wb-manager i18n extract es pt
|
|
|
|
|
|
The translatable text can then be found in ``i18n/translations/es/LC_MESSAGES/messages.csv`` and ``i18n/translations/pt/LC_MESSAGES/messages.csv``.
|
|
|
|
|
|
The CSV files should be updated with a translation for each string in the target column.
|
|
|
|
The extract commannd add any new strings without overwriting existing translations, so it is safe to run multiple times.
|
|
|
|
|
|
Updating Locale Catalog
|
|
=======================
|
|
|
|
Once the text has been translated, and the CSV files updated, simply run::
|
|
|
|
wb-manager i18n update <loc>
|
|
|
|
This will parse the CSVs and compile the translated string tables for use with pywb.
|
|
|
|
|
|
Specifying locales in pywb
|
|
==========================
|
|
|
|
To enable the locales in pywb, add one or more locales can be added to the ``locales`` key in ``config.yaml``, ex::
|
|
|
|
locales:
|
|
- en
|
|
- es
|
|
|
|
Single Language Default Locale
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
pywb can be configured with a default, single-language locale, by setting the ``default_locale`` property in ``config.yaml``::
|
|
|
|
|
|
default_locale: es
|
|
locales:
|
|
- es
|
|
|
|
|
|
With this configuration, pywb will automatically use the ``es`` locale for all text strings in pywb pages.
|
|
|
|
pywb will also set the ``<html lang="es">`` so that the browser will recognize the correct locale.
|
|
|
|
|
|
Mutli-language Translations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If more than one locale is specified, pywb will automatically show a language switching UI at the top of collection and search pages, with an option
|
|
for each locale listed. To include English as an option, it should also be added as a locale (and no strings translated). For example::
|
|
|
|
locales:
|
|
- en
|
|
- es
|
|
- pt
|
|
|
|
will configure pywb to show a language switch option on all pages.
|
|
|
|
|
|
Localized Collection Paths
|
|
==========================
|
|
|
|
When localization is enabled, pywb supports the locale prefix for accessing each collection with a localized language:
|
|
If pywb has a collection ``my-web-archive``, then:
|
|
|
|
* ``/my-web-archive/`` - loads UI with default language (set via ``default_locale``)
|
|
* ``/en/my-web-archive/`` - loads UI with ``en`` locale
|
|
* ``/es/my-web-archive/`` - loads UI with ``es`` locale
|
|
* ``/pt/my-web-archive/`` - loads UI with ``pt`` locale
|
|
|
|
The language switch options work by changing the locale prefix for the same page.
|
|
|
|
Listing and Removing Locales
|
|
============================
|
|
|
|
To list the locales that have previously been added, you can also run ``wb-manager i18n list``.
|
|
|
|
To disable a locale from being used in pywb, simply remove it from the ``locales`` key in ``config.yaml``
|
|
|
|
To remove data for a locale permanently, you can run: ``wb-manager i18n remove <loc>``. This will remove the locale directory on disk.
|
|
|
|
To remove all localization data, you can manually delete the ``i18n`` directory.
|
|
|
|
|
|
UI Templates: Adding Localizable Text
|
|
=====================================
|
|
|
|
Text that can be translated, localizable text, can be marked as such directly in the UI templates:
|
|
|
|
1. By wrapping the text in ``{% trans %}``/``{% endtrans %}`` tags. For example::
|
|
|
|
{% trans %}Collection {{ coll }} Search Page{% endtrans %}
|
|
|
|
2. Short-hand by calling a special ``_()`` function, which can be used in attributes or more dynamically. For example::
|
|
|
|
... title="{{ _('Enter a URL to search for') }}">
|
|
|
|
|
|
These methods can be used in all UI templates and are supported by the Jinja2 templating system.
|
|
|
|
See :ref:`ui-customizations` for a list of all available UI templates.
|
|
|