Translation

Translation Toolbox

Translation Toolbox is submodule bundled with ToME Addon's Development Tools, contains a few utility tools for developers to translating ToME4.

Notes ahead

Translation Toolbox stores all your translation file in the user-i18n folder in your ToME4 home directory, which is also where your savefile stored. If you can't find it, you can follow Tome_faq#Where_are_my_save_files.3F.

While it is not mandatory, it is strongly recommended to use a Version Control System (e.g. git, mercurial, etc) to manage your translation workspace. You won't want to permanently lose your translation text because of software bug or misoperation.

For technique support and bug report, you can report in the #translation channel in the official ToME4 Discord server (https://discord.gg/tales-of-majeyal).

Functions

After you have installed translation toolbox, you can see Translation Tool in your debug menu. Choose it, and you will see thess functions:

• Change working locale: Change to any arbitary locale, even if not present in Language Selector.
• Create translation addon: Help you create an example translation addon to test your translation.
• Extract text index: #Extracting text from ToME4 contains further explaination.
• Rearrange translation files can be used to generate empty translation file, deduplicate and rearrange your translation files.#Rearrange translation files contains futher explaination. Check translation files only check and report conflicting translation entries across files, and won't write to any file
• Release translation as addon will copy translation file to the destination addon.

Extracting text from ToME4

To support translation for ToME4, the translation tool will first need to detect texts in ToME4. So, you must run this at least once, or the following option will not have any use. It will use luafish to parse all lua script in game source code. This operation will cost some minutes, and the game may freeze for a few times, but don't worry, the game isn't crashed.

Extracted text entries will be stored in extracted-text folder. Every game part will be stored in it corresponding file.

Engine will be engine.lua, module will be in mod-boot.lua or mod-tome.lua, and addons will be in tome-items-vault.lua or tome-orcs.lua

To reduce repeat rescanning, it will store the md5 checksum of game parts in md5s.cfg, skip non-changing game parts. If you encountered a problem about this, delete this file will force a full rerun.

After the first run, you will need to rerun it on game change to detect newly added strings. This function will compare with the old extracted detect the "newly added" ones and mark them as "new". In case of misoperation, old strings will be copied to backup folder. But only for once: they will disappear after you execute it again, so if you don't want to lose it, please do manual backup.

Rearrange translation files

Translation Tool use your current locale as your working language, And translation will be stored in corresponding folder in your workspace path. If you are on wrong locale, You should use Change working locale to switch the locale you are working on.

Your working directory will contain all your translation files, so be sure to backup it often.

After first run, the folder may contains those files:

• <part_name>.lua: Translation file for that game part, it can be automatically generated as you use Rearrange for the first time.
• <part_name>.copy.lua: If you want to add addtional content at the beginning of the translation file, please use this. This is very helpful when you want to setup things like Fonts or Translation Flags
• backup folder: Similiar to that in extracted text, it will backup your translation file, but only for once.
• _t_append.lua: This contains translation text that will be `imported` into the translation project, it can be used for migration from the old framework, or scatter files to translators, and use it to combine them back.
• _tdef_append.lua: This is a tricker one, contains translation raw texts that does not appear in game as _t entries, but should be translated.
  • For example, northwest is a combination of "north" and "west" in game, but it may appear as an independent word in your language.
  • Also, magestaff that does not appear as _t. It's the key for key-value staff flavor defination in game, and we may not want to change this for compatibility.
  • This is still subject to interface changes. Currently, you need to get a up-to-date _tdef_append.lua in https://pastebin.com/tJS5SCt6
• _not_merged.lua: For translation entries that is lost and cannot find its corresponding file, to avoid losing them. You can choose when to delete or preserve them, just do the backup when you do this.
• i18n.log: contains log.

Translations file will rearranged like this:

section "<file-name>"
{Valid translations}
-- untranslated text
{Texts that haven't been translated}
-- new text
{Newly add text add in newer version of the game (detected by the difference of successive extracting operations)}
-- old translated text
{Translation text that can't be found in current game}

Migration from old i18n_tools

The extract and rearrange function is just like the old i18n_extractor.lua and i18n_helper.lua interface.

You can use _t_append.lua to import your old merge_translation.lua or <locale-name>.lua translation file, but before that, you shall read the following note.

• Section name is changed. For example, "game/addons/tome-addon-dev/init.lua" is now "tome-addon-dev/init.lua", and "game/engines/default/data/keybinds/actions.lua" is "engine/data/keybinds/actions.lua". If you want to import, you may want to replace those filenames to avoid losing things.
• Some renames. For example, tome is renamed to mod-tome.
• untranslated.lua is not implemented yet, for I rarely use it. If you prefer using it, please let me know.
• For safety reason, ToME4 forbids arbitary file access on your PC, so the in-game code won't copy your translation file to game source code folders. `copy_files.py` script can be used for it. Anyway, this practice is not encouraged now, the new addon mode will be better to test your addon, until it is nearly fully finished and about to release as official translations bundled with the game.