Booktype 2.3 for Authors and Publishers
Localizing the Interface
The Booktype user interface can be localized using standard GNU gettext files. Using the web-based Transifex platform for this task means you don't have to tackle the whole of a localization yourself; just as much as you can manage. Transifex also hides the raw gettext files from the translator behind an easy-to-use interface.
First, you should check if a localization is already under way for your locale of choice. The best way to do this is to take a look at the Transifex project https://www.transifex.com/projects/p/booktype
You can also ask in the Booktype development forum at http://forum.sourcefabric.org/categories/booktype-development, where you might find community members who can help you with the translation.
To join an existing localization project or start a new one on Transifex, you will need to sign up for a translator account, which is free of charge. There is a guide on how to use the Transifex system at http://docs.transifex.com/guides/txeditor and support for translators is also available in the Booktype forum.
Booktype has four resources which can be translated: lib/booki and lib/booktype (the Booktype editing interface), lib/booktypecontrol (the Booktype Control Centre), and the Debconf templates (used in the Debian and Ubuntu GNU/Linux package installer).
The gettext format
If you do not wish to use Transifex, it is possible to work directly on the raw translation files. GNU gettext uses a .po file for each language or dialect, a specially formatted plain text file with groups of three or more lines, like this example from Booktype's Russian localization:
#: account/templates/account/create_group.html:9 msgid "There is already a group with this name." msgstr "Группа с таким названием уже существует."
The first of these three lines starts with the hash symbol, and references where this string of text is found in the source code by its file name and line number. If this string is found more than once in the source code, you will see other reference lines here. The second line contains the msgid, which is the original version of the string. The third line contains the msgstr, which is the translation of that string for the localization that this particular .po file relates to.
If you use the cross-platform program Poedit http://www.poedit.net/ to edit the .po file, this formatting of the text is hidden by an easy-to-use GUI. Poedit can be installed on most GNU/Linux distributions using the standard software installer. Versions of Poedit for Mac and Windows are available for free download from the project's homepage.
Before manually translating strings in poedit from scratch, you should take a look at the online translation services available which can fill in many of the msgstr's for you, such as Google's Translation Toolkit http://translate.google.com/toolkit/ which supports gettext .po files. You can then use poedit to fine-tune the localization and fix any formatting errors produced by the automatic translation.
Contributing to Booktype via git
The GitHub repository for Booktype is at https://github.com/sourcefabric/Booktype. If you don't already have a GitHub account, you can sign up at https://github.com/signup/free. Once you have a GitHub account, you can fork a copy (https://help.github.com/articles/fork-a-repo) of the Booktype project. Work for the current version of the Booktype software is done in the master branch, so that's the branch to checkout after you have made the initial git clone. See the chapters on manual installation to test your changes.
After forking the Booktype git repository to 'your-username' account, make sure you're in the master branch:
git clone git@github.com:your-username/Booktype.git git checkout master
The git program should respond:
Switched to branch 'master'
The git branch command indicates the active branch with an asterisk:
git branch devel * master
Booktype uses ISO 639-1 codes (http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) to identify languages. Create new locale directories (e.g. locale/el/LC_MESSAGES/ for Greek) for each component:
mkdir -p lib/booktype/locale/el/LC_MESSAGES/ mkdir -p lib/booktypecontrol/locale/el/LC_MESSAGES/
Then in each component directory, run the makemessages command, e.g: for Greek:
cd lib/booktype django-admin.py makemessages -l el cd ../../lib/booktypecontrol django-admin.py makemessages -l el
and update the header information in the django.po file which will be created in the appropriate directories.
# Greek translation for Booktype Control Centre # Copyright (C) 2014 Booktype contributors # This file is distributed under the same license as the Booktype package. # A. Translator <translator@example.com>, 2014. # msgid "" msgstr "" "Project-Id-Version: Booktype 2.0\n" "Report-Msgid-Bugs-To: contact@sourcefabric.org\n" "POT-Creation-Date: 2014-11-11 11:28+0000\n" "PO-Revision-Date: 2014-11-12 10:42+0000\n" "Last-Translator: A. Translator <translator@example.com>\n" "Language-Team: Booktype Localization <contact@sourcefabric.org>\n" "Language: el\n"
Or use one of the existing .po files as a template and copy it manually into the appropriate directory, if you do not have a Django development environment set up.
After using an online translation tool to get started, if necessary, you can load the .po file into poedit and complete your translation. Enter the localization team's contact information and language into poedit's Edit -> Preferences and Catalog -> Settings dialogs, which will be added to the .po file. When you save a .po file in poedit, the corresponding binary .mo file will be compiled automatically.
Finally, git add, git commit and git push these new .mo and .po files to your GitHub fork of the project, and send a git pull request (https://help.github.com/articles/using-pull-requests) to the Booktype developers. The localization can then be added to a forthcoming Booktype release.
If you don't want to work with git, that's no problem - download a copy of the .po file you would like to localize, run it through Google Translate and check it with poedit, and email your contribution to the Booktype team as an attachment - it will be very welcome! However, learning to use Transifex or GitHub is a good idea, because it means you can work directly on the source code, share the localization work with the Booktype community, and avoid duplicated effort.