KeeperFX Wiki

Introduction

In KeeperFX, each campaign has a .dat file for each supported language. This contains the in-game messages, which are in 2 variants:

  • Objective. Appears at the bottom of the screen in-game. There is one at the start of the game, and the final one is usually something like "Success! This Land is Yours. Press Space to proceed to the next realm.". There are often more posted during the game, each replacing the previous one.
  • Information. Is a text message in a box, very similar to Objective. When triggered, Information is visible via flashing 'i'. You may have several Information messages visible at once - they will not replace each other, but will stack. Each Information has a limited lifespan after it's been read, and will disappear after some time. Both these message types are sent via the level script file (map00xxx.txt), specific to each map. The script calls a message from that language's .dat file (e.g. text_eng.dat). In KeeperFX .dat files are generated via
  • .pot files which are template English language files
  • .po files which are translations of that campaign's .pot file KeeperFX uses the .pot and .po files to generate the language specific text_xxx.dat files for each campaign. As well as in-game messages, the .dat file also contains all the other information needed by the game for a specific language. The game produces tooltip messages whenever you point at an object, room, thing, creature etc in the game, and these also come from the .dat file. Hence it is wise to use a pre-existing file, usually from the original campaign, and modify that to generate new content.

Table of Contents

Notification

For all these types of changes, it is advisable (but not compulsory) to give notice that you intend to make a change / changes. Go to the KeeperFX Issues page and click ‘New Issue’. Enter the relevant details in the form where you can. Make it clear that you intend to do this work, and are notifying the community of your intent. It is a good idea to do this to prevent duplication of effort (i.e. someone else might do the same work!). Another advantage is that if you embark on a translation, but you can’t complete it, you can upload your latest progress into this site, and someone else can download your latest work and complete it.

Correcting A Translation

You may have played a campaign, and noticed an error, or a poor translation, and want to fix it. You can do this quite easily. You will need POedit (open-source translation tool) to do this.

Getting the files and tools you need

Go to the Language folder in KeeperFX source code tree and you will see a list of the language files for the original campaign and the various KeeperFX campaigns. Select the campaign, and find and click to show the .po file for the language you wish to correct. Then right-click on ‘save target as’, and download the file ‘text_xxx.po’ (where xxx is the language you wish to translate into). Also download the English template file, which is usually text_eng.pot Download POedit from its official site.

Updating translation

Start the POEdit software and choose 'edit a translation', and when prompted open the 'text_xxx.po' file for the language you wish to amend. You are now able to make changes, but before correcting any translations, go to: Catalogue -> update from pot file And when prompted, choose the text_eng.pot file. When complete, this will highlight all pre-existing changes needed for the translation file, as it may have been changed since the first translation.

Testing the results

After you've made a few corrections, you may want to check how the changes look inside the game. This is not trivial, as KeeperFX needs translation to be converted to .dat format before use in the game. If you'll send the translation to developers, you will soon be able to see the results in new Nightly Builds. But if you'd like to integrate the changes to the game by yourself, you need to convert the file to .dat format.

I want to add a translation for a campaign

These instructions assume that:

  • an English version of the campaign file is available
  • the target language is already a supported KeeperFX language (there are official campaign translations) You will need POedit (open-source translation tool) to do this.
Getting the files and tools you need

Go to the Language folder in KeeperFX source code tree and you will see a list of the language files for the original campaign. Click on the file of the language you wish to use - ‘gtext_xxx.po’ (where xxx is the language you wish to translate into). If there's no .po file for your language, then you'll have to create it from .pot file - click ‘gtext_eng.pot’. After the file is clicked, right-click on the ‘Raw’ button and download the file. Similarly, download the .pot file for the campaign you wish to translate. If it is an official campaign within KeeperFX, go to the Language folder in KeeperFX source again, and enter the folder of the campaign to download the right file. If it is a campaign which isn't shipped with KeeperFX, then you’ll need to have the English template (.pot file) from the author(s). Download POedit from its official site.

Preparing initial translation

Open the ‘gtext_xxx.po’ file in POEdit. From within the program choose: Catalogue -> update from pot file and select the .pot file you've downloaded. Accept the changes listed by POEdit. POEdit will now have highlighted all the campaign specific messages that need the new language scripts. You are now ready to start translating. Save the new .po file giving it different name, for example ‘ancntkpr_rus.po’.

Translating

Translate the highlighted messages into the new language, either all at once, or some at a time. When the file is completed, you have to send it to KeeperFX developers. You may either create an enhancement proposal in theKeeperFX tracker, or contact a developer on discord for inclusion in the campaign.

Testing the results

If you'll send the translation to developers, you will soon be able to see the results in new Nightly Builds. But if you'd like to integrate the changes to the game by yourself, you need to convert the file to .dat format.

Problems
Q: I can't find the .po file for my language.

A: Your language may be not yet supported by KeeperFX. Create an issue in "Issue tracker" describing the situation.

Q: I can't find the .pot file for the campaign I want to translate.*

A: Some campaigns do not have translations, because they don't have any in-game messages. If you're not sure, you can always raise an issue asking for help.

Adding new language

KeeperFX supports many languages - all of them are mentioned in README file. If the language you want to add is within that list, then it is supported - you should look at how to add a translation for a campaign . If the language isn't supported, it requires some programming to add the support. Go to the KeeperFX Issues page to create a ‘New Issue’. On the ‘Enhancement Proposal’ enter all the relevant details you can. Ask if someone is willing to add the new language. If there are national characters in that language, or it has other rules which seem relevant, state them in the description. Sooner or later, a programmer will read your issue and answer it. In the meantime, you may start translating the game, you just won't be able to test your changes until the support is added. See the section 'Add a translation for a campaign' for details. If you think some national characters won't be available in KeeperFX, you should still use them inside your translation - if the char will be missing, automated tools will replace characters with closest English equivalent. This way, when the character will be added to KeeperFX bitmap fonts, the translation won't need any fixing.

Modifying English language template

While .po file have a great tool to create, update and edit them, the .pot files do not have such editor. The best way is to open them in your favorite text editor and make changes there. Remember to use simple text editor, which will not support text formatting, and will not break syntax of the .pot file. Notepad or wxMEdit are both good choices; don't use Ms Word.

Testing the results

After you've made a few corrections, you may want to check how the changes look inside the game. This is not trivial, as KeeperFX needs translation to be converted to .dat format before use in the game. If you'll send the translation to developers, you will soon be able to see the results in new Nightly Builds. But if you'd like to integrate the changes to the game by yourself, you need to convert the file to .dat format.

Making a Translation template for a new campaign

While making levels, you do not necessarily want to start with all messages in .pot files. It is much more convenient to keep all the messages inside your level script file. Later, when your campaign is almost ready, you can easily export all strings to .pot file, in a partially automated way. So, it is best to use QUICK_INFORMATION() and QUICK_OBJECTIVE() for displaying messages while creating levels. Just remember to use QUICK_*() commands for all the messages - don't mix them with DISPLAY_*(), as that would make automating .pot file generation much harder.

Creating new translation template

To make a new translation template, it is best to start with an existing .pot file from another campaign, like the one from Burdened Imp campaign. Open the file in any text editor (ie. Notepad under Ms Windows) and replace strings with the ones from QUICK_*() commands in your script. Keep string 0 (marked guitext:0) intact - it's a message shown after winning a level. Use strings 1..200 for your objectives and infos, then strings 202..225 for your level names - that would keep the convention used in other levels. Group unused message numbers under the "Moo" string - there shouldn't be missing string other that guitext:201 (and leave this one missing - it is by purpose an empty string). Note that this part of work can be automated - see the next chapter for details. After the .pot file is ready, comment out all the QUICK_*() commands in your scripts and insert DISPLAY_*() commands below, using the same message numbers you've assigned to each string in .pot file with guitext:. To convert .pot file to .dat, follow conversion instructions.

Automating extraction of strings to translate

There is a script in KeeperFX code repository which allows fast generation of .pot file based on QUICK_INFORMATION() and QUICK_OBJECTIVE() commands within levels. After your levels are ready, run this script under Unix shell (ie. any Linux distribution, or on Windows with MinGW installed). This will create a .pot file automatically. You will still have to do a few modifications to it - it will contain only strings from your levels, so will lack some of the strings for spells, rooms, creatures etc. You may copy and paste that missing part at end of file from any other campaign .pot file. If you don't know how to use that script, ask a programmer to do so - ie. by creating a request in KeeperFX issue tracker, and attaching an archive with all your levels to it. After .pot file is ready, you still have to replace QUICK_*() commands with DISPLAY_*() in all your scripts - that part is not automated.

Testing the results

After you've made a few strings, you may want to check how the changes look inside the game. This is not trivial, as KeeperFX needs translation to be converted to .dat format before use in the game. If the translation is to be added to official KeeperFX builds, then send it to developers, and you will soon be able to see the results in new Nightly Builds. But if you'd like to integrate the changes to the game by yourself, you need to convert the file to .dat format.

Converting .po or .pot file into .dat format

KeeperFX cannot read .po or .pot files directly. These formats are used to help with translations, but then have to be converted into a format which the game engine supports, which is .dat. You don't really have to deal with that - if you will send the new .po or .pot to be included in new KeeperFX builds, it will be converted automatically and included in the next nighty build. To send the file to KeeperFX developers, you may either create an enhancement proposal in KeeperFX tracker, or e-mail it to a developer (ie Mefistotelis) for inclusion in the campaign. Still, if you'd like to test your translation by yourself, here's how to do the conversion:

Conversion utility

To convert .po or .pot file to .dat, get KeeperFX tools (or compile them from KeeperFX source code), and use po2ngdat command line utility which can do the conversion.

Using the .dat file in the game

If you've made the .dat file which fixes existing one, just find it in the KeeperFX folders and replace with new version. If this is a new file, then you must enable it in a campaign .cfg file and place it into the same folder where other translations for this campaign are.

Useful software

POEdit

POEdit is used for generation of new .po files for new campaign translations, or for editing existing .po files. So use it when making translations. It is opensource software, get it from poedit.net. On first use go to File>preferences>editor and uncheck ‘automatically compile .mo file on save’ (these files are not needed).

wxMEdit

wxMEdit is opensource software for text file editing. Download it from wxmedit.github.io. This program is not required, alternative text editors may also be used. For KeeperFX, this program is used to:

  • edit .pot English template files. These are the 'master' English files containing the in-game messages & information. There is usually a distinct file for each campaign.
  • generate new .pot English language templates (for a new campaign). This is best done by modifying a copy of gtext_eng.pot, the original campaign file, as it contains all the generic messages, descriptors, tool-tips etc that are required by all campaigns.