diff options
| -rw-r--r-- | doc/administration.rst | 15 | ||||
| -rw-r--r-- | doc/developer.rst | 12 | ||||
| -rw-r--r-- | doc/developer/localize.rst | 134 | ||||
| -rw-r--r-- | doc/index.rst | 6 |
4 files changed, 163 insertions, 4 deletions
diff --git a/doc/administration.rst b/doc/administration.rst new file mode 100644 index 0000000..3c5cf7f --- /dev/null +++ b/doc/administration.rst @@ -0,0 +1,15 @@ +Administration Guide +==================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + administration/installation + administration/configuration + administration/upgrading + administration/backup + +This guide contains information pertaining to the administration of a Fietsboek +instance. This includes the installation, updating, configuration, and backing +up of Fietsboek. diff --git a/doc/developer.rst b/doc/developer.rst new file mode 100644 index 0000000..6b99851 --- /dev/null +++ b/doc/developer.rst @@ -0,0 +1,12 @@ +Developer Guide +=============== + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + developer/localize + +This guide contains information for developers that want to modify or extend +Fietsboek. This includes information on how to localize Fietsboek to new +languages. diff --git a/doc/developer/localize.rst b/doc/developer/localize.rst new file mode 100644 index 0000000..c345c3e --- /dev/null +++ b/doc/developer/localize.rst @@ -0,0 +1,134 @@ +Localizing Fietsboek +==================== + +Most of the localization in Fietsboek is done using the `gettext +<https://www.gnu.org/software/gettext/>`__ machinery to provide translated +messages. Additionally, `Babel <https://babel.pocoo.org/en/latest/>`__ is used +to provide localized number and date formatting. + +In addition to ``gettext``-based messages, some longer texts are also provided +as stand-alone files in their respective language directories. + +The ``gettext`` Machinery +------------------------- + +The ``gettext`` machinery depends on three files: + +The ``.pot`` files are the template files that contain all the messages that +need to be translated. They are generated by walking through the source code +and finding marked translation strings. + +The ``.po`` files are translations, initialized from the ``.pot`` template. For +every language, a ``.po`` file contains the translated messages and can be +edited by the translator. + +Finally, the ``.mo`` files are compiled versions of the ``.po`` files, intended +to be more efficient. + +Extracting Messages +------------------- + +.. note:: + + This section can be skipped if you only intend on creating a new + translation. It is only important if you introduce new features with new + messages to the code. + +If you introduce new messages in Fietsboek, it is important to regenerate the +``.pot`` template. Only then can translations for your messages be added. + +In order to do so, use the :program:`pybabel` binary: + +.. code:: bash + + .venv/bin/pybabel extract -F babel.cfg -o fietsboek/locale/fietslog.pot --input-dirs=fietsboek + +The :file:`Makefile` contains a shortcut for this command: + +.. code:: bash + + make babel-extract + +Creating a New Language +----------------------- + +If you want to add a translation for a language that does not yet exist, first +generate the ``.po`` file containing the messages using :program:`pybabel`: + +.. code:: bash + + # Replace LOCALE with the locale name, for example "nl" or "fr" + .venv/bin/pybabel init -d fietsboek/locale -l LOCALE -i fietsboek/locale/fietslog.pot + +Again, there is a shortcut in the :file:`Makefile`: + +.. code:: bash + + make babel-init LOCALE=nl + +This will create the directory :file:`fietsboek/locale/{language}`. + +Finally, you need to copy the non-gettext messages. This is best done by +copying over the english original texts: + +.. code:: bash + + # Replace nl with the locale that you just generated + cp -r fietsboek/locale/en/html fietsboek/locale/nl/ + +Updating a Language +------------------- + +When features and messages get added to Fietsboek, it is important to keep the +message catalogues up to date: + +.. code:: bash + + # Replace nl with the locale that you want to update + .venv/bin/pybabel update -d fietsboek/locale -l nl -i fietsboek/locale/fietslog.pot + +This ensures that every message from the template is also present in the +language's message catalogue, ready for translation. + +Alternatively, you can also use the shortcut again: + +.. code:: bash + + make babel-update LOCALE=nl + +Translating +----------- + +Once you have the ``.po`` file generated (either by initializing a new language +or by updating an existing one), it is time to actually translate messages. +This is done by editing the +:file:`fietsboek/locale/{language}/LC_MESSAGES/messages.po` file. This can be +done either by using a standard text editor, or by using a specialized tool +like :program:`poedit`. + +After translating the messages, the files in +:file:`fietsboek/locale/{language}/html` should also be translated. For this, a +text editor or a HTML editor can be used. + +Compiling the Messages +---------------------- + +To generate the machine readable message format, the message catalogue has to +be compiled: + +.. code:: bash + + # Replace nl with the locale that you want to compile + .venv/bin/pybabel compile -d fietsboek/locale -l nl -i fietsboek/locale/nl/LC_MESSAGES/messages.po + +Or using the shortcut: + +.. code:: bash + + make babel-compile LOCALE=nl + +Further Reading +--------------- + +* The Pyramid documentation: `Internationalization and Localization + <https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/i18n.html>`__ diff --git a/doc/index.rst b/doc/index.rst index 05449cd..a0b9d4f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,10 +10,8 @@ Welcome to Fietsboek's documentation! :maxdepth: 2 :caption: Contents: - administration/installation - administration/configuration - administration/upgrading - administration/backup + administration + developer Fietsboek is a self-hostable sharing site for GPX track recordings with social features. The goal is to have an application like `MyTourbook |