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:
|
<![CDATA[
<?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.
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.