Localization Files

There are few different mechanisms for localizing the UI for the user's language. They all depend on files in the game's UI file. However, they use different files, in different formats.

All localization files live in subdirectories of the locale directory in the UI package. These subdirectories are named with standard two-letter language codes: locale/en for English, locale/de for German, etc.

Elements in XML Interfaces

Displayed document in XML formats (such as SVG) can contain translation entities. See that link for the magic URL which loads these entity definitions.

These definitions are in standard XML DTD format:

  <!ENTITY message "I am message!">

Given this definition, you could then create an SVG element such as:

  <text>&message;</text>

Tokens in RPC Replies and localize() Calls

Tokens in the game, seat, and ui namespaces are loaded from XML files in the game's UI file.

The client searches for files called locale/LANG/gametokens.xml, locale/LANG/seattokens.xml, and locale/LANG/uitokens.xml, where LANG is the two-letter language code of the client's current language setting.

If these files are absent (or if the UI file is not a ZIP archive), then the corresponding namespace cannot be translated into the corresponding language. The token will be translated with a string like "(Untranslatable message: game.token)".

The format of these files, and no I don't have a DTD or schema but you can probably work out how it goes, is:

  <?xml version="1.0"?>
  <volitytokens>
  <token>
    <key>hello</key>
    <value>Greetings.</value>
  </token>
  <token>
    <key>welcome</key>
    <value>Welcome to \1.</value>
  </token>
  <token>
    <key>gamename</key>
    <value>Pilchards and Pitchforks</value>
  </token>
  </volitytokens>

You can put Unicode characters in value tags by encoding them as UTF-8.

Whitespace is not stripped within key and value tags. So don't do this:

  <token>
    <key>             <!-- extra newlines bad -->
      gamename        <!-- indentation inside <key> also bad -->
    </key>
    <value>
      Pilchards and Pitchforks
    </value>
  </token>

If you put whitespace in key tags, they'll fail to match referee messages. If you put whitespace in value, the whitespace will faithfully be copied when printing client failure text. This will produce spurious blank lines and funny indentation, which is generally not what you want. (Although it might be useful for esoteric cases, which is why it's legal.)