Aetheria Game Engine (AGE) has been designed to be a multi-language system. Everything in AGE can be easily adapted to other languages, including both the graphical user interfaces (program menus, buttons, etc.) and, more importantly, the game parser and messages themselves. This allows programmers to create IF and related games in various languages, and players to enjoy them in their chosen language.

Currently, AGE supports the following languages:

The goal is to support as many languages as possible, and as completely as possible. If you would like to add support for another language, this guide will tell you how. The only thing you need is knowledge of the target language and of one of the languages already supported by AGE (see the table above). You don't need any knowledge of programming to translate AGE to a new language. The vast majority of what is necessary for adapting AGE to a new language is pure translation work, with only minimal programming work needed. If you are willing to do the translation work, I (the AGE developer and maintainer) will do the coding work. You can contact me at solrac888 (at) yahoo (dot) com for this purpose, and this guide will tell you what you need to tell me so that I can incorporate your translation to the system.

The remainder of the guide is structured in four sections, corresponding to the separate components of AGE that can be translated: the AGE user interface (i.e. buttons, menus, etc.), the PUCK (development system) user interface, the game parser (i.e. what allows you to make or play games themselves in other languages) and the programmer's documentation (for programmers to learn to create AGE games).

Each of those components is independent of the others, and can be translated independently. For example, it is possible to have the user interface in English, and use it to play Spanish games, or vice versa. Therefore, contributions on any of the four components will be very welcome. If you do not have the time or the will to translate everything, please do not hesitate to contribute a translation for one of the components, or even part of it. The rest can always be translated later by other contributors.

In this respect, it is worth noting that the AGE and PUCK user interfaces take the least work to translate, while the game parser and documentation take some more work.

Translating AGE's graphic user interface (menus, buttons, etc.) to a new language is very easy. You only need to follow the following steps:

• Go to http://code.google.com/p/aetheria/source/browse/#svn%2Ftrunk%2Fage%2Fsrc%2Feu%2Firreality%2Fage%2Fi18n and download the UIMessages.xx file, where .xx is the code (see table above) of the source language that you want to translate from. For example, if you know English, you can download UIMessages.en, which is the file with the AGE user interface messages in English. Note that, after clicking on a file name, you need to click on “View raw file” to actually download the file (and not the preview).
• You will see that the file contains one message per line, in the format message.name=The message text. Translate the message texts without touching the names. If there is any doubt about the context of a message, you can ask me or run AGE and see where in the menus it appears, although I think it should be obvious 99.9% of the time. Note that the file is encoded as UTF-8, this means that you can use practically any alphabet. You must not change this encoding when translating the file (this should not be a problem, as most text editors will not do that if you don't choose to change it explicitly).
• Send the file to me and I'll incorporate it into AGE. It's that easy.

The procedure is the same as for AGE's user interface, just with a different file. Follow the following steps:

• Go to http://code.google.com/p/aetheria/source/browse/trunk/#trunk%2Fpuck%2Fsrc%2Forg%2Ff2o%2Fabsurdum%2Fpuck%2Fi18n and download the Messages.xx file, where .xx is the code (see table above) of the source language that you want to translate from. For example, if you know English, you can download Messages.en, which is the file with the AGE user interface messages in English. Note that, after clicking on a file name, you need to click on “View raw file” to actually download the file (and not the preview).
• You will see that the file contains one message per line, in the format message.name=The message text. Translate the message texts without touching the names. If there is any doubt about the context of a message, you can ask me or run AGE and see where in the menus it appears, although I think it should be obvious 99.9% of the time. Note that the file is encoded as UTF-8, this means that you can use practically any alphabet. You must not change this encoding when translating the file (this should not be a problem, as most text editors will not do that if you don't choose to change it explicitly).
• Send the file to me and I'll incorporate it into AGE. It's that easy.

Translating the game parser and messages, i.e. the game engine itself, to other language can require some programming work: apart from translating messages, one needs to take into account some other issues to adequately parse the player's input and provide descriptions of the world. However, the way AGE is designed, this programming work should be very easy and short for the vast majority of languages - if you know Java, you can have a look at the existing language classes at http://code.google.com/p/aetheria/source/browse/#svn%2Ftrunk%2Fage%2Fsrc%2Feu%2Firreality%2Fage%2Flanguage, but if you don't (or just do not feel like coding), I am willing to do it myself if you take care of the pure translation part.

We will first proceed to make an inventory of the aspects of your language that will affect the translation and that you need to tell me for me to do the coding work; and then describe what you will need to do.

To allow AGE to fully support games in your language, we will first assess the feasibility of the translation.

Human languages are, in general, very difficult to accurately process with computer programs. However, in IF we have the enormous advantage that we do not need to parse the language in general, but only a very specific kind of sentences: imperative sentences, i.e., sentences which represent direct orders such as “go north” or “take the lamp”. This kind of sentences tend to have one or a few very specific syntactic structures, so that we only need to deal with a tiny subset of the language: features like past tenses, passive voice, etc. do not appear in the standard inputs to IF games.

Taking advantage of this, AGE has been designed to be very easily adaptable to a very wide range of languages. However, there are some cases (such as languages with more than two genders or with highly irregular declensions) where non-trivial coding work is required and a fully functional translation will not be possible in the short term.

To see how easy it is to translate AGE to your language and which coding work needs to be done, and to give me the information I need for doing the coding, please take note of the following facts about your language:

1. In which order do the subject, verb and objects of an imperative sentence naturally appear in your language?

In English, imperative sentences are of the form verb + objects (as in “take the lamp”, “give the lamp to John”). However, other languages may have different orders, such as the verb going last. This is no problem in AGE, but you have to tell me the order your language uses in order to configure it in the AGE code.

2. Does your language have grammatical gender affecting determiners and pronouns? If so, how many genders are there?

In some languages, nouns are classified in categories, called genders, that affect some words (such as determiners and pronouns - also adjectives, but we do not care about those) that go with them. For example, English has no grammatical gender, and every common noun can go with the article “the”, as in “the actor / the actress”. In contrast, Spanish has grammatical gender, so that “the actor” translates as “el actor”, whilst “the actress” is “la actriz” - “el” being the masculine article, and “la” the feminine article.

If your language has two grammatical genders, coding their support in AGE is trivial, you will only need to tell me which are the definite and indefinite articles (if any) for each gender (better with an example sentence of each) so that I can configure AGE to show them correctly.

If your language has more than two grammatical genders that affect articles and pronouns, it may be difficult to make the translation work in the short term (as AGE was designed for languages with two genders and I would need to add support for more). Please consult me.

3. Does your language have word contractions involving articles and/or prepositions?

Many languages have pairs of words that can or must contract into a single word when they appear together. In English, for example, we can contract “it is” to “it's” or “do not” to “don't” - but this does not really affect AGE localization. What can have an influence is contractions that involve articles and/or prepositions. For example, in Galician, every time the preposition “con” (with) appears together with the article “o” (masculine form of “the), it must mandatorily contract into “co” (with the). This means that I need to add some very easy code to handle the contractions when showing messages like “the goblin attacks you with the short sword”, where those words can happen to appear together.

If your language has contractions involving articles and/or prepositions, give me a list of them and how they are formed (e.g. con+o=co) so that I can create that code and make AGE display texts in a natural way in your language. I also need to know if articles and prepositions must take different forms depending on words surrounding them - e.g. as in English, where the indefinite article is “a” before a consonant sound, and “an” before a vowel sound.

4. How do you say him/her/it in your language? Does your language have clitic pronouns for direct objects?

In English textual games, if we have referred to an object previously, we can use a pronoun. For example: “Take the sword. Drop it” or “Look at Jack. Greet him”. I will need to know how you say these pronouns (him/her/it) in your language, in order to code the support for that.

Additionally, some languages make these pronouns clitic, i.e., attached to the verb instead of appearing as individual words. For example, in Spanish “greet him” would be “salúdalo”, with no space between “saluda” (saludar) and “lo” (a clitic form of “him”). If your language has this kind of pronouns, please tell me which they are and how they are attached to verbs.

5. Does your language have a case system for nouns? If so, how does it work?

In some languages, nouns take different forms (declensions) depending on their case. For example, in Latin, if the noun Roma (Rome) is the subject of a sentence, it appears as Roma (Roma pulchra est - Rome is nice), the so-called nominative case. However, if it is the direct object, it appears as Romam (Camillus Romam ex obsidione Gallorum liberavit - Camillus liberated Rome from the siege of the Gauls).

There should be no problem in AGE to handle a case marking system like that of Latin (it's simpler than it seems, since again, in imperative sentences you only get very specific cases). However, some languages (such as Basque) have much more complex case systems, with a large amount of cases and highly irregular inflection, that can be more problematic unless the IF game author is willing to manually input the relevant declensions for each noun. If your language has declensions for noun cases, please tell me how they work so that we can deal with this.

To translate the AGE parser and messages to your language, you need to download the following files (which you are going to translate):

• Go to http://code.google.com/p/aetheria/source/browse/#svn%2Ftrunk%2Fage%2Fsrc%2Flang and, under the subdirectory of the source language, download the files alias.lan, common.lan, messages.lan, and verbos.lan. For example, if the language from which you wish to translate is English, you would go to http://code.google.com/p/aetheria/source/browse/#svn%2Ftrunk%2Fage%2Fsrc%2Flang%2Fen and download those four files from there. Note that, after clicking on a file name, you need to click on “View raw file” to actually download the file (and not the preview).
• From the http://code.google.com/p/aetheria/source/browse/#svn%2Ftrunk%2Fage%2Fsrc%2Flang directory itself, download a tr-xx-en.lan file. For example, this can be tr-es-en.lan. This is a table that translates some common Spanish verbs into English.

Note that all these files use the UTF-8 text encoding, and your translation should, too. Generally you need not worry about this, as text editors preserve the encoding of files unless you explicitly tell them to do otherwise.

Now you can translate the files, following these instructions:

The alias.lan file contains aliases, i.e., commands that should automatically be translated to other commands. For example, this is the file that tells the system that “west” or “w” are shorthand for “go west”.

Therefore, you will use this file to set the aliases for your language, by translating both the leftmost part (the shorthand or alias) and the rightmost part (aliased command). For example, the line “w=go west” in English corresponds to “e=ir al este” in Spanish. Do the same for your language, following the standard abbreviations in it or creating them if they do not exist!

The common.lan file is a list of words that can commonly appear in the input without being either verbs or words specific to the game's vocabulary. Typically, you will want to have here a list of prepositions, articles, numerals, pronouns and conjunctions in the language. This will ensure that, even if those words are not explicitly defined in a game, the parser will acknowledge that they are “real words” and not try to correct them to some similar word that it knows. For example, if the word “other” is not included in common.lan and the player types “take the other sword”, and there is an otter in the game, it will try to autocorrect “other” to “otter” as it's the closest word that the game nows. Including “other” in common.lan, we prevent this.

As you can imagine, situations like that are not that common, so it is not extremely important to have an exhaustive list in common.lan. The English file is minimal and the parser tends to work fine, even if it may have slightly lower precision than the Spanish parser which has a much more extensive list. So you can just create a very small list to get started, and words that tend to create confusion can be added later.

This is a message file in a similar format to those of the AGE and PUCK user interfaces mentioned in previous sections. It consists of entries like for example

#When you place $item in $container
you.put.into=You place $item in $container.\n

The right-hand side of the equality (You place $item in $container.\n) is a game message, with placeholders (in this case, $item and $container) that will be changed to names of entities in the actual game, and a “\n” meaning a line break in the output. For example, this message could show in a game as “You place the sword in the chest.”

You will need to translate the right-hand side (except for the placeholders, that should be exactly the same -in this case $item and $container- in the other language, and the \n) and leave the left-hand side as it is, since it's the name of the message. The comment can optionally be translated to help people doing other localizations and game programmers that need to make sense of the messages. So we would get something like (in Galician):

#Cando pós $item en $container
you.put.into=Pós $item en $container.\n

Note that the messages.lan file is rather long, but you can save a lot of time by using an automatic translator to do a rough and then revising it by hand, at least for languages that are close to each other - with this method I was able to translate the Spanish file to Galician in a very short time.

verbos.lan is a list of verbs that could potentially be used in a game. In principle, decent results can be obtained by listing only the verbs that are default AGE commands (such as “go”, “take”, “drop”, “attack”, etc.), so a good starting point is to limit yourself to these initially, and perfect the list later.

The advantage of adding more verbs to the list (including even infrequent verbs) is that, if by any chance the player types one, it will be recognized as a verb (even if the game does not exactly know what to do with it) and this will affect parsing precision.

For example, suppose the player types “take the sword and yell”. If the verb “yell” is on the list, AGE will correctly interpret that you want to first take the sword and then do something else (even if that something hasn't explicitly been programmed in the game). If the verb “yell” is not on the list, AGE will think that you want to take something called a yell (or maybe auto-correct it to “bell” if there is a bell in your game). This is why having as many verbs as possible is desirable but just the most common ones are enough for rather good results.

If you look at the format of the verbos.lan file in English, you may be surprised by its redundancy. It is full of entries like

open=open
reduce=reduce
settle=settle

And so on. The reason for the two copies of each verb is that the verbos.lan file, apart from being a mere list, has a second function: it is used to transform verbs into a canonical form when there are several possible verb forms that can naturally appear in an imperative sentence.

For example, in Spanish IF, you can give orders in infinitive (“coger la espada” for “take the sword”) or in imperative tense (“coge la espada” for “take the sword”). For this reason, the Spanish verbos.lan file has an entry

coge=coger

To indicate that appearances of the form “coge” have to be changed to the canonical (infinitive) form “coger”. That way, the game author only has to make sure that she handles the verb “coger” correctly, and “coge” will be automatically handled.

In English, these nuances are not necessary because there is only one form for each verb that makes sense in game orders (as the imperative and infinitive in English are identical). If you are translating to a language where this is the case, you can just write the same form in both sides of each line, as in English. If you are translating to a language where several forms make sense, like Spanish, you will need to choose one as the canonical form and write the lines in the form non-canonical-form=canonical-form (and note that it is perfectly possible to have several non-canonical forms for the same canonical form, by adding several lines for that verb).

The tr_xx_en.lan file (xx being a language code) is a file that contains translations to English of a few dozen of verbs, which are used (or may be used in the future) by AGE. This file is needed to translate verbs in your language to actions, so that AGE can understand that if you type e.g. “coller” in Galician, that means “get” and you are telling the parser to get something.

You can take for example the tr_es_en.lan file as reference, and translate the left side of each verb (the Spanish side) to your language, so that it matches the English side. Note that if a verb has several possible imperative forms as mentioned in the last section, you only need to provide the translation pair for the canonical form, so this should be short work.

At the moment, it is not necessary to add additional verbs to this list apart from the around 40 verbs present in the existing localizations, as this file is only used for verbs that are used internally by the AGE core (i.e., default AGE commands), and has no influence at the moment on custom verbs defined by specific game authors, which will link their verbs to behaviors with their own code. Adding more verb pairs could be useful in the future to support features like games with embedded machine translation, though.

The only remaining thing would be to send the translated files to me -together with the linguistic inventory mentioned above- so that I can put the translation to work!

The programmer's documentation is located in the wiki http://www.caad.es/aetheria/doc/.

The automatic registration form in the wiki has been disabled due to spam attacks, but I can register you manually. If you are interested, just write me at solrac888 at yahoo dot com with your desired username, email address and initial password and I will make an account for you.

Then, you will be able to edit and add pages to the documentation. To translate a page to English, just go to the Spanish page and click the “English” flag, and you will be able to write a translation. To see the format that the wiki expects, you can click on “Edit this page” in the Spanish page and see the source code, which you can also use as the source for your translation.

If you wish to translate documentation into a language different from English or Galician, just ask me to add the flag for that language and I will do it.