Localizing xml files for AoW3

[Rodmar18]

Let's share our ways to localize Age of Wonders 3!
Please, comment on anything wrong/inaccurate/perfectible info.

File format used by AoW3:

Text files used by AoW3 are encoded in utf-8 and are spreadsheet indeed, using the Microsoft Excel 2003 XML format (.xml).

Modifying files with a modern Microsoft Office:


Modifying files with OpenOffice.org or LibreOffice.org:

If OpenOffice.org and LibreOffice.org Calc have build-in import/export XML components, to open and save XML files, they can't manipulate MS Excel XML format without additionnal software components.

As explained on:
https://www.openoffice.org/xml/filter/
These XML filter components are the needed software layer that handles physical files, and they are used as an interface between Excel format (in physical files) and a more meaningful XML format that can be used by the build-in modules.
(WARNING: as I'm translating, some U.I. names may be "adapted"! )

• To check whether such filter components are installed already:

Tools > XML Filter Settings

Check that 'MS Excel 2003 XML' is there.
You can check its installation with 'Edit'.

• Required XML Filter components:

To save/write as MS Excel 2003XML: ooo2spreadsheetml.xsl
To open/read a MS Excel 2003XML: spreadsheetml2ooo.xsl

• Where to put downloaded XML filter components:

(create folder arborescence if not existing yet, also please, adapt path to your usual files folder)

OpenOffice 4.1.6:
(C:\Program Files)\OpenOffice 4\share\xslt\export\spreadsheetml\
for ooo2spreadsheetml.xsl
(C:\Program Files)\OpenOffice 4\share\xslt\import\spreadsheetml\
for spreadsheetml2ooo.xsl

LibreOffice 5:
(I can't get this work, so I'm not sure; perhaps it's the same arborescence as for oo.org)
(C:\Program Files)\Libre Office 5\share\filter\spreadsheethtml\
for both
[EDIT]I could get a hand over LibreOffice 6.2 on W10: filters' location is the same as with OpenOffice, and MS Excel 2003 XML is already configured.[/EDIT]

• To add missing fliter components:

  Tools>XML Filter Settings>New

• General tab:

Fill-in the following fields:
- Filter Name
- Application
- Format type name
- File extension
with:

MS Excel 2003 XML
LibreOffice Calc (.ods) <------ select this
Microsoft Excel 2003 XML
xml;xls

• Transformation tab:

Fill-in the following fields:
- DocType
- Export XSLT
- Import XSLT
with:

Workbook
<absolute path to ooo2spreadsheetml.xsl>
<absolute path to spreadsheetml2ooo.xsl>

• How to open a MS Excel 2003XML file:

Just 'Open with', and choose app, or directly 'Open' if you linked this format to the app.

• How to save as a MS Excel 2003XML file:

Just 'Save as' and select Microsoft Excel 2003XML (.xml). (not any .xls!), and confirm the action.
[EDIT]If the option doesn't appear, and the filter is configured (as I experienced), then test the filter so that the file association is set.

Tools>XML Filter Settings>Test XSLT

[/EDIT]

 

[Rodmar18]

Dealing with in-game replacers and variables:

As in most games, AoW3 uses icons to help the player to quickly grasp the meaning of displayed info.



1) Simple icon replacers: e.g. [hp/] = <heart icon>, [fire/] = <flame icon>

Anybody having thought about altering the localization of the game, or writing one from scratch (translating the game), soon realizes that this translates into having "icon replacers" added in the textual bits. Icon replacers appear as bracketed words, followed by a slash character: [.../].

Spoiler: List of know icon replacers (please comment on them):

[hp/]                       (red heart)
[def/]                      (blue shield)
[resist/]                   (yellow ankh)
[moveWalk/]                 (brown boots)

[gold/]                     (gold coins)
[mana/]                     (blue crystals)
[research/]                 (still)
[production/]               (hammer)
[population/]               (people)
[deadPopulation/]           (skulls)

[happiness/]                (green mask)
[anger/]                    (red mask)

[fire/]
[frost/]
[shock/]
[blight/]
[spirit/]
[physic/]

[resistFire/]
[resistFrost/]
[resistShock/]
[resistBlight/]
[resistSpirit/]
[resistPhysical/]
(those are resist or def icons with a small elemental icon at the center)

[medalIron/]               (iron medal, used for any rank)
[medalGold/]               (golden medal = elite rank)
(not witnessed nor tested other medals: medalBronze? medalSilver?)
[xp/]                      ('xp' in green)
[turn/]                    (hourglass, also used for rounds)
[casting/]                 (white star)
[manaCap/]                 (boxed mana)

• How to deal with icon replacers:

​

As long as they replace known icons, a localizator can move them around so as to comply with the syntaxic rules that are used in the language.​

2) Hybrid replacers: e.g. [hp+/] = [hp/]"Hp", [fire+/] = [fire/]"Fire"

Since DLC3, there are what I call complex or "hybrid replacers". They are used to display the same icon, only it is appended with a character string, a word that translates the icon (e.g. "Hp", "Fire", "Happiness", ...). It was a good idea in English, if you want to illustrate each core word by an adjacent icon, as this is the case in many games. Indeed, these associations already exist in base game and DLC2 files, and they are literally built by using an icon replacer, followed by a word. As I guess, those hybrid replacers where designed to alleviate the burden of writing those repeatitive associations.

• They left however two issues.

​

a/ First one is a consistency issue, as older files (base game and DLC2) were never rewritten with the same replacers, and sometimes, this is visible.​

​

b/ Second one, and a far more grievous issue for localizators, is that now, a word is always appended to an icon, without regard for that language's syntaxic rules, and also adding a capitalized word whereas this could be against these rules. Of course, these added words being separately localized in Interface.xml file, they can be rewritten without a capital, or even replaced with a null "" string... provided they are only used in hybrid replacers.​

• How to deal with "hybrid" replacers:

​

If the systematic association of an icon and a word causes issue with syntaxic rules, the only solution is to replace an hybrid replacer with an icon replacer (and eventually a word), e.g. [hp+/] -> [hp/]. However, in this case, and for consistency reason, all hybrid replacers could have to be replaced.​

3) Variables: e.g. {fireResistance} = "+20%"[fire+/]" Resistance"

A variable appears as a compound string (well, a variable name) between curled brackets {..}; let's say that they can be called "variables" instead of constant replacers.
I guess that they were used to separate the text writing from the balancing task, and they are very useful in this, of course. Although some share the same name, they are usually deemed to be used in a single description key.
Alas, they contain more than raw numbers. In textual bits, a variable is generally the concatenation of a sign ("+"/"-")(optional), a number (always), a percentage sign ("%") (optional), an icon or hybrid replacer (always), and additional words (optional). They really are like bits of sentences that you add to a description. You can't alter their build, you can only use them as they come, or dismiss them. Like hybrid replacers, they use words that are localized in Interface.xml file.

• Localizators potentially face four issues:

​

a/ Sign consistency: depending on the DLC, or a peculiar writing, same effects can have a buit-in sign or not, and sometimes, a negative effect can have a built-in "+" sign because of the built-in word associated to it, or because of the expected word following the variable in this very textual bit. This is the case with "Weakness" as opposed to "Protection" or "Resistance". while this is meaningful and logical, if the rule is consistent throughout the game, this is too much assuming that the localizator wants to or can follow this. Even in English, a weakness is associated with a different (or absent) sign, depending on it's in a faction description, or an ability description.​

​

b/ Hybrid replacers are used inside variables since DLC3 (see case 2, above).​

​

c/ Additional words are used, and they bear the same issues as hybrid replacers: imposed position in the sentence without a regard to syntaxic rules, capital letter, imposed word whatever the context.​

​

d/ A peculiar variable class involves the concatenation of two or more data in one. This aggravates the grief, as you figure, because sometimes (DLC3), the effects are not even separated with a colon, wich is against most syntaxic rules, and certainly against consistency with other phrasing used in the game. E.g. {...} = "2"[frost+/]" 2"[fire+/]​

• How to deal with variables:

​

It depends on each case (and the use of hybrid replacers in DLC3 files).​

​

I'd say that the best variable for a localizator is a variable with only an unsigned percentage or number, and an icon replacer. I believe this is compliant with any language, and any localization choices/style. Thanksfully, most are like this: {arcaneBindingDuration}, {sphereofprotectionPhysicalProtection}, ...​

​

If you need to add a sign, it's then simple: e.g. "+{toughnessPhysicalProtection}". Of course, with built-in signs, that would lead to either "++" or "+-", so watch out.​

​

Some have to be replaced however, and the difficulty for localizators is then to retrieve the value of the number or the percentage by starting a game and peering into the Tome of Wonders (if lucky), or some unit or city panel. Basically, a variable would be replaced by its separated constituents, e.g. literal "-10% [fire/]" instead of built-in "+10% [fire+/] Weakness"​

PBEM & SP Balance mod often replaces variables by their literal expressions when they change a value, and this makes the localization task easier.



I will add screenshots later.

 

[Rodmar18]

Formatting text:

Vanilla files use some kind of format tags that ressemble any marked-up language tags. As far as I know, they are:

• break lines (return to next line). Several can be used in a row.

[br/]        --> go to next line
[br/][br/]   --> skip one line

• bullet lists, as seen in the factions and classes descriptions.

[bulletList]
[bullet] text 1 [/bullet]
[bullet] text 2 [/bullet]
[bullet] text 3 [/bullet]
[/bulletList]

I skipped lines on this example for better visibility, but as they come as opening/closing pairs, tags are usually used on the same line.

[bulletList][bullet] text 1 [/bullet][bullet] text 2 [/bullet][bullet] text 3 [/bullet][/bulletList]

A bullet list always starts and ends on a new line.