Translation Server

From Koha Wiki

Jump to: navigation, search

The Koha Translation Server hosts files necessary to translate Koha into various languages. It's based on Pootle.


Workflow for translators

The Pootle server hosts projects containing languages containing translation files. There is one project per Koha version. In each project, there are languages, and in languages there are .po files. Instead of one big po file, there are multiple for different parts of Koha (OPAC, staff interface, help, ...).

The Pootle Server can be used directly by translators to translate online, in a collaborative environment. This is the easiest way for a team of translators to work together. It's also possible to work offline, using a desktop .po file editor which allows to translate faster than the Pootle web editor.

The integration of translation files, or resulting files, into Koha itself, follows two main stages :

  • String Freeze. At this stage, the Koha development team decides that the Koha code is fixed and ready to be released. The new and modified strings of this Koha version that need translation are extracted and added to the .po files by the Translation Manager. The Koha Translation Server is updated with those files and an email will be sent to the koha-translate mailing list.
  • Koha Release. Just prior Koha release, generally a week after String Freeze, .po files are pulled from the Translation Server by the Translation Manager, and sent to the Release Manager who includes them into the released version.

Translating online

Translating online using Pootle is the preferred way of doing translations since it will allow multiple people to work together.

Translating offline

Translators working offline must follow this workflow:

  • The .po files are downloaded from Pootle
  • The translation is done offline in a .po file editor
  • The locally edited .po files are uploaded back to the Pootle server

Important: Translators have to be very careful and must avoid keeping .po files locally for a long time. Otherwise the files might get outdated, missing the latest changes, especially if they are kept beyond string freeze. Another problem is that uploading the files can overwrite another translator's work, so it's important to make sure that this doesn't happen. It's recommended to upload local modifications daily.

When the Release Manager announces String Freeze, translators have to:

  • wait for the email to the koha-translate mailing list
  • download all .po files from Pootle
  • process all files
  • upload all files to Pootle prior release date and before next String freeze!


The Translation Manager role, among others, is to coordinate with the Release Managers and Maintainers in order to periodically update the translation files hosted on the translation server. The .po files have to be synchronized with the Koha code repository.

NOTE: For the time being, .po files are included in the Koha main git repository. There is an ongoing discussion about splitting Koha code and Koha translation files: Git Splitting and Shrinking

Pootle stores translations in a database for efficiency. .po files have to be put in and pulled out the database. The Pootle command line script is used to synchronize the Pootle DB with the Koha git repository:

  • ./ sync_stores – save the Pootle DB contents into .po files
  • ./ update_stores – update the Pootle DB with the .po files content

File naming

The Koha naming convention for languages differs from the Pootle one. A translation of the language code has to be made based on this equivalence table:

Koha        Pootle  Comment

am-Ethi     am      OPAC
ar-Arab     ar      OPAC
az-AZ       az      Azéry
ca-VA       ca      Catalan
da-DK       da      Danish
de-DE       de      German
el-GR       el      Greek
en-GB       en_GB   English, Great Britain
en-NZ       en_NZ   English New Zealand
es-ES       es      Castillan, Spain
fr_CA       fr_CA   French (Canada)
fr-FR       fr      French
hi          hi      Hindi
hr-HR       hr      Croatian
hu-HU       hu      Hungarian
it-IT       it      Italian
ja-Jpan     ja      Japan
mi-NZ       mi      Maori
mon         mn      Mongol
nb-NO       nb      Norvegian (Bokmål)
nl-BE       nl      Dutch (Belgium) 
nl-NL       nl_NL   Dutch (Nederland)
nn-NO       nn      Norwegian Nynorsk
pl-PL       pl      Polish
pt-PT       pt      Portuguese (Portugal)
pt-BR       pt_BR   Portuguese (Brazil)
ro-RO       ro      Romanian
ru-RU       ru      Russian
sv-SE       sv      Swedish
tet         tet     Tetum
th-THA      th      Thai
tr-TR       tr      Turkish
uk-UA       uk      Ukranian
zh-Hans-CN  zh_CN   Chinesee (China)
zh-Hans-TW  zn_TW   Chinesse (Taiwan)

From Koha to Pootle (String Freeze)

Version Branch. On a box having a Koha git repository, on the Pootle server itself or on another machine, a branch is created based on targetted Koha version. This branch will be used to update .po files. For example, for a Koha 17.05.0 version

git checkout branch 17.05.0 origin/17.05.x
git checkout -b 17.05.0-freeze

DB Sync. On the Pootle server, strings from the Pootle DB are synced with the system .po files using sync_stores

For example:

cd ~/Pootle-2.1.6
./ sync_stores --project=1705
cd ..
mkdir po_tocopy
koha-pootle pootle-to-koha Pootle-2.1.6/po/1705 po-tocopy --doit
cd po-tocopy
scp * <<git repository>
cp <local directory>

koha-pootle is a specific script which renames files from one convention to the other.

    • .po files update**. In the Koha git repository, copied .po files are updated with new/modified strings.
cd <koha-repo>/misc/translator
./translate update

After updating the translations, there are a lot of lines at the end of the .po files to delete. They look like that:

#~ msgid ""
#~ "the left part contains six elements, some are automatically calculated "
#~ "but but can be changed"
#~ msgstr ""
#~ "der linke Teil enthält sechs Elemente, einige davon werden automatisch "
#~ "berechnet, können aber geändert werden"

#~ msgid "the records this subject is applied to. "
#~ msgstr "die Datensätze, mit denen dieses Thema verbunden ist. "

#~ msgid "the selected"
#~ msgstr "die markierten"

To delete all those lines and consecutive blank lines:

perl -i -ne 'print if ! /^#\~/' po/*.po
perl -i -00 -pe '' po/*.po

Copy. .po files are copied on the Pootle server if necessary.

Renaming. Koha .po files are renamed. For example:

cd po-tocopy
cd ../Pootle-2.1.6
koha-pootle koha-to-pootle ../potocopy po/1705 --doit

Update Pootle DB

./ update_stores --project=1705

From Pootle to Koha

Release Branch. On the Koha git repository a branch is created, for example for a 17.05.0 release:

git checkout -b 17.05.0-translate origin/17.05.x

Pootle DB to .po files. Strings from Pootle DB are copied into .po files.

cd ~/Pootle-2.1.6
./ sync_stores --project=1705

Renaming. .po files are renamed from Pootle convention to Koha one:

cd ../po-tocopy
rm *
koha-pootle pootle-to-koha --doit ../Pootle-2.1.6/po/1705 .

Copy. Renamed .po files are copied to the Koha git repository.

Pull Branch. A Branch is prepared for the Release Manager and a pull request is sent to them.

git commit -a
git push tm-public-git-repository 17.05.0-translate
git request-pull HEAD^ git://tm-public-git-repository-url/git/koha

Tips and tricks

Invalid syspref translation. Sometime, syspref strings haven't been properly translated. You have for example:

acquisitions.pref#AcqCreateItem# Crear un ítem cuando

When the valid string is:

Crear un ítem cuando

A Perl onliner can transform the who syspref .po file:

perl -i -pe 's/msgstr .*# (.*)"/msgstr "$1"/' po/es-ES-pref.po

Duplicated lines in syspref .po files

for i in *pref*; do echo $i; uniq $i>t.pref; cp t.pref $i; done
Personal tools