#summary This is a guide for new translators.

= Translations =
== Introduction ==

This is a guide for translators. In order to translate Hedgewars into another language you are going to need:

 # The latest Hedgewars localization files
 # A text editor like Notepad++, Geany, Vim, etc.
 # Qt Linguist. To download Qt Linguist, you have to download the Qt SDK.

== Getting the localization files ==

To get the Hedgewars localization files there are 4 possible ways.

 * *A*. Clone the Hedgewars source repository.
 * *B*. Download the latest Hedgewars source code.
 * *C*. Find the localization files in your current Hedgewars installation.
 * *D*. Download only the specific files to be translated.

The *A* is maybe the most convenient way to include the translations in the next Hedgewars release as you can easily produce a patch to provide it to the Hedgewars developers. Note that a fast internet connection is desired as you probably will clone the whole game sources. The other advantage of this way is that it can be used to translate the latest game version that is going to be released.

The *B* way is a lot like the *A* way but more limited.

The *C* is probably the fastest way and the more convenient for the translator.
However, it has the limitation that one can only translate the most recent Hedgewars release (the one currently installed) and not the version that is going to be released.

The *D* way is to download the desired files from [https://hg.hedgewars.org/hedgewars/file/default/share/hedgewars/Data/Locale/ here].

Above I am going to discuss the *C* way (Find the localization files in your current Hedgewars installation).

=== Finding the localization files ===

In GNU/Linux you have to look into `/path-to-Hedgewars/Data/Locale where path-to-Hedgewars` is the path to your Hedgewars installation.

In Windows you have to look into `c:\path-to-Hedgewars\share\Hedgewars\Data\Locale` where path-to-Hedgewars is the path to your Hedgewars installation.

For example, in an Arch Linux box the path is `/usr/share/hedgewars/Data/Locale`.
For Windows 8, the path is `C:\Program Files (x86)\Hedgewars 0.9.19\Data\Locale`.

== Language codes ==
Languages are identified with the [https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO 639-1 language code] (e.g. “de” for German). For regional language variants, an [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code] can be appended with an underscore (e.g. “pt_BR” for Brazilian Portuguese).

== Translation files ==
Here is a list of the different localization files of the English language that you should use as your translation reference/template as it should be the most accurate and up to date. The file locations are relative to the top directory of the Hedgewars source code. You can edit all these files with a text editor, but for some files special editors are available.

=== Overview ===
These are all files which contain translatable text for Hedgewars. Replace “ZZ” with the actual language code.
 * `/share/hedgewars/Data/Locale/ZZ.txt`—In-game strings
 * `/share/hedgewars/Data/Locale/ZZ.lua`—Scripted stuff (missions and game styles)
 * `/share/hedgewars/Data/Locale/hedgewars_ZZ.ts`—Frontend
 * `/share/hedgewars/Data/Locale/missions_ZZ.txt`—Mission names and descriptions
 * `/share/hedgewars/Data/Locale/campaigns_ZZ.txt`—Campaign names and descriptions
 * `/share/hedgewars/Data/Locale/tips_ZZ.xml`—Main menu tips
 * `/share/hedgewars/Data/Maps/<map name>/desc.txt`—Mission map descriptions

These files are not part of Hedgewars itself, but are used by other programs and websites to present Hedgewars:

 * `/share/hedgewars/Data/misc/hedgewars.desktop`—[https://wiki.freedesktop.org/www/Specifications/desktop-entry-spec/ Desktop Entry] file for Hedgewars
 * `/share/hedgewars/Data/misc/hwengine.desktop`—*Do not translate!*
 * `/share/hedgewars/Data/misc/hwengine.desktop.in`—Desktop Entry file for the engine
 * `/share/hedgewars/Data/misc/hedgewars-mimeinfo.xml`—File type descriptions
 * `/share/hedgewars.appdata.xml`—[https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html AppData] description

=== Engine (in-game stuff) ===
 * `/share/hedgewars/Data/Locale/ZZ.txt`—This contains the core in-game strings, such as the mission panel, the messages at the top, ammo names and descriptions (see below)
 * `/share/hedgewars/Data/Locale/ZZ.lua`—Strings used by Lua scripts, which includes campaigns, missions and game styles (see below)

==== `.txt` files ====
A `.txt` file is organized in lines and string identifiers. Each string is identified with two numbers like `01:05`. The first number is called the “group”.

Each line must contain a single translation and follows this format:

`XX:YY=Translation`

For example:

`00:00=Grenade`

See `en.txt` for the English original texts. Note that some of the numbers may be missing in your file, so you need to add them on your own.

The group `02` is special because texts can be repeated here. These texts are used for event messages like the death of a hedgehog (`02:00`). Hedgewars will randomly use any of these messages in the same group. Each language can have its own set of messages for this. Translations can be rather flexible here.
In `02`, you don't need to translate every English message, but try to do your best. It is OK to omit messages if a direct translation wouldn't make sense (e.g. for weird English idioms). You can also invent your messages which are more appropriate for your language. If you're in a hurry, you can just add single a single message for each of the `02` groups (`02:00`, `02:01`, `02:02`, etc.), but don't forget to finish it later.

In the `04` and `05` groups, you can use a couple of special characters:

 * `|`: Line break
 * `:`: Highlight itself and all text before that character in this line. The colon itself will be written.
 * `::`: Like above, except the two colons will not be written.
 * `\:`: Will be replaced with “:” without triggering highlighting (escape sequence)
 * `\|`: Will be replaced with “|” without triggering a line break (escape sequence)

Don't forget to test these texts in-game to make sure everything looks fine.

==== `.lua` files ====
In a `.lua` file you will find many lines like this:

`--        ["Rubber Band"] = "", -- Construction_Mode`

Those need to be translated. The part in square brackets is the English original text.
The part in the quotation marks after the equals sign is supposed to contain the translation.
The initial two dashes and spaces are used for strings which hav not been translated yet. You need to remove them after you've completed the translation.

The two dashes at the end don't need translation, it's just the beginning of a comment for you to show you the source of the English text. In this case, it comes from the Construction Mode script.

Example for a translated line (in Italian):

`["Rounds Complete"] = "Round Completati",`

In case you need to include a quotation mark in your translation, write `\"` instead of `"`.

Note to programmers: These `.lua` files are actually containing real Lua source code.

=== Frontend (main menu) ===
 * `/share/hedgewars/Data/Locale/hedgewars_ZZ.ts`—Contains most strings of the frontend and you can edit it with Qt Linguist
 * `/share/hedgewars/Data/Locale/missions_ZZ.txt`—This is the [Missions mission] description strings
 * `/share/hedgewars/Data/Locale/campaigns_ZZ.txt`—This is the campaign description strings
 * `/share/hedgewars/Data/Locale/tips_ZZ.xml`—This contains the tips shown in the main menu. This file is *not* in XML format.

==== Mission map descriptions ====
The map selection shows brief descriptions for mission maps below the preview image. Those can be translated and you find those texts in:

 * `/share/hedgewars/Data/Maps/<map name>/desc.txt`

Replace “`<map name>`” with the name of any mission map. You see a list of mission maps if you select the map type “mission map” when preparing a game.

To translate these, add a line of the format `language code=description` (e.g. “en=This is an example.” for English). You must use the following special character sequences for new lines, commas and underscores:

|| *Written text* || *Is replaced by* ||
|| `_n` || New line ||
|| `_c` || Comma ||
|| `__` || Underscore ||

=== Metadata ===
The following files are not used by Hedgewars itself, but they contain translatable metadata about Hedgewars:

 * `/share/hedgewars/Data/misc/hedgewars.desktop`—[https://wiki.freedesktop.org/www/Specifications/desktop-entry-spec/ Desktop Entry] file for the Hedgewars application
 * `/share/hedgewars/Data/misc/hwengine.desktop.in`—Desktop Entry file for the Hedgewars engine for playing savegames and demos
 * `/share/hedgewars/Data/misc/hwengine.desktop`—*Do not translate*! This file will be automatically generated from `hwengine.desktop.in` when building Hedgewars
 * `/share/hedgewars/Data/misc/hedgewars-mimeinfo.xml`—Description of Hedgewars file types
 * `/share/hedgewars.appdata.xml`—[https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html AppData] description (for the desciption in software distribution services)

== Updating an existing translation ==

That is relatively easy. Just edit the existing file. You can edit every file with your favorite editor and the `.ts` file with Qt Linguist.

The `en.lua` file doesn’t exist. The strings are hard coded in the code.

== Creating a new translation ==

That is easy, too. Make a copy of the English file and rename it to use the language code. For the files in the `misc` directory, you need to add an additional line for your language (if it is missing).

The `en.lua` file doesn’t exist. Use `stub.lua` instead as your template.

Example for French:

 * Copy `en.txt` to `fr.txt`
 * Copy `stub.lua` to `fr.lua`
 * Copy `tips_en.xml` to `tips_fr.xml`

== Testing the translations ==

When finished, you have just to start Hedgewars and choose your language from the Game Preferences, Advanced tab.

If a translation is missing, then the string is going to be displayed in English.
Note that you should restart the frondend for the language changes to take effect.

== Sharing the translations ==

In order to share your translations with Hedgewars community there are 3 possible ways:

 # Talk with a Hedgewars developer in order to include it in the next Hedgewars release. This is the best possible solution
 # Talk with a Hedgewars developer in order to include it in [https://hedgewars.org/content.html DLC]
 # Give them the files and tell them where to place them. Of course this is the less convenient way but it is maybe a good approach to let other players double-check your translations

== Abbreviations ==
You will find a few abbreviations in the files. here's what they mean:

=== A Space Adventure ===
 * *PAotH*: Planetary Association of the Hedgehogs
 * *Hog Solo and GB*: Hog Solo and Green Bananas
 * *RS1*: Red Strawberries 1
 * *RS2*: Red Strawberries 2

=== General ===
 * *AFK*: Away From Keyboard
 * *fps*: frames per second
 * *s*: second ([https://en.wikipedia.org/wiki/International_System_of_Units SI unit] of time)
 * *min*: minute

== Things to have in mind ==

If you are going to make a translation for a next Hedgewars release strings may not be frozen yet and change before the release. Better ask in [https://hedgewars.org/chat our chatroom] in cases like that.

Feel free to translate hedgehog and team names into your own language, when it makes sense. Remember that most names are meant to be funny and puns are not uncommon. The game should be enjoyable in all languages.