Skip to content

Translating Magarena

Jump to bottom Edit New page
lodici edited this page Jul 21, 2017 · 71 revisions

Translations of the user interface are performed using a simple text file generated by Magarena. Here are a few lines taken from a newly created translation file -

4209253986 = ▫Migrate data from an existing installation of Magarena.
3937389802 = ▫Download card images
3365541470 = ▫Run Firemind Worker
2823720574 = ▫Toggle full-screen
2150973105 = ▫Shortcut key: F11
1034062502 = ▫Close menu

Using your preferred text editor, simply replace the English words or phrases after the = sign with the required translation. For example, here are the same entries translated into Portuguese -

4209253986 = Importar dados de uma instalação pré-existente do Magarena.
3937389802 = Baixar as imagens das cartas
3365541470 = Sediar duelos do Firemind
2823720574 = Mudar para tela inteira
2150973105 = Tecla de atalho: F11
1034062502 = Fechar menu

The current set of translation files can be found in <install folder>/Magarena/translations.

Translation file

Encoding

It is very important that the file is encoded as UTF-8 without BOM. Magarena will automatically do this for you when it creates the file. However because you will be editing the file using your preferred text editor, on saving your changes it is possible that an old or badly behaved editor (eg. Windows Notepad) will change the file to a different encoding. If this happens then Magarena will not be able to load the translation file.

Format

4209253986 = ▫Migrate data from an existing installation of Magarena.

Each line in the file consists of a 10-digit number followed by an = sign and ending with a word or phrase. Only the text after the = sign should be changed.

The small square ▫ prefix character has no meaning other than as a visual aid to help identify untranslated text both in the file and in the user interface itself. It should be removed when updating with the translation.

The following characters should be treated as literals although it may be necessary to re-position within a phrase or sentence depending on the language's grammatical rules.

literal description
%s, %d replaced with dynamically generated data.
%% displays percentage symbol.
\n, | new-line
<html>, <br>, ... various html tags.
{f} replaced with an icon.
\" displays a double-quote.
\u2022 displays the "•" (bullet) symbol.
\\ displays the "\" (path separator) character.
%.1f java numerical formatting string.

Header line

Introduced in version 1.86, the first line of the translation file has been reserved for additional metadata and is updated each time Magarena creates a new translation file or synchronizes an existing one. This line, which should remain unaltered in the translation file, contains one or more values separated by the ¦ character as described in the following table.

# name value
1 version records the version of Magarena against which the translation file was generated.
2 font flag 0 or 1 prevents or allows use of custom fonts in the UI.

Comments

It may be difficult to work out the translation for some text. In these cases there will usually be a comment on the preceeding line that attempts to convey the meaning. A line is considered a comment if it starts with a # character. For example -

# 0256104689 eg. Creatures (28 cards, 46%)
0256104689 = ▫%s (%d cards, %d%%)

# 3864448769 eg. {f} will be replaced by an icon.
3864448769 = ▫Click {f} or Space to pass.

Please do not translate these comment lines as they are automatically generated each time the file is opened from Magarena. They are there for guidance only and are not displayed in the UI.

Create a new translation file

  1. Open the Preferences dialog from the Settings menu.
  2. On the General tab, click the button next to the User Interface language setting.
  3. From the popup menu, click New Translation.
  4. Enter the name of the translation file, for example français.
  5. Magarena will create a file, français.txt in the Magarena\translations folder and ask the operating system to open it using the default text editor. If Magarena is unable to open the default text editor, please open the popup menu again and click on File Explorer to open the location of the translation file instead.
  6. Note, any changes you make to the translation file will be not be reflected in the UI until you restart Magarena.

Update an existing translation file

  1. Open the Preferences dialog from the Settings menu.
  2. On the General tab, select the required translation from the drop-down list.
  3. Click the elipsis button on the right to display a popup menu.
  4. Select the Edit option.
  5. Magarena will ask ask the operating system to open the translation file using the default text editor. First though, it will synchronize the contents of the file with the latest UI, adding any new entries to the top of the file above the existing translations.
    If Magarena is unable to open the default text editor, please open the popup menu again and click on File Explorer to open the location of the translation file instead.
  6. Note, any changes you make to the translation file will be not be reflected in the UI until you restart Magarena.

Using a translation

  1. Open the Preferences dialog from the Settings menu.
  2. On the General tab, select the required translation from the drop-down list.
  3. Click Save. You will be asked if you want to restart Magarena.

Developer Guide

When Mangarena generates the translation file it uses reflection to look through each class in the jar file in order to find all string constants beginning with _S. For this mechanism to work it requires following a simple convention (eg. see a579c16) -

  1. Replace string concatenation (ie. using +) with the placeholder format - String.format(<string>, <args>..). This is generally considered good practice anyway and produces more readable code.
  2. Move inline strings to a static final constant with a name beginning with _S. I use _S1, _S2, ..._Sn, attaching no meaning to the constant name since my IDE (Netbeans) lets me easily see the value by moving the cursor over a _S reference. I would imagine this would also be the case for other IDE's like Eclipse. However, you can use meaningful names if you wish just as long as they start with _S.
  3. Use MText.get(_S?) or MText.get(_S?, <args>..) in place of the inline string, where _S? is the equivalent _S reference.
  4. Where appropriate use the @StringContext annotation to better convey the meaning of a string to the translator. This will appear as a comment in the translation file. For example, #1 and #2

Abbreviations

When working with abbreviations there is a chance that you could end up with the same hash code which will cause problems with translations. For example, in English the abbreviation 'P' is used in player stats to refer to Games Played but on the card explorer screen it is used as a column heading for creature Power. Both screens defined 'P' as a translatable string and so generated duplicate hash codes, only one of which would actually end up in the translation file.

To overcome this the MText.abbreviate() method was added to ensure a unique hash code that is based on an abbreviation and its meaning. The following examples should help to explain how to use it - PlayerMiniStatsPanel and CardTableColumn.

Keywords translation

The keywords screen can be opened any time using the K key or via the Help -> Keywords glossary menu option. By default it gets its content from the English.txt file in the ../Magarena/translations/keywords folder.

You can force Magarena to use a different content file when running in another language by adding a new file in the keywords folder with the exact same name as the main translation file.

Please check the top of English.txt which describes the format of the keywords file. As long as this format is adhered to you are free to add whatever content is deemed appropriate.

home • wiki • top

Home
Getting Started
Upgrading
Command-line arguments
Feedback / Bug Reporting
Contributing

Player Guide

Keyboard shortcuts
Supported deck formats
Themes
Customizing Magarena
Translating Magarena

User Interface
Main Menu Screen
New duel
Deck view
Deck Editor
Mulligan screen
Game screen
Card Explorer
Card Script Viewer
Download images
Preferences

Scripting Guide

Groovy Guide

Developer Guide

New cards for next release

Artificial Intelligence

Links

Clone this wiki locally