1. Supported Options for WML/Lua files

When you create an add-on, you may want to see it translated in several languages. You need to create your own .po file. This short page assume you already know how to write a WML file (See also the Official WML Reference).

Here you will find some additional informations, useful for a good usage of wmlxgettext.

Note

Paragraphs from 1.1 to 1.4 will talk about WML code; paragraphs 1.5 and 1.6 will talk about Lua code.

1.1. #textdomain <new_current_domain>

You wesnoth add-on, must contain a textdomain. A textdomain is defined in your _main.cfg file:

[textdomain]
   name="wesnoth-xyz"
   path="data/add-ons/xyz/translations"
[/textdomain]

Note

xyz can be everything. We will use xyz only as an example.

However, the what it is actually important for wmlxgettext is the following line of text that must appear inside all your add-on files:

#textdomain wesnoth-xyz

This will change the current_domain. This is useful, since wmlxgettext will capture only the sentences under the right textdomain (only the sentences under the textdomain of your add-on, to avoid to add undesired sentences).

1.2. # wmlxgettext: <WML_CODE>

You may need to declare a macro definition that uses unbalanced tags like the ABILITY_FEEDING macro defined on the WML core files:

#define ABILITY_FEEDING
# comment omissed
[dummy]
    id=feeding
    name= _ "feeding"
    female_name= _ "female^feeding"
    description=_ " (description omissed)"
[/dummy]
# wmlxgettext: [abilities]
[/abilities]

The example shows a macro wich has unbalanced tags, since there is a closing tag [/abilities] but not the opening [abilities] tag.

Usually, when encountering unbalanced tags, wmlxgettext returns an error, but this time the tags are unbalanced on purpose. This is where the special comment # wmlxgettext: <WML_CODE> helps us.

Coming back to the example showed above, the comment # wmlxgettext: [abilties] will be ignored by the WML code (so the WML code will be unbalanced, as desired); but wmlxgettext will read [abilities] as an actual opened tag, thank of the # wmlxgettext: special comment.

In this way, wmlxgettext will open [abilities] tag when reading # wmlxgettext: [abilities], that will be sucessfully closed when the tag [/abilities] found.

1.3. # po: <addedinfo>

Another special comment (not meaningful on actual WML code, but useful for wmlxgettext purposes) is # po:. Here a fake example:

# po: The speaker is still unknown for the player, but he is a male
[message]
   speaker=unknown_speaker
   message= _ "translatable message"
[/message]

The special comment # po: will add to the translator infos what follows. This is the comments that will be displayed on pot file:

[message]: speaker=unknown_speaker
The speaker is still unknown for the player, but he is a male

The first line displayed to the translator is automaticly generated by wmlxgettext (standard help message).

The second line displayed to the translator is what you typed after the special comment # po:

1.4. # po-override: <override-info>

The special comment # po-override: is similar to # po: special comment already showed before:

# po-override: [message]: speaker=FinalBoss
[message]
   speaker=unknown_speaker
   message= _ "translatable message"
[/message]

This time, the special comment # po-override: will replace the default (automaticly generated) message to the translator. This is, infact, the comments that the translator will be see:

[message]: speaker=FinalBoss

This string will be displayed instead of the default one (in the example, the default overriden message is [message]: speaker=unknown_speaker, wich is, infact, not displayed since it is replaced by # po-override:).

Note

Unlike # po: you can use only ONE # po-override: for every sentence. However you can use one or more # po: special comments together with the # po-override: special comment.

1.5. Changing Domain in Lua code

Changing the current domain value in Lua uses is very different than the WML counterpart.

  • On WML you will change the current domain value with the #textdomain directive
  • On Lua code, instead, the same action is performed in a very different way, using this code:
local _ = wesnoth.textdomain('wesnoth-xyz')

Note

xyz can be everything. We will use xyz only as an example.

In the example showed above we changed, in lua code, the current domain value to wesnoth-xyz.

1.6. Special comments on Lua

On lua code you can also use those special comments BEFORE the translatable string that will require an additional or overridden info:

  • -- # po: <additional info for translator>
  • -- # po-override: <info that overrides the default info>

Note

You can also use -- po: and -- po-override:, instead of -- # po: and -- # po-override: Both forms are allowed.

Those special comments works in the same way as the # po: and # po-ovverride: special comments supported in WML code (see paragraphs 1.3 and 1.4).

Note

The special WML comment # wmlxgettext: is instead unsupported in lua code.

(It is needed in WML code to avoid errors when tags are unbalanced on purpose, so it is useless in lua code, wich is a procedural language and not a ‘tagged’ language).