Urban Giraffe

Step 1: Producing a POT file

The first step involved in translating a plugin or theme is to produce a POT file, which is a list of all localizable text. Sometimes this file will be provided by the theme or plugin author, but if not it can be automatically generated using gettext or poEdit.

Before you begin you will need access to the theme or plugin you want to translate. You may find it easier to have WordPress installed on your own machine, but it is not essential. You should download and unzip the theme or plugin from the author's site and store it in a known location:

poEdit

From the File menu select New Catalog. A window will appear asking for catalog settings. Fill this out as follows, changing the details as appropriate to your chosen theme or plugin and target language:

The character set (charset) encoding tells poEdit how characters in your file are stored. Character sets contain special characters that some languages need (such as letters with accents - é). Where possible you should use UTF-8 as your character set as this is the default encoding used by WordPress and supports almost every character you could need. If you do require another encoding then make sure this is clearly marked in the final output file (more details about this later).

The plural forms is a complicated setting and requires a section of its own. For the moment you can leave this empty and if you discover at a later date that you do require support for plurals then you can change the catalog options and update the value.

When you've entered the catalog settings you should select the Paths tab and enter the full path to the location of your theme or plugin. Specify it both in the base and as an additional path:

Finally select the keywords tab and enter the following keywords to tell poEdit what is used to mark localizable text:

Note that the interface is very 'fiddly', and you need to select an empty row and then click the small square box to edit text (as highlighted). The list of keywords matches the functions provided by WordPress and, in the case of ngettext, configures poEdit for correct pluralization.

Finally you should press OK whereupon you will be prompted to save the catalog file. Note that poEdit will save the file as a .PO, not a .POT. The file extension has no bearing at this point, so just chose a location and name for the file (remembering the naming conventions).

When you save your catalog file, poEdit will automatically scan through the theme or plugin and generate a list of all localizable text:

Press OK to accept this list and accept any messages that appear. Note that if the plugin or theme is updated you can use poEdit to refresh this list and it will tell you what text has changed, and what text has been deleted. This is a very useful feature to stop you having to re-translate text.

That's it! You should now have a .POT file stored wherever you told poEdit to save the catalog. This file will contain a list of all localizable text, and poEdit will display this in its main window ready for you to move on to step 2.

GNU gettext

Using gettext to produce a POT file is similar to poEdit but without all the niceties of a graphical interface. From a terminal, change to the theme directory and enter the following commands:

find . -iname "*.php" >files.tmp
 
xgettext --language=PHP --indent --keyword=__ --keyword=_e \
--keyword=__ngettext:1,2 -s -n --from-code=UTF8 -f files.tmp
 
rm files.tmp

Note that the second line is displayed across two lines, but should be executed on one. An output POT file called messages.po will be produced:

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid   ""
msgstr  "Project-Id-Version: PACKAGE VERSIONn"
        "Report-Msgid-Bugs-To: n"
        "POT-Creation-Date: 2007-08-10 11:07+0800n"
        "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONEn"
        "Last-Translator: FULL NAME <EMAIL@ADDRESS>n"
        "Language-Team: LANGUAGE <LL@li.org>n"
        "MIME-Version: 1.0n"
        "Content-Type: text/plain; charset=CHARSETn"
        "Content-Transfer-Encoding: 8bitn"
 
#: view/admin/redirections.php:2
#, php-format
msgid   "%s Redirections"
msgstr  ""

The top of this file contains 'header' information describing the localization. You should update this section to reflect your target language, pluralization (see next section), and yourself.

Plural Forms

A plural form is a rule that determines how a language pluralizes a particular word. For example, in English if you wish to display how many messages a user has you would have the following forms:

You have 1 message
You have 2 messages

However, it cannot be assumed that to pluralize the word 'message' you simply add an 's', and a lot of languages either require no pluralization, or have other rules. To work around this problem the GNU gettext framework allows the programmer to leave the pluralization up to the translator by marking such words using the __ngettext function. How they do this is not important here (and is discussed in Preparing A Theme Or Plugin for Localization), but if plural forms do exist in the plugin or theme you are translating then you need to tell poEdit or gettext about the rules of your target language.

GNU gettext makes use of a special plural command syntax to describe pluralization rules. Exact details of this syntax is beyond the scope of this document and can be found on the GNU gettext documentation site. However, to aid translators a list of the most popular rules is given below (as described on the GNU site):

Language	Plural form
Hungarian, Japanese, Korean, Turkish	nplurals=1; plural=0;
Chinese	nplurals=2; plural=1;
Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish, Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto	nplurals=2; plural=n != 1;
French, Brazilian Portuguese	nplurals=2; plural=n>1;
Latvian	nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
Gaelic	nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
Lithuanian	nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
Croatian, Czech, Russian, Ukranian	nplurals=3; plural=n%100/10==1 ? 2 : n%10==1 ? 0 : (n+9)%10>3 ? 2 : 1;
Slovak	nplurals=3; plural=(n==1) ? 1 : (n>=2 && n<=4) ? 2 : 0;
Polish	nplurals=3; plural=n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
Slovenian	nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;

poEdit

The plural forms value is set from the catalog settings page:

GNU gettext

Put the plural form value in the header section of the PO file:

"Plural-Forms: nplurals=2; plural=n != 1;\n"

Share This