In KeeperFX, each campaign has a .dat file for each supported language. This contains the in-game messages, which are in three variants:
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.
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.
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.
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.
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.
These instructions assume that:
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.
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’.
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.
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.
A: Your language may be not yet supported by KeeperFX. Create an issue in "Issue tracker" describing the situation.
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.
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.
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.
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.
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(), QUICK_OBJECTIVE(), and QUICK_MESSAGE() 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.
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.
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.
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.
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:
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. The Dungeon Keeper String Editor can also be used to convert a single .po or .pot file to .dat format; simply open it and save it as a .dat file.
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.
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 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:
Dungeon Keeper String Editor can edit .dat files directly, meaning there's no need for conversion from .po or .pot. This is useful for testing changes before "finalising" them by putting them into a .po or .pot file to be included in KeeperFX, and for making level-specific .dat files (see below). It can convert .dat files to .pot translation templates, and convert .po and .pot files to dat.
KeeperFX 1.1.0 and later support level-specific translations and custom strings. To use this feature, the strings need to be in .dat files for thet specific level, e.g. map00xxx.lan.dat, where 'lan' is the language code (e.g. 'eng' for English, 'jpn' for Japanese, etc). Use Dungeon Keeper String Editor to create and edit these files (use slots 1-200, for aforementioned reasons), but make sure the code page is set correctly before saving, or the results may be gibberish. Use the DISPLAY_*() commands with the corresponding string IDs in the .dat files in the level's script. Note, however, that this cannot be used to translate the name of the level, only the text used in it, as these files are loaded with the level. If KeeperFX is set to a language a level has not been translated into, the level's strings for the map pack/campaign's default language (usually English) will be used.