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).
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.
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.
Identify the product. (The element identifiers in the HTML often point to the product that needs to be changed.)
Add a
locales
directory to the product, in the same directory that has theconfigure.zcml
file.Add i18n to the Python code.
To the
__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')
Identify the Python products that contain strings that need translating. To each add the following
import
:from . import GSMessageFactory as _
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})
Add i18n to the page templates.
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">
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-->
Add
i18n:name
attributes to dynamic content.<span class="group" i18n:name="groupName" tal:content="view/groupInfo/name">this group</span>
Add
i18n:attributes
attributes to dynamic attributes.<a title="Change this About box" i18n:attributes="title admin-change-button-title">Change</a>
Add i18n to the Zope Configuration file.
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">
Add the
reigsterTranslations
element<i18n:registerTranslations directory="locales" />
Run the latest version of
i18n.sh
[1] in the base directory of the product to create and update the translation.Fill out the English translation, which is used as the source translation for Transifex.
Commit the changes.
Add the product to Transifex [2].
In the GroupServer organisation on Transifex, click on Add project.
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.
- Use the GroupServer product identifier as the name
(e.g.
Assign to the project to the GroupServer Team.
Skip “Add content”.
Create the project.
View the new project.
Choose the Manage link.
Under Project URL, add hyphens where Transifex has removed dots from the project name (e.g.
gssiteabout
→gs-site-about
).Optionally add a Long Description from the Introduction section of the product
README.rst
.Save.
Update the
README.rst
to include a Transifex link in the Resources section.- Translations: https://www.transifex.com/projects/p/gs-group-encouragement/
Initialise the product, accepting the defaults:
$ tx init
Run
tx-set.sh
[3] in the base directory of the product.Sync local source and translations to remote:
$ tx push -s -t
Pull the translations, now modified by Transifex from remote to local:
$ tx pull -a
Commit the Transifex configuration (
.tx/
) and the modified translations to version control.
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.
Update the
pot
file and thepo
files by running thei18n.sh
script in the root of the product [1].Update the English
po
file, copying the default text into themsgstr
. 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.)Push the changes in the source file to Transifex, using the Transifex client (
tx
):$ tx push -s
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.
Pull the updated translations (in
po
files) from the Transifex project using the Transifex client (tx
):$ tx pull -a
Ensure that Zope is set up to automatically compile the
po
files tomo
files:$ export zope_i18n_compile_mo_files=true
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.
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> |