Translation of VCMI mods

Translation of mods via Weblate

Translation for some mods is being migrated to our self-hosted Weblate.

If mod that you wish to translate is already there and it already has your language, then all you need to do is register and start translating. Changes made via Weblate will be automatically added to corresponding mod in 24 hours or less.

If you wish to add a new mod on our Weblate, please contact VCMI Team for initial setup via Discord or Github.

Initial setup

Before starting, go through this checklist to ensure that mod is ready for Weblate:

mod must be hosted by vcmi-mods Github organization
mod must contain mod.json in top-level directory, and not in a subdirectory
mod must use centralized workflow from https://github.com/vcmi-mods/workflow
make sure that workflow has generated content/translation/english.json with exported English strings of your mod repo
add empty .json for every language to which you wish to translate. See below for details

Once everything is ready, please contact VCMI Team via Discord or Github to finish the process

Addition of new languages

This operation can be done by anyone with write access to mod repository. You can also create new pull request and ask for someone with write access to accept it.

If translation to a new language needs to be added to Weblate, please add empty dummy files for required language to mod repository on Github. This should automatically generate translation on Weblate once changes are merged. You can do this:

Manually, by creating empty .json file with {} as content next to every english.json in your mod (usually - only in main mod, but in some cases submods may also need separate translation)
By running python script locally: python3 .github/add_translations.py --root . --lang <language> (script available in any mod that uses VCMI mod workflow)
By running "Add new language to translation" workflow in mod repository with desired language (requires admin permissions)

For language tag format always use full name of language in English, in lower case. Examples: english, polish, chinese

Note that while Weblate supports basically any language, VCMI only supports limited set of languages listed in Translations.md

Addition of new submods

If you have added new submod that needs translating to mod you are working on, add required files (english.json generated by translation export and any required dummy translations) to mod repository on Github. Please use the same list of translations as for the rest of the mod.

Once new files are up, please contact VCMI Team via Discord or Github to finish the process and add new component for the submod on Weblate

WARNING: Do not edit or move translation files other than through Weblate. If you have to, for example due to submod reorganization, please contact VCMI Team.

Translating mods manually

Exporting translation

If you want to start new translation for a mod or to update existing one you may need to export it first. To do that:

Optionally, backup your mod preset - game may modify active submods of mod being translated
Set game language in VCMI Launcher to one that you want to target
launch VCMI server in translation export mode:
(Windows) Create shortcut for VCMI_Server.exe and append --translate-mod=XXX to "Target" field in shortcut properties, where XXX is identifier of mod that you want to translate
(Other platforms) Open command line and run vcmiserver --translate-mod=XXX, where XXX is identifier of mod that you want to translate

After that, start VCMI Launcher, switch to Help tab and open "log files directory". You can find exported json's in extracted/translation directory.

Exporting translation (alternative)

Alternatively, you can use vcmi client to do similar actions:

Enable mod(s) that you want to export and set game language in Launcher to one that you want to target
Launch VCMI and load any map to get in game
Press Tab to activate chat and enter '/translate'

After that, start VCMI Launcher, switch to Help tab and open "log files directory". You can find exported json's in extracted/translation directory.

If your mod also contains maps or campaigns that you want to translate, then use /translate maps command instead.

If you want to update existing translation, you can use /translate missing command that will export only strings that were not translated

NOTE: when translating with this method, some strings may not export correctly, for example strings that were modified in multiple mods. To avoid this, you'll need to disable mods that override other strings and do a second re-run of this command

Translating mod information

In order to display information in VCMI Launcher in language selected by user add following block into your mod.json:

    "<language>" : {
        "name" : "<translated name>",
        "description" : "<translated description>",
        "author" : "<translated author>",
        "translations" : [
            "translation/<language>.json" // NOTE: path is relative to content directory
        ]
    },

However, normally you don't need to use block for English. Instead, English text should remain in root section of your mod.json file, to be used when game can not find translated version.

Translating in-game strings

After you have exported translation and added mod information for your language, copy exported file to <mod directory>/content/translation/<language>.json.

Use any text editor (Notepad++ is recommended for Windows) and translate all strings from this file to your language