SpaceMonger Customization

[ Prev: Contents | Up: Contents | Next: 3. Strings ]

2. The Basics |

> All of SpaceMonger's text is represented using external Extensible Markup Language (XML) files that get read and analyzed when the program first runs or when you tell SpaceMonger to switch languages. (For correctness, we have also included the associated XML Document Type Description (DTD) file so that you can validate your language files externally.)

> In SpaceMonger's folder, you will find several files named `lang-`xx`.xml`. Each XML file represents the complete set of text and menus for one language. Thus `lang-us.xml` contains all the text for "U.S. English"; `lang-fr.xml` contains the text for "Français" (French); and so on. These files are actually plain text files that you can open with any text editor (including Windows Notepad).

> SpaceMonger recognizes files in its directory that have names like these, and, if their contents are recognizably correct XML, SpaceMonger will display the contained language in the list of available languages. You should not change the files included with SpaceMonger. Instead, you should copy one of the files and rename it. (This is not a requirement. We just strongly recommend that you avoid editing the default language files because you may want them again.) So, for example, if you're translating from English to Latin, copy `lang-us.xml` in the same folder, rename it to `lang-lt.xml`, and edit the copy. SpaceMonger will recognize the new file.

> Let's look at one of these files. Open `lang-us.xml` in a text editor. (We will assume throughout the rest of the Customization portion of the User's Manual that you will have one of these files open in a text editor so you can refer to it regularly.) You should see something like this:

>     <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
>     <!DOCTYPE lang-database SYSTEM "wink-i18n.dtd">

>     <!--*************************************************************************
>     **  SpaceMonger 2.x Language Resource File
>     **************************************************************************-->

>     <lang-database langid="US" langname="U.S. English" charset="WestEurope"
>             app="SpaceMonger" appver="2.1" vendor="Sixty-Five">

>             <!--*****************************************************************
>             **  Strings that are common to just about every application.
>             -->

>             <group name="common">

>                     <!-- Common pushbutton text strings -->
>                     <group name="buttons">
>                             <string name="OK">OK</string>
>                             <string name="Cancel">Cancel</string>
>                             <string name="Apply">Apply</string>

>                             . . .

> If you've never seen XML before, this will look a little strange. On the other hand, if you understand some HTML, you don't really have that much to learn. We'll assume from this point on that you know a little HTML, that you know what a tag is, and can use a text editor. If you don't, there are plenty of good books on HTML, and you should probably read one of those first. (On the other hand, we worked hard to make it hard to break SpaceMonger, so even if you don't know exactly what you're doing, it's okay to play with things to see what happens.)

> First, and most importantly, and unlike HTML, XML is case-sensitive. This means that it's important whether the text is upper- or lower-case. So the tags `<group>` and `<GROUP>` are not the same tag; if we show you something in lower-case, it must remain in lower-case, and if it's in upper-case, it must remain in upper-case. There are a handful of exceptions to this rule, which we will point out when we get to them, but for the most part, make sure you keep the right case.

> Next, the `<?xml ... ?>` and `<!DOCTYPE ... ?>` lines are required in every XML file and identify what kind of XML to use and what program the file is for, respectively. For now, just assume that the lines that we give in the example above are necessary at the top of every language database file.

2a. The Root Tag |

> Following the big "SpaceMonger 2.x Language Resource File" comment, you'll see a `<lang-database ... >` tag. This tag marks the beginning of the actual database and defines several important things:

> Attribute | What it means
> --- | ---
> langid | A unique two-character language ID, in upper-case, that will be used to identify this language. Thus "US" for "U.S. English", "FR" for French, "DE" for German, etc.
> langname | A human-readable name for this language. You should use this language's language to write the name; thus for "US" this would contain "U.S. English", for "FR" this would contain "français", and for "DE" this would contain "Deutsch".
> charset | The character set to use when displaying text in this language. The list of character sets are only those sets supported by Windows. The following options are available: WestEurope: Windows' ANSI charset (equivalent to ISO Latin-1). EastEurope: Windows' Eastern-European character set. Baltic: Windows' Baltic-language character set. Greek: Windows' Greek-language character set. Russian: Windows' Russian-language character set. Turkish: Windows' Turkish-language character set. In general, if your native language is English, then you want "WestEurope"; if your native language is not English, then you probably already know which encoding you'll need. In the current version of SpaceMonger, there is no support for Middle-Eastern or Far-Eastern language scripts (sorry). Note also that SpaceMonger ignores the character set given in the `<?xml ... ?>` tag and uses only the one listed here.
> app | This must always be "SpaceMonger".
> appver | This indicates which version of SpaceMonger this file was designed for, and gives the program the option of displaying alternative text if the file and the program don't match versions. The current version of SpaceMonger is "2.1".
> vendor | This must always be "Sixty-Five".
> import | This optional tag lets you import the complete contents of another database before starting this database. This is useful if you're writing a database for a dialect of an existing language, since it lets you avoid coping the whole database. It's also useful if you want to do simple customizations for SpaceMonger, since you can easily add your own entries to menus without changing the original XML file. For an example of dialects, look at the database for British English ("uk.xml"): it imports the U.S. English database ("us.xml") and adds some spelling changes to certain words ("color" becomes "colour", for example). For an example of customization, look at the database named "zz.xml", which inherits the U.S. English database and adds menu buttons for several common programs.

> At the end of the database, there is a closing `</lang-database>` tag. This tag must be the last text in the file.

> Within the root tag, there are `<group>` tags, `<string>` tags, and `<menu>` tags, in no particular order. These form the majority of the database file.

2b. Group Tags |

> A group tag is used to contain other tags in a logical grouping and looks like this:

>     <group name="common">
>     	...
>     </group>

> Group tags may contain `<string>` tags and other `<group>` tags. You should never change the name of a group unless you have a really, really good reason to, since SpaceMonger uses the group's name to locate its contents.

[ Prev: Contents | Up: Contents | Next: 3. Strings ]

Copyright © 2006 by Sixty-Five, Inc. All Rights Reserved.