Translation file format (.po)
Translations are stored in ".po" files (Portable Object), named with a language code
specific to each language and country. So for example the translations for the Spanish spoken in
Spain would be found in es_ES.po and for Spanish spoken in Mexico would be found in es_MX.po.
It is a plain-text filetype, so you can edit it however you choose, but translators often prefer to use purpose-built translation editors (such as Poedit), or web-based translation tools (such as https://translations.launchpad.net).
The format of ".po" files is a list of entries, with the english phrase to be translated, followed
by the local translation. The english phrase is on the line or lines beginning with msgid, and the
translated phrase goes on the line or lines beginning with msgstr.
Before the msgid line there will be a comment line indicating where in the source code the word or
phrase came from. This can often help when the meaning of the english is not obvious. There may also
be comments left by the developers to make translation easier.
Most entries will look something like this:
#: action.cpp:421
msgid "Construct Terrain"
msgstr "niarreT tcurtsnoC"The english phrase here is “Construct Terrain”, and it comes from line 421 of the file “action.cpp”. The example translation is just a reversal of the english letters. With this, in stead of “Construct Terrain”, the game will display “niarreT tcurtsnoC”.
Another exmple is:
#: action.cpp:425 defense.cpp:635 defense.cpp:701 npcmove.cpp:2049
msgid "Sleep"
msgstr "pleeS"This is similar to the last example, except it is a more common phrase. It is used in the files action.cpp, defense.cpp (twice) and npcmove.cpp. The translation will replace every usage.
File Header
The header at the top of the ".po" file is the only part that differs from the
comment/msgid/msgstr format.
If you are working on an already established translation you will not have to modify it.
For a new translation, it should be mostly set up for you, either by the editor you are using or by
the msginit program which is the recommended way of initializing a translation (see
TRANSLATING.md).
If you are starting from another translation file however, you might need to change a few things. Just fill it in as best you are able.
The header will look something like:
# French translations for Cataclysm-DDA package.
# Copyright (C) 2013 CleverRaven and Cataclysm-DDA contributors.
# This file is distributed under the same license as the Cataclysm-DDA package.
# Administrator <EMAIL@ADDRESS>, 2013.
#
msgid ""
msgstr ""
"Project-Id-Version: 0.7-git\n"
"Report-Msgid-Bugs-To: http://github.com/CleverRaven/Cataclysm-DDA\n"
"POT-Creation-Date: 2013-08-01 13:44+0800\n"
"PO-Revision-Date: 2013-08-01 14:02+0800\n"
"Last-Translator: YOUR NAME <[email protected]>\n"
"Language-Team: French\n"
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"If you are starting a new translation, or you are in charge of the existing translation, it is helpful if you include your name and e-mail address so that you can be contacted with any questions or issues regarding the translation.
The only important part that cannot be easily filled out manually is the Plural-Forms section. It
determines how different numbers of things are handled in your language. More on that later.
Format strings and newlines
Some strings will have special terms such as %s, %2$d and \n.
\n represents a linebreak. Mostly these are unnecessary as the code wraps lines where it can, but
sometimes these are used for placing things on different lines. Just use \n in your translation
wherever a new line should go.
%s and other similar terms are replaced with something else when the game is running. You might
need to move them around, depending on the translation. It is important that every term beginning
with % is kept in the translation.
Here is an example which replaces a %d with a number:
#: addiction.cpp:224
#, c-format
msgid ""
"Strength - %d; Perception - 1; Dexterity - 1;\n"
"Depression and physical pain to some degree. Frequent cravings. Vomiting."
msgstr ""
";1 - ytiretxeD ;1 - noitpecreP ;%d - htgnertS\n"
".gnitimoV .sgnivarc tneuqerF .eerged emos ot niap lacisyhp dna noisserpeD"Here it is important that the %d was not reversed, and that the \n remained at the end of the
line. In this case, %d will be replaced with the character’s strength modifier when the message is
displayed.
In some cases it might be necessary to change the order of terms. This can confuse the game. If the
order of the % terms changes, you must add numbers to all of them, so that the game knows which
was which. Some strings will already have these numbers, but some might not.
As an example, if there is a string with %s shoots %s!, it might change in translation. Perhaps it
will become something like %s is shot by %s!. But now it is the wrong way around, the shooter has
swapped with the shootee.
In this case, each %s should be numbered with a digit (1-9) then a dollar sign ($) between the %
and the s. For example %1$s shoots %2$s! would be equivalent to %s shoots %s!. So the example
translation above could be %2$s is shot by %1$s!, and this would work correctly.
The game can figure out these %1$s %2$s parameters automatically, but you must make sure that
(A): all of the % terms in the translation are numbered; and (B): the numbers are correct in terms
of the original ordering in the english text.
For example:
#: map.cpp:680
#, c-format
msgid "%s loses control of the %s."
msgstr "%2$s eht fo lortnoc sesol %1$s"would be displayed in-game as kcurt eht fo lortnoc sesol liagibA, assuming Abigail was driving a
truck.
Special tags in strings
Some strings in the translation may have special tags in front of or inside them. These tags should be left as-is, and only the rest of the string translated.
For example, the NPC and city names from “data/raw/names.json” are prefixed with <name> so as to
avoid conflicts with words (such as Wood the material, and Wood the last name). For these, the
<name> part should be left in.
For example:
#. ~ proper name; gender=female; usage=given
#: lang/json/json_names.py:6
msgid "<name>Abigail"
msgstr "<name>liagibA"Names also have a comment above them, indicating what the name is used for in-game. In this case,
Abigail is a possible first name for a female NPC.
Plural forms
Many languages use different terms for things depending on how many of them there are. These are
supported using plural forms, defined by the Plural-Form line in the ".po" file header.
For these, there will be multiple msgstr lines, intended for the different forms depending on
number. The game will automatically choose the correct form depending on the number of things.
For example:
#: melee.cpp:913
#, c-format
msgid "%d enemy hit!"
msgid_plural "%d enemies hit!"
msgstr[0] "!tih ymene %d"
msgstr[1] "!tih seimene %d"Here the first entry is for when there is only one enemy, the second is for when there are more
than one enemies. The rules differ wildly between languages.