# Translations

## Translation file locations

The main engine translation file is at:

    /mods/default/languages/engine.pot

This is the simplest and most important file to translate. It contains the common engine and interface text. Having this text translated at least makes the interface usable for readers of that language.

The data translation files are at:

    /mods/[modname]/languages/data.pot

Once the basic engine text is translated, these data files are the next files to translate. Note that not all mods have a translation file (example: mods that only update graphics).

In these language folders you'll see translations of these pot files. Each language has its own .po file. Example:

    /mods/default/languages/engine.it.po
    /mods/fantasycore/languages/data.ru.po

The filenames for these language translations use the ISO standard 2-letter language codes (639-1). If the language only has a 639-2 code, that is permitted instead.

## Editing an existing po file

Before editing an existing translation, check with the original translators to make sure they're not already working on this. Example, here we list the previous translators for Flare-game: https://github.com/clintbellanger/flare-game/wiki/Credits#translations

We use a very small subset of the gettext convention for Flare translations. Most .po file editing apps should work. In a pinch, a plain-text editor should work (but be sure to test in-game, as syntax errors are more possible).

Translation entries have two lines. The msgid is the original text and the msgstr is your translation. Example from engine.it.po:

    #: ../../../src/Avatar.cpp:633
    msgid "You are defeated. Game over! Press Enter to exit to Title."
    msgstr "La Morte ti ha raggiunto. Game over! Premere Invio per tornare al Titolo."

Any line that starts with # is a comment. Often these comments refer to the source file of the text. You might want to look at the source file if you're having trouble figuring out the context of this message.

The lines that begin with msgid and msgstr always start with those keywords, followed by one blank space, followed by the entire message in double-quotes (").

Sometimes the msgid contains a % sign followed by a letter, like this:

    #: ../../../src/Avatar.cpp:444
    msgid "Congratulations, you have reached level %d!"
    msgstr "Felicitaciones, has alcanzado el nivel %d!"

This means some value (usually a number) is inserted into the text at that position. Your translation should include the same % sign followed by the same letter.

Translating is as simple as editing the text inside the quotes of the msgstr line. Do not modify the msgid lines. The only other thing your edited .po file should include is updated header information e.g. the revision date and last translator.

## Creating a new .po file

Copy the engine.pot (or data.pot) file and rename it to engine.xx.po, where xx is the new language's code. Then edit your new .po file. First fill in the header information, then fill in the msgstr values.

If you get confused on any one point, look at other .po files in the same folder for examples.

## Enabling a new language in the engine

If you're creating a new language file, you'll especially want to test it by playing the game with your language enabled. Edit this file and add your new language entry:

    mods/default/engine/languages.txt

And save the file. When running the game use the Configuration menu, Interface tab to select your new language.

## Submitting your new .po files

If you're already familiar with GitHub you could fork the engine or game and send your update as a Pull Request.

Otherwise it's fine to email your new .po file(s) to the engine maintainer (Clint Bellanger) or the specific game maintainers.

Please include your name or preferred nickname to be included in the credits.

Note that we're only accepting human-translated text. Please don't submit a translation that was simply run through machine translation.

## Tools

Here is a list of .po file editing tools, if you don't want to use a plain text editor.

- Poedit - simple cross-platform editor of gettext catalogs.
- Virtaal - easy translation tool that supports many localization formats.
- GTranslator - powerful translation tool integrated with GNOME desktop.
- Lokalize - editor of gettext catalogs integrated with KDE desktop.