• Introduction
• What is Booktype?
• Roles and Permissions
• Getting Started
• My Dashboard
• Control Center
• Books
• Creating a Book
• Importing a Book
• Deleting a Book
• The Edit Interface
• Creating Chapters
• Editing a Chapter
• The Table of Contents
• Adding Images
• Settings
• Publishing
• Groups
• Creating a Group
• Joining a Group
• Adding a Book to a Group
• People
• Communicating
• Design
• Formless Content
• Adding CSS
• Learn by Sharing
• Table of Contents Style
• Copyright
• Sections
• Front Page
• Footers
• Some Tricks
• Advanced
• Command Line Admin
• Theming the Interface
• Localizing the Interface
• Installation
• Before you install
• Setting up the database
• Installation on GNU/Linux
• Installation on OS X
• Help
• Where to get support
• About this manual

Localizing the Interface

The Booktype interface can be localized using the standard GNU gettext method. Using GitHub for this task means you don't have to tackle the whole of a localization yourself; just as much as you can manage.

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 GitHub repository for Booktype at https://github.com/sourcefabric/Booktype/tree/devel. 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.

GNU gettext means using 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.

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 next major version of the software is done in the devel branch of each project, so that's the branch to checkout after you have made the initial git clone.

In the locale code de_DE, de represents the German language and the suffix _DE indicates the dialect spoken in the country of Germany. Some languages have a wide variety of dialect localizations, which can be differentiated with a suffix in this way. You should update the header information in the .po file, which includes the language code and a country code, using one of the existing .po files as a guide.

Booktype has two components to translate: lib/booki and lib/booktypecontrol. After forking the Booktype git repository, make sure you're in the devel branch:

git branch
* devel
  master

Create new locale directories (e.g. locale/de_DE/LC_MESSAGES/ for German as spoken in Germany) for each component:

mkdir -p lib/booki/locale/de_DE/LC_MESSAGES/
mkdir -p lib/booktypecontrol/locale/de_DE/LC_MESSAGES/

Then in each component directory, run the makemessages command, e.g: for German:

cd lib/booki
django-admin.py makemessages -l de_DE
cd ../../lib/booktypecontrol
django-admin.py makemessages -l de_DE

and update the header information in the django.po file which will be created in the appropriate directory. 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 git 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.