Welcome Guest, you are in: Login

Chummer Wiki

RSS RSS

Navigation







Search the wiki
»
Chummer now supports multiple languages! All language files must be placed in the Chummer\lang directory. Translations are handled through two files: a User Interface translation file, and a Data translation file. New strings may be added throughout the development of Chummer as new functionality becomes available. Any new strings that are added or modified will be listed in the revision notes for each update that is released.

Language Fallback

Because of Chummer's constantly-evolving nature, the Language Manager allows for language fallback. If a string does not exist in the language that is selected, it will instead use the English version of the string to prevent something from appearing completely blank. When the application loads, the Language Manager reads in all of the English strings and matches them with their keys. If a different language has been selected, it then reads the language file and replaces the English version of strings with those in the file based on matching keys (meaning that if an entry is not found in the language file, the English value is at least present).

User Interface Translations

All UI strings are handled by the Language Manager. When Chummer starts, the Language Manager reads in the contents of the lang\en-us.xml file which contains the English version of all UI strings. Without this file, Chummer cannot load. Once the English strings are loaded, the Language Manager then reads the selected language file (as long as it is not en-us) and replaces its English content with the content of the language file based on matching keys. If a key exists in the selected language file that does not exist in the English content, it is ignored. If a key exists in the English content that does not exist in the selected language file, the English content is used instead. This prevents fields from being mysteriously left blank or throwing errors.

All language files must be placed in the Chummer\lang directory and must end in .xml. When creating a new language, it is easiest to copy the en-us.xml file and use that as a starting point. When editing a language file, only the contents of the version, name, and text tags may be changed. The contents of the key tags must remain exactly as they are - this is how the Language Manager matches strings to replace the English content with the content in the language file.

Special Characters

The UI translation file make use of a number of C-style special characters.
  • \n start a new line of text
  • {0} or {1} are replaced by values withing Chummer. These are used in places such as The save file {0} could not be found. where {0} is replaced by the file name. If these are present in an English string then your translated string must also contain these to work properly. You cannot add additional values as Chummer can only replace values it knows about.
  • & before a character marks it as a key mnemonic (press Alt+the key mnemonic to trigger the button without having to click it). For example: &Add Cyberware would appear as Add Cyberware and would be triggered when you pressed Alt+A.
  • && creates an ampersand character. For example: Vehicles && Drones would appear as Vehicles & Drones.

Data Translations

All data translations are placed in a single file. Like the User Interface translation file, this file must be placed in the Chummer\lang directory. It must also be named in a specific manner; if your UI translation file is called fr.xml, your data translation file must be called fr_data.xml.

A single translation file is used for all data. There are multiple nodes within the document. Each has a file attribute that indicates the particular data file is to be translated.

When creating entries, the name tag must exactly match the name of an item from the source data file. This is essentially the unique key for the item and is how Chummer matches a data item up with its translation information. There are only a few tags that are supported in the data translation file. They are:

translate - the translated name of the item
page - page number that the item can be found on in the native language book
code - alternate short-hand code for the book in its native language (applies to books.xml only)

If an item does not need to be translated or given a different page number, you do not need to create an entry for it in the data translation file.

The easiest way to get a better understanding of the data translation file, and to use as a starting point for your own translations, is to use the French translation files that are included with Chummer (fr.xml and fr_data.xml).

Verifying Translations

You can verify the contents of translation files through the Options window. Select the language you would like to check, then click on the Verify or Verify Data buttons.

Verifying UI Translations

The Verify button verifies the contents of the User Interface translation file. It checks the English UI file and compares it against the selected UI translation file. If a key exists in the English file that does not exist in the translation file, or if a key exists in the translation file that does not exist in the English file, the mismatched keys are shown in a message box. Keys that do not exist in the English file are ignored as the application has no knowledge of them.

Verifying Data Translations

The Verify Data button verifies the contents of the Data translation file. The verification process may take a moment as it checks the contents of each data file. When the process is done, you will receive a message saying that the results have been written to an XML file.

The file lists the results for each data file (matched by a tag). Any item with an attribute of exists="False" means that Chummer could not find a matching item; either the data file does not exist (in the case of a file tag), or an item with the given name does not exist within the data file. The results file will also list any required tags that are missing for the translated item if applicable.

Always-English Content

Some content will always be in English, largely because they are either not part of the game or not directly a part of the application and outside of the scope of translation support. The items that are not translated are:
  • Verify and Verify Data File buttons in the Options window. It is assumed that someone translating content from English to another language can read English and these are only useful to translators.
  • Content in Omae that is brought in from a webservice which is most of the filtering criteria and all of the user-created content.
  • Chummer Wiki, linked from the Help menu which brings you to this site.
  • Release Notes, linked from the Help menu. This is just a simple text file that describes what has changed between different versions and I'm sure nobody wants to take the time to translate these every time there's an update.
  • About, linked from the Help menu. This is basically the disclaimer of "I don't own the Shadowrun name, game system, etc." so it's not something that anyone should be able to modify.

© ChummerGen.com, 2013