mirror of
https://github.com/Oreolek/undum-docs.git
synced 2024-06-29 05:05:04 +03:00
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# Translation and Internationalization
|
|
|
|
Undum provides support for translations and internationalization.
|
|
In particular, if you feel you want to translate Undum, then a lot
|
|
of work has already been done for you. I am very grateful to Oreolek
|
|
for this assistance. He translated the Russian version within days
|
|
of the code being released, and advised on the tools that would
|
|
make translation easier.
|
|
|
|
To write a game in another language, you need only to write the game
|
|
content in that language. The identifiers you use in the game (to
|
|
represent situations, actions, qualities and quality groups) must use
|
|
only unaccented lower case latin letters and numbers, but the text you
|
|
generate can contain any content you choose. Including right to left
|
|
content or ideographs.
|
|
|
|
Undum itself has a small number of error messages and pieces of text
|
|
that it uses. These include the default names for the
|
|
FudgeAdjectivesQuality values. These strings are all found at the end
|
|
of the `undum.js` file. They can be overridden. Simply define a new
|
|
language file for your language (e.g. `lang/gk.js`) and override the
|
|
appropriate strings. In your HTML file, after importing `undum.js`,
|
|
import you strings file. For example, the end of the Russian
|
|
translation of the tutorial (`tutorial.ru.html`) has:
|
|
|
|
<script type="text/javascript" src="media/js/undum.js"></script>
|
|
<script type="text/javascript" src="media/js/lang/ru.js"></script>
|
|
|
|
These translation strings are given as an object mapping the string
|
|
name to the translated strings. This object is given as part of the
|
|
`undum.translation` object, with a property name equal to the language
|
|
name. So, for example, the UK English translation might begin:
|
|
|
|
undum.lanuage["en-UK"] = {
|
|
no_group_definition: "Couldn't find a group definition for {id}.",
|
|
|
|
Within the translation strings, data to be incorporated later is given
|
|
in curly braces.
|
|
|
|
|
|
## Language Codes
|
|
|
|
Undum uses a simplified version of the IETF standards for language
|
|
code. For our purposes this consists of three parts, only the first of
|
|
which is required: `language-Script-REGION` where `language` is a two
|
|
letter lower-case ISO language code, `Script` is a four letter
|
|
title-case script identifier, and `REGION` is a two letter country or
|
|
region code, all capitalized. The script is omitted when it is the
|
|
default script for a language and locale. You would specify a script
|
|
if you were using romaji (Latin letters) to write Japanese, but not if
|
|
you were writing it in Kanji and kana.
|
|
|
|
The major virtue of this standard is that it allows fall through when
|
|
a translation is not available. For example a translation into
|
|
Brazillian Portuguese `pt-BR` might be different to one into Angolan
|
|
Portuguese `pt-AO`, but there may be some strings they have in
|
|
common. This allows a translator to create a base file for just plain
|
|
Portuguese `pt`, then each country's dialect can define its own file
|
|
that just overrides a few of the strings.
|
|
|
|
|
|
## Filename Conventions
|
|
|
|
It is only a convention, but for all files that occur in language
|
|
specific versions, I have used the filename convention of placing the
|
|
language code before the extension, e.g. `filename.lang.extension`. The
|
|
game file is similar `filename.game.lang.js`. You are free to use any
|
|
format you choose, of course, but if you want to contribute back to
|
|
the trunk, please follow this convention, to save having to rename
|
|
things and connect up the links later.
|
|
|
|
|
|
## API
|
|
|
|
The translation system provides a simple API based on the `Globalite`
|
|
package of Nicolas Merouze (the implementation is unique to Undum). It
|
|
adds a `l()` method to the Javascript `String` prototype. This method
|
|
has the signature `l(data)`, where data can be any object mapping
|
|
strings to other strings.
|
|
|
|
The method attempts to figure out what the current language is by
|
|
looking at the `lang` attribute of the top level HTML tag (you'll
|
|
notice in the tutorial games this is defined in all cases, you should
|
|
do the same). It then tries to find a matching object containing
|
|
translations in `undum.language`. If it finds such an object, then it
|
|
looks up the original string in that object to find a translation. It
|
|
then merges any data passed into the `l` method into the string,
|
|
before returning the result.
|
|
|
|
The translation look-up honors the IETF rules for language fallback,
|
|
so (continuing the previous example) if your game file is in Brazilian
|
|
Portuguese `pt-BR`, and a translation isn't found, then generic
|
|
Portuguese translation `pt` is also checked. Finally, if no valid
|
|
translation is found, then the default version is used. Since Undum
|
|
was written in English, this default version is the English
|
|
version. This is purely by my convenience, and isn't part of the IETF
|
|
spec!
|