Translating

Last modified
Sunday, November 6, 2016 - 11:31

Executive summary

If you want to help translating LedgerSMB and join the LedgerSMB translation project at Transifex.

Introduction

LedgerSMB uses the same method many open source programs use for their internationalization support: Strings in the source code are specifically marked. Later, a program extracts the marked strings. These strings are compiled into a lexicon; this lexicon is stored in a file with a '.pot' extension. In LedgerSMB's case, this is a file with the name LedgerSMB.pot.

Translators then translate the strings in the lexicon. The output is stored in so-called '.po' files.

When the program runs, the strings which are marked for translation are looked up in these '.po' files based on the language settings from the user, showing the translated program.

Translating LedgerSMB thus means translating the strings in the lexicon.

The translation workflow

In order to keep a translation current, the following steps will need to be executed upon each iteration:

  1. Extract the current set of translated strings from the sources, written into the lexicon (.pot)
  2. Update the translation files (.po) with any new strings to be translated
  3. Add translations for new strings to translation files (.po)
  4. Include updated translation files in the project for release

Steps (1) and (2) have been automated by the project: the lexicon and translation files will be updated on a regular basis, but at least when a release happens.

Step (4) has been automated by the project too, in order facilitate translators.

Translation & submission

The only remaining step in the translation workflow is to update the translation files. For this step, the project depends on services offered by Transifex. They run a cloud-based translation-support service which supports a very wide range of translator and submission workflows.

Quick start

The quickest way to get started is probably Transifex's web-based translation. It allows to translate software just by signing up, navigating to the LedgerSMB dashboard page and clicking on the Translate button on the right (near the top) of the screen. See their Getting started documentation and the Using the Transifex webeditor" tutorial for more details.

Transifex allows you to log in with many of the popular "Web login systems", such as GitHub, Google and Facebook!

Things to know

  • Transifex shows 3 resources: one for the current stable version (currently 1.4) and one for the version under development; you won't need to translate all strings twice! Transifex copies exact matches from one to the other resource, so you only translate the remaining strings in the second resource!
    • LedgerSMB: Resource for development version
    • LedgerSMB-14: Resource for stable release version
    • LedgerSMB-13: Resource for EOL version 1.3; there to benefit from work on the other 2
  • Many strings have square brackets, an underscore and a number in the string, like "Account [_1] not found". The bold section of the string gets replaced by a parameter; in this example: the number of the account.
    If a string requires more parameters, they are numbered from 1 up: [_1], [_2], ...
  • As a translator, you might run into inconsistencies or errors in the source strings. Please file tickets for those cases such as this example.
  • Strings marked fuzzy (in the .po file) or not reviewed will not be used by our translation library at run time; please do review all strings and mark them reviewed.

Offline translation

The online translation method works great as a quick start, but there's one big drawback: when the translator needs more context to understand the string being translated, the only thing (s)he has to go on is a listing of where the string appears in the sources.

Translation tools like poedit address that issue: with a push of a key, you can jump to the location in the source where the string occurs to understand the context. If you want to use this approach, you need to

  • Sign up with Transifex
  • Make sure you have a password in your account (User Settings -> Change password)
  • Clone the source tree from Github:
    $ git clone https://github.com/ledgersmb/LedgerSMB.git --single-branch

    This command creates a LedgerSMB directory in the directory it's started from.
  • Go to the cloned directory:
    $ cd LedgerSMB
     
  • Update the translation from Transifex service:
    $ tx pull -r ledgersmb.LedgerSMB -l <language-code>
     
  • Translate using poedit or another editor
     
  • Send the translations back to transifex:
    $ tx push -r ledgersmb.LedgerSMB -l <language-code>

The above assumes you have Git, the transifex client installed and poedit. On Debian/Ubuntu systems, these commands should do that:

# aptitude install git poedit python-pip
# pip install transifex-client

If you're not on a Debian/Ubuntu system, see Transifex's instructions for installation of their client.