po-introduction


Introduction

This document is for you if you're kinda new to .po based translations. I've written it because I couldn't find a short and to-the-point introduction to .po files.

What are .po files?

.po files are translation files used by the gettext i18n system. It contains text items as to be found in source-code, almost always in english. A .po file is used by gettext to dynamically replace the english text by localized text during a program execution, according to your locale environment (try the locale command to inspect yours).


Explanation

A developer will give you a potfile. Usually it's named after the project name, and the file extension is .pot - for example, frozen-bubble.pot. Your first task is to rename it after the name of the language you're translating to, and to use the .po extension. For example, for a translation into french, rename it to fr.po.

It's now time to examine the contents of the file to perform the translations. In a .po file, you see entries like this:

    #: src/name.c:36
    msgid "My name is %s.\n"
    msgstr ""

It indicates that in line 36 of file src/name.c, there is a translatable text string which is My name is %s.\n (note: \n is a special sequence which produces a newline).

Your job as a translator is to insert the translation after the msgstr label, below every msgid. It looks like this (let's tell I'm translating to l33t english):

    #: src/name.c:36
    msgid "My name is %s.\n"
    msgstr "My n@me is %s.\n"

The %s to be found in some strings is a placeholder for dynamic replacement; in this example, %s will probably be replaced by the name the user would have entered - if you have doubts about the meaning of a text entry, don't hesitate to look in the source code or to ask the developers.

This was simple. Now, when sourcecode changes, fortunately translation doesn't need to be redone entirely. Gettext has a merge feature, which produces three types of entries:

Post-merge: 1st category of entries

    #: src/name.c:36
    msgid "My name is %s.\n"
    msgstr "My n@me is %s.\n"

It means the translatable string has not changed in sourcecode, so not need to work on it.

Post-merge: 2nd category of entries

    #: src/name.c:39
    #, fuzzy
    msgid "My name really is %s!\n"
    msgstr "My n@me is %s.\n"

The #, fuzzy above an msgid label indicates it is a new translatable string, and gettext tried to guess a good translation based on another one in the file; the translation is almost always false of course, but it can a a good base. You need to update the msgstr translation, and then remove the fuzzy indication, so that you end up with something like:

    #: src/name.c:39
    msgid "My name really is %s!\n"
    msgstr "My n@me really is %s!\n"

Warning: it's very important to remove the #, fuzzy line, as the translation item would be ignored by gettext if this is not done!

Post-merge: 3rd category of entries

    #: src/name.c:42
    msgid "I don't know your name...\n"
    msgstr ""

It's a new item, which was far enough from others for not generating a fuzzy; this, you have to translate as usual:

    #: src/name.c:42
    msgid "I don't know your name...\n"
    msgstr "I don't know your n@me...\n"

Last update: Thu Oct 26 09:49:36 2006

Valid XHTML 1.0.