Contents
Introduction
How to Create a New Translation
Testing a Translation
General Guidelines for Translators
Updating a Translation for a New Release
Advanced Topics
Strange Eons uses two different kinds of localization: the game language and
the user interface language. The game language determines the language used on
the cards and characters created by the program. The user interface language is
the language that the windows, menus, buttons, and other controls are presented
in. The two languages are independent. For example, one could use a
Portuguese user interface to create cards for a Spanish game.
- Decide what kind of translation you want to create. There are 4 areas
that you can work on as a translator:
- a new game language (the language used on cards)
- a new user interface dialect (the language used in the editor for menus, buttons, and other
controls)
- the plug-in descriptions in the plug-in catalogue
- the spell-check components for a translation
You can create a new
translation that includes some or all of these elements. You can also
volunteer to work on any of these that are missing for an existing language.
- Get in contact with me. Use the feedback form
to let me know you are working on a new translation. Make sure you include a
valid email address so I can update the list
of active translations and add your address to the
translator's mailing list. If there is already a team working on that
translation, I will send your name and contact information to the lead translator and
the team will contact you to let you know where they need help. If you
have comments or corrections about a translation, I will send those on to
the translation team as well.
- Download the most recent version of Strange Eons available (download the
"Work-in-Progress Release" if there is one).
- Open the plug-in catalogue and install the latest version of the
Translation Tools plug-in.
- Optionally, download the Plug-in Authoring Kit
if you want to use the SE Text Resource Editor (it is in the tools folder).
Translation work is currently transitioning away from using
- Create a new project for your
translation work.
- Add a new translation task to the project. Right-click on the task
folder and choose "Import This Version" to create a folder of text from the
current version of Strange Eons.
- If you want to add support for spelling checking, add a resource
reference task in order to get a copy of the spelling dictionary files.
- Locate the folder where the text resources were unpacked. Have a look
around to get familiar with the contents and structure. If you want to work on a local spelling system, you may
also need to be aware of the phoneme_rule_XX files in the ca/cgjennings/text/spelling
folder of the JAR file (rename the .jar to .zip and
use an archive tool to unpack these).
- Follow the instructions below for the specific areas you want to
translate.
Adding a New Game Language
- Determine your two-letter international language code.
You can
find a list of language codes here (the two letter code is the
rightmost column). Another method is to open a
command prompt (shell), change to the directory of the SE JAR file
and run it with the following command:
java -jar strange-eons-xxx.jar --debug
A bunch of text will be printed as SE starts. Look for a line like this:
Using EN as the game language (the system language is
XX).
Assuming your operating system is running in the language you are
translating to, the XX above will instead be the code for your language.
NOTE: For historical reasons, SE uses capital letters for game
language codes, and lowercase letters for user interface and other language codes.
- Modify text/languages.txt to add your language to the list of
languages. Also add the appropriate credits-XX, and settings-XX
lines.
- Create a new folder text/XX, using your language code in place of
XX. Copy the contents of the English directory (text/EN) into
this folder. Copy the single file settings.txt from the Spanish
translation (text/ES) into this folder, overwriting the English copy.
- Open the new copy of settings.txt. Modify
the settings keys to point to the data files in your new translation. So for
example,
ability-list = text/ES/abilities.txt becomes
ability-list = text/XX/abilities.txt.
- NOTE: The Spanish settings file contains the minimum number of
settings changes needed for the Spanish version. You may need to add other
lines. Anything that can appear in the main resources/settings.txt file
(use a resource reference task to get a copy) or in
card-layout.txt can
also be set here, and anything you define in this file will override the
definition in the main settings.txt when your game language is
active.
- The EN translation is the default, and the other translations are defined in terms of how they are different from
the EN translation. One benefit of this is that you can work on the
translation in pieces and the program should still run correctly, but it
will use the English settings for anything that you have left out. You can
have a look at some of the existing translated files to get an idea of what
you need to do.
- The data files (in particular, card-text.txt) allow you to control
where labels like "Fixed Possessions" get printed on the game card.
Sometimes you will have to adjust these, or make the text smaller, in order
to get the translation to fit. This is most likely when working on cards
like the Investigator card, which have a complex layout. Usually, though,
the value in the English file works fine. When you don't need to change the
setting, it is a good idea to delete these lines as they waste space and
make navigating the file more difficult. (Remember that if you delete these
lines, the equivalent line from the English file gets used instead, so if
the line is the same in your file, it is redundant. If you change your mind
later, you can always add the lines back in.) The exception to this rule is
any line that defines actual text. It is best to leave this in, in case you
decide that it should be re-worded later.
- Start translating. See the general editing
instructions below for more information.
To Create a New User Interface Dialect:
- The user interface localizations are stored in resources/text/interface.
The user interface supports translations into languages and into
dialects of languages. The default user interface is Canadian English.
This is stored in /text/interface/eons-text.properties.
Other translations are stored in the same folder in files with names of
the form eons-text_xx.properties or eons-text_xx_YY.properties, where xx is the country code (in lowercase here, unlike above), and
YY is the dialect code (a
standard two-letter country code, in uppercase). To create a translation for a different language,
create a copy of the base translation (eons-text.properties) with a name of the form:
eons-text_xx.properties, where xx is your language code (e.g., de, es, fr).
(See above if you need help determining your language code.)
- If there is not already a file for your language:
Add a
stub file to indicate the dialect (based on your country) that you will
use. The stub file will not contain any strings, because you will put
them in the base language for your file. (Strange Eons will fall back on
the base language file, and then on the default language file, when a
dialect does not define a particular string.) Copy one of the existing
stubs and edit the comments to reflect your language. Alternatively, you
can also right click on the base file (eons-text.properties)
and choose Add Locale
in a translation task folder.
If a file for your language already exists, and you are adding a new
dialect:
Add a new properties file with a name of the form eons-text_xx_YY.properties,
where xx is your language code and YY is the country code
for your new dialect. In this file, define only those
strings which are different from the default file for your language (eons-text_xx.properties)
in your dialect.
Example
Jean decides to create a French translation. He lives in Rouen,
France. Let us suppose that there is no French translation yet. So he
creates the file eons-text_fr.properties and places his French
translation there. He also creates a stub file eons-text_fr_FR.properties
which is empty except for some comments (see the en_CA dialect for an
example). Now, Zoé decides to create a translation for her dialect of
French. She lives in Montréal, Canada. So she creates the dialect file
eons-text_fr_CA.properties and adds definitions for the strings which are different from the
base fr file in Canadian French.
- Register the new dialect and add credits by editing /text/locales.txt.
Adding or Improving Spelling Support
See the file text/README-SPELLING.txt in the SE resources for
information on the spelling subsystem.
To test a translation in a translation task, right click on the build
folder in the task (bXXXX) and choose Test Translation.
This will let you start a separate copy of Strange Eons that uses your text
files. If your language is not already supported by Strange Eons, it won't
be available in the dropdown lists. Instead, add command line arguments to request
the new language in the Additional Strange Eons
Arguments field (e.g.: --lang zh --uilang zh).
(Note: the JVM command line in the test dialog should work as-is for
Windows. You may need to adjust it for other platforms.)
Working With Files
- When working with SE text files, it is highly recommended that you use
the editors in Strange Eons. If you are an advanced user and wish to use a
different tool, follow these guidelines:
Make sure that all word wrapping is turned off.
-
All game language text files should be saved using the
ISO-8859-15 encoding.
Use Unicode escapes (see below) to insert characters that are not available
in that encoding.
-
All user interface text files must be saved using the
ISO-8859-1 (not
-15) encoding. Use Unicode escapes (see below) to insert characters that are
not available in that encoding.
All spelling word lists should be saved using the UTF-8 encoding with the
.utf8 extension. Follow the convention of adding _cpl to
compressed word lists, and ensure that the settings for the word list
correctly indicate whether it is compressed. If using the SE resource tool,
you should start it with a large maximum memory size, as sorting and
compressing/decompressing large word lists requires a lot of memory to keep
track of the information needed to undo/redo.
- You don't have to complete the translation all at once. You can work on
it in sensible chunks and send me an update whenever you complete a chunk. When you have a new translation chunk ready, zip up the relevant files
and email them to me.
- If your language requires special characters that are not present in the
special card fonts, you have two choices. You can contact me and I will do
my best to add the needed characters (if I can), or, if you know how, you can add them
yourself and send me the updated fonts.
- Generally, lines that start with a # are comments that will be ignored
by Strange Eons. Most files are self-documenting: read the comments in the
file to see what the file is used for and how to format the lines.
- You can insert any Unicode character in a text file using an "escape
sequence": type \uxxxx, where xxxx is the hexadecimal code of
the character. For example, \u2014 would produce an em dash (—). If you are
using the SE Resource Editor, you can just enter the character (use the
Insert Characters... dialog if you can't type it). It will convert to the escape sequence for you if needed.
- You can split up long lines in a text file by ending the line in a
backslash. The string will continue onto the next line, but any spaces at
the start of the following line are ignored. If you need to place a space at
the point where you are breaking the line, place it before the
backslash. And make sure that nothing comes after the backslash that breaks
the line (in particular, be careful not to have any spaces).
- Most user interface strings can use HTML tags if you write <html> at the
start of the text. For example, you could split the "+ Sanity" button over
two lines for the German version by defining it as, e.g.: ie-b-sanity =
<html>Gesundheit<br>Geistige.
- Where you see a notation like %s or %d, it means that
some value will be inserted at that point, like a name, number, or a file
name. In some cases you may want to move the order of these items around to
make a more natural translation. The arguments (the things that will replace
the notations) are numbered according to the order of the notations in the
original text. You can specify a different order by inserting n$
after the %, where n is the number of the argument
in its original order. This sounds confusing, so here is an example:
Original text:
The %s dog has a toy %s.
(e.g., The happy dog has a toy ball.)
Reordered text:
The dog with the toy %2$s is %1$s.
(e.g., The dog with the toy ball is happy.)
The original text could also be written:
The %1$s dog has a toy %2$s.
Suggestions for Translating Game Materials
- Use the official text and wording from your game edition. If you are
missing a particular expansion, you can just leave that text in English for
now.
- More card types have essentially the same layout as their English
counterparts. In some cases (the most common is the Investigator card),
the layout has been modified to get the translated material to fit. You
can fix this by customizing settings from card-lay in the
settings.txt file for your language.
TIP: If your display is large enough, resize the editor
window until the edited card is the same size as a real card. Then hold a
real card up next to the display and compare them.
- Double-check that a card name is what you think it is before
translating. Compare the list price (if any), game effects, etc., to be
sure. If you cannot figure out what the matching card is in your edition,
let me know and I'll try to help you.
- Be mindful of your spelling, especially the spelling of Cthulhu Mythos
names. It won't hurt to run your translation through a spelling checker when
you are done, especially if you are prone to making typing or spelling
mistakes. If you are working with a team, you can proofread each other's
work.
- Keep the translated names in the same order as the original English
names. This will makes things easier if your files need to be updated by a
non-native speaker, and makes it easier for you when new content is added.
Most lists are sorted before they are displayed, so the order you place them in will be
ignored anyway.
I certainly don't consider myself to be the final word on any of this. If you
have tips or suggestions for your fellow translators, please share!
- When I add new content to a text file, I generally mark it with a
tag indicating the version it was added or changed (e.g. [2.1a11]). You
can search for these to look for changes.
- For a more accurate check, use the tools included with the
translation task. Import a copy of the text from the new version. Select
the file you want to check in the older version. Hold Ctrl and select
the same file in the new version. Both the old and new versions are now
selected. Right-click over the new file and choose
Compare Files. A window will open that shows which lines are the
same, and where lines have been deleted or inserted. You can use this to
identify everything that has changed.
- The Strange Eons Text Resource Editor includes some additional tools
for updating a translation in the Tools
menu. (Eventually some version of these should be incorporated in the
translation tools plug-in.)
You can choose the languages you want to use from the
preferences dialog. Sometimes, though, it is convenient to be able to set the
language without changing your settings. For example, you might want to write a
script to start the program in English for comparison purposes. You can request a particular language using the --lang and --uilang command
line options. For example, a command of the form:
java -Xmx512m -jar strange-eons-xxx.jar --lang fr --uilang en_gb
would request French cards and a UK English user interface.
Using Multiple Languages at the Same Time
You cannot switch to another language within a single instance
of SE. However, you can run more than instance of SE at a time, and use a
different language for each. To do this:
-
Start SE and open the Edit | Settings... dialog box.
-
Under Miscellaneous Options, make sure that Limit
to Single Instance is not checked.
-
Change the language settings to whatever you want the second
copy to use.
-
Press OK to accept the changes.
-
Start a second instance of SE. It will run in whatever
language you selected. (You could also start it with a given language from
the command line as described above.)
-
Repeat as often as desired.
Dialects With Pluralization Rules Different from English
In English, and many other languages, only two word forms are used in to
construct plurals: a singular form and a plural form. However, many languages,
such as languages in the Slavic, Semitic, and Celtic families, have more than
two plural forms or use different rules when deciding which form to use. Strange
Eons can support these languages, although I must be contacted because support
requires writing a small algorithm that can select the appropriate form.
Here is the general procedure:
- Get in touch with so we can discuss the particular rules for your
dialect. We will agree on a particular order that the different forms should
come in. For example, suppose your language has 2 plural forms and 1
singular form. The singular form is used only with 1, one plural is used
only with 2, and the other plural is used with everything else. We might
arrange it so that the plural for 2 is the "first" plural, and the other
plural is the "second" plural. (There is only one singular, so it is the
"first" singular by definition.)
- When translating text that uses different keys for singular and plural,
if the form is not the "first" one of its kind, add a number (2 for second,
3 for third, and so on) to the key right after the part that distinguishes
between singular and plural in the original keys. For example:
common-item-text = Common Item
common-item-pl-text = Common Items
becomes:
common-item-text = [first plural form, typically singular]
common-item-pl-text = [second plural form]
common-item-pl2-text = [third plural form]
common-item-pl3-text = [fourth plural form]
etc.
Pluralizers have already been added for the languages currently included with
the application. However, most of these do not yet define "-pl2" keys (for
languages that need them), so they will generate incorrect plurals in some
cases. (When a "-plX" key is missing, the X-1 key is used instead. See the
Release Notes for 540 (2.1 alpha 2) for details.
Label Aspect Ratio
Left-justified labels which are printed in the title font (for example, the
skill and home labels on investigator sheets) may have their aspect ratio altered
by supplying a key and value of the form:
[region-key-base-name]-ratio = ratio of width to height
For example:
home-text-region = 31,438,75,42
home-text-ratio = 0.75
Arbitrary Extra Regions on Front Investigator Sheet
You can add arbitrary extra regions to investigator cards. The German
translation uses this to split the Sanity label over two lines.
The regions are numbered from 1 to the value of number-of-extra-regions. For
each region, you must include a set of keys for the type, content, region,
typesize, and colour; e.g.:
inv-number-of-extra-regions = 2
inv-extra-1-type = left
inv-extra-1-text = Example Extra Region 1
inv-extra-1-region = 0,0,100,100
inv-extra-1-pointsize = 16
inv-extra-1-colour = black
inv-extra-2-type = center
inv-extra-2-text = Example Extra Region 2
inv-extra-2-region = 100,0,100,100
inv-extra-2-pointsize = 12
inv-extra-2-colour = red
The possible values for the type of an extra region are:
left : text is left-justified in the title font
center : text is centered in the title font
body : text is left-justified in the body font
Colours can be any colours (not tints) defined in the settings file, which in the standard
files means at least black, blue, red, green, yellow, or purple. You may define
additional colours by adding them to your settings; the key name should end in
-colour and the format is the same as for the existing colours (a
hexadecimal integer in RRGGBB format).
January 10, 2007 — Updated
January 01, 2011