Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
328 lines (220 sloc) 10.3 KB
.. index:: !Internationalisation, !i18n, !Localisation, !l10n

Translation guide

Authors:Alice Rose; Michael JasonSmith;
Contact:Michael JasonSmith <mpj17@onlinegroups.net>
Date:2015-02-18
Organization:GroupServer.org
Copyright:This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net.

Introduction

GroupServer is written in English, and the interface has been partly translated into French and German. In this guide we work through how to translate GroupServer, how to add internationalisation (i18n), and finally we discuss how to update the products.

Change the language

Your browser determines the language that is chosen when GroupServer displays a page. To change what language is chosen alter the Preferred languages, or Language and input setting in your browser preferences (options).

.. index:: Translation, !Transifex

Translate GroupServer

Anyone can help improving the translations of GroupServer! We use the Transifex system to help make the translations: it is a web-based system that allows you to translate GroupServer bit by bit. All you need is a browser. If you have any questions please feel free to ask away in the GroupServer development group.

.. index:: Development

Add internationalisation (i18n)

Adding internationalisation support to a product that lacks it is a development task. If you come across a component of GroupServer that lacks a translation please ask for i18n to be added in the GroupServer development group. The person who responds (probably either Michael JasonSmith or Alice Rose) will then carry out the following tasks.

  1. Identify the product. (The element identifiers in the HTML often point to the product that needs to be changed.)

  2. Add a locales directory to the product, in the same directory that has the :file:`configure.zcml` file.

  3. Add i18n to the Python code.

    1. To the :file:`__init__.py` for the product instantiate a message factory, passing the name of the product as an argument:

      from zope.i18nmessageid import MessageFactory
      GSMessageFactory = MessageFactory('gs.groups')
    2. Identify the Python products that contain strings that need translating. To each add the following import:

      from . import GSMessageFactory as _
    3. Add i18n to all the strings:

      • All strings, including the simple ones, get a label with the default (English) text following. The label make Transifex much easier to deal with.

        @form.action(name="change", label=_('change-action',
                                            'Change'),
                     failure='handle_change_action_failure')
        def handle_invite(self, action, data):

        When actually adding i18n to a command button in a zope.formlib form remember to set a name, that way the element-identifier will be the same no matter the language.

      • Complex strings have a mapping keyword argument, and a ${} template syntax (rather than {} for Python format-strings).

        _('start-status',
          'The group ${groupName} has been started.',
          mapping={'groupName': r})
  4. Add i18n to the page templates.

    1. Add the i18n namespace to the page template, using the product name as the domain.

      <html xmlns:i18n="http://xml.zope.org/namespaces/i18n"
            i18n:domain="gs.group.start">
    2. Add i18n:translate attributes to all elements that require translation. Always set the translation ID.

      <p id="group-id-error" style="display:none;" class="alert"
         i18n:translate="group-id-used">
         <strong class="label alert-label">Group ID In Use:</strong>
         The Group ID <code>above</code> is already being used.
         Please pick another group ID.
      </p><!--group-id-error-->
    3. Add i18n:name attributes to dynamic content.

      <span class="group" i18n:name="groupName"
            tal:content="view/groupInfo/name">this group</span>
    4. Add i18n:attributes attributes to dynamic attributes.

      <a title="Change this About box"
         i18n:attributes="title admin-change-button-title">Change</a>
  5. Add i18n to the Zope Configuration file.

    1. Add the i18n namespace

      <configure xmlns="http://namespaces.zope.org/zope"
                 xmlns:browser="http://namespaces.zope.org/browser"
                 xmlns:i18n="http://namespaces.zope.org/i18n">
    2. Add the reigsterTranslations element

      <i18n:registerTranslations directory="locales" />
  6. Run the latest version of i18n.sh [1] in the base directory of the product to create and update the translation.

  7. Fill out the English translation, which is used as the source translation for Transifex.

  8. Commit the changes.

  9. Add the product to Transifex [2].

    1. In the GroupServer organisation on Transifex, click on Add project.

    2. Fill in the Project Details form:

      • Use the GroupServer product identifier as the name (e.g. gs.site.about).
      • Source language is always English.
      • The License is always "Permissive open-source"
      • Source Code URL is the GitHub URL.
    3. Assign to the project to the GroupServer Team.

    4. Skip "Add content".

    5. Create the project.

    6. View the new project.

    7. Choose the Manage link.

    8. Under Project URL, add hyphens where Transifex has removed dots from the project name (e.g. gssiteaboutgs-site-about).

    9. Optionally add a Long Description from the Introduction section of the product :file:`README.rst`.

    10. Save.

    11. Update the :file:`README.rst` to include a Transifex link in the Resources section.

      - Translations:
        https://www.transifex.com/projects/p/gs-group-encouragement/
    12. Initialise the product, accepting the defaults:

      $ tx init
    13. Run tx-set.sh [3] in the base directory of the product.

    14. Sync local source and translations to remote:

      $ tx push -s -t
    15. Pull the translations, now modified by Transifex from remote to local:

      $ tx pull -a
    16. Commit the Transifex configuration (.tx/) and the modified translations to version control.

  10. Push all the changes to the repositories.

Update the products

Transifex and the product need to be kept in sync with each other. When the product changes it is necessary to update Transifex with the new strings. Likewise, when some translations have been completed it is necessary to update the product with the new translations.

Update Transifex with the new strings

To update a Transifex project with the new strings in a product carry out the following tasks.

  1. Update the pot file and the po files by running the i18n.sh script in the root of the product [1].

  2. Update the English po file, copying the default text into the msgstr. This is the source language that supplies the example text in Transifex. (Without this step the translations can still take place, but the translators see the message identifiers, rather than the default text.)

  3. Push the changes in the source file to Transifex, using the Transifex client (tx):

    $ tx push -s
  4. Commit and push the changes to the source-code repositories.

Update the product with the new translations

To update a product with the new translations in a Transifex project carry out the following tasks.

  1. Pull the updated translations (in po files) from the Transifex project using the Transifex client (tx):

    $ tx pull -a
  2. Ensure that Zope is set up to automatically compile the po files to mo files:

    $ export zope_i18n_compile_mo_files=true
  3. Start your development system. Change the language in your browser to test the different translations.

    Note

    Browsing the Web with a changed language will result in Goggle, Microsoft, the NSA, and Yahoo! getting some funny ideas about that languages you can comprehend.

  4. Commit and push the changes to the source-code repositories.

[1](1, 2) Download i18n.sh from <http://groupserver.org/downloads/i18n.sh>. It wraps the marvellous i18ndude: $ pip install i18ndude
[2]Ensure you have transifex-client 0.11.1 beta or later installed: $ pip install transifex-client==0.11.1.beta
[3]Download tx-set.sh from <http://groupserver.org/downloads/tx-set.sh>