Textdomain Conventions

It is easy to get your user-made add-on nowadays thanks to the seldom mentioned WesCamp-i18n Project, which is one of the inspirations for Wesnoth-UMC-Dev’s very existence. Having your add-on in our repository doesn’t mean it will be automatically exported to WesCamp and translated, however, but to do so you just need to add a single line to your .pbl file:

translate=true

Unfortunately, this is not enough to ensure an add-on will be actually translatable, and there are certain coding conventions that need to be followed.

First, you need to make sure your content’s textdomain name is in the format wesnoth-Addon_Directory_Name, where Addon_Directory_Name is, well, the exact same name of your add-on’s base directory. For instance, a campaign named Epic Fail would have a root folder Epic_Fail, and a textdomain of wesnoth-Epic_Fail — this is the name to be used in all your #textdomain directives and the [textdomain] declaration in your _main.cfg.

A common misconception is that textdomain identifiers (especially for campaigns) are of the form textdomain-ACRONYM — this is not correct, and acronyms are reserved for future mainline campaigns.

Second, due to limitations of the gettext engine, you cannot have empty strings marked as translatable. The following is invalid:

[message]
    speaker=narrator
    message= _ ""
[/message]

You may, however, have translatable strings consisting of nothing but whitespace. This is still discouraged, but it should not cause problems with the internationalization tools used at WesCamp.

Third, do not include macros with {} in middle of strings marked as translatable. While proper translation catalog entries will be generated for these lines, the game will never be able to localize them to any language due to the nature of this inclusion mechanism — the contents are preprocessed and replaced before the game’s WML parser gets to intervene, and at the end your game will look for a non-existent string in the translation catalogs and give up on the localization.

Optionally, you can choose to use strings from mainline textdomains and reuse their existing translations to save your add-on’s translators some work. A notable use case would be attack names in unit definitions. Strings such as “sword”, “bow” or “staff” are part of the Wesnoth core translations and may be safely skipped from your own textdomain by binding them to one of wesnoth, wesnoth-units or wesnoth-lib wherever applicable. Following with our example case:

[attack]
    name=sword
#textdomain wesnoth-units
    description= _ "sword"
#textdomain wesnoth-Epic_Fail
    type=blade
    range=melee
    damage=5
    number=3
[/attack]
[attack]
    name=gun
    description= _ "gun"
    type=pierce
    range=ranged
    damage=13
    number=1
[/attack]

This associates the string “sword” to the wesnoth-units textdomain while keeping our custom “gun” attack name associated to our own campaign’s translations.

It is not a good idea to bind strings to other campaigns’ or eras’ domains unless you are 100% sure your users will need to have them installed for your content to work at all, even if they are mainline campaigns. The reason for the latter is that distributors may choose to provide the mainline campaigns in separate, optional packages for people such as MP gamers who don’t need things such as music or single-player content.

Generated in 0.003 seconds.
This page was last modified on Fri Dec 17 20:42:06 CET 2010.