Translations

Pioneer aims to be internationalized. To this end, there is support for multiple languages in Pioneer. This document specifies how the languages are defined, and how somebody can translate Pioneer to a new one.

Localization is not a current aim. The game is set in the distant future; any cultural conventions will be drawn from the fictional premise of the game.

There are two translation systems. The first is for the core game engine. The second is for those parts of the game which are implemented in Lua.

Core engine translation

Pioneer selects its languages dynamically, at run time. The languages are defined in files in data/lang. They are should be named after the native name of the language (English, Deutsch, Nederlands, etc) with a .txt filename extension. English.txt should always be present. It is the master language. All other language files should be a translation of English.txt, and any untranslated strings will fall back to the English.

Language files should be encoded as UTF-8, and must not have a byte order marker at the start. The content of the file should look like this:

# This is a comment
GAME_SAVED_TO
    "Game saved to "
SELECT_FILENAME_TO_LOAD
    Select a file to load
COULD_NOT_OPEN_FILENAME
    Could not open %path

Blank lines and lines beginning with # are ignored. All the other lines in the file are interpreted as tokens and definitions, alternately, until the end of the file.

Tokens

The token is a single word or phrase, in capitals, with underscores replacing spaces and with no punctuation. The token is the same in all languages, and uniquely identifies a translatable phrase to Pioneer.

Definitions

The definition is the translatable phrase, in whichever language is specified in the filename. Leading and trailing whitespace are ignored. The definitions are indented for legibility, but this is just for the benefit of the person working with the file, not a technical requirement.

If a translatable phrase should have a leading or trailing space, the definition must be quoted as in the example "Game saved to"' above. This practice is being superseded by tokenization, as described below. If you find a translation where word order would be wrong in your language, please raise an issue on the Github issue tracker so that it can be tokenized.

Tokenization, as in the example "Could not open %path" above, is used where a phrase will have words inserted by Pioneer. In the example, it is the name of a saved game. In others, it might be where a date or a price is used, or a character's name, a piece of equipment or a cargo type. These tokens are not the same as the main language tokens. These tokens begin with a percent sign, and if they are used adjacent to other words, they can be enclosed in braces, as in this example:

NUMBER_TONNES
    %{mass}t

Tokens within definitions must not be changed or translated. If the token is changed, it will stop working.

Lua module translation

Regular translatable phrases

Translatable phrases in Lua modules are defined as tables within Lua files. The filename is arbitrary, and is normally chosen by the script writer, who should ideally have provided translatable phrases in the English language.

Languages are defined as a single Lua table, which contains each language's name as a key, and a further table as that language's dictionary. This is passed to the Translate:Add() function as a single parameter. English must be defined first, otherwise the game can crash. A simple example is as follows:

Translate:Add({
    English = {
        WELCOME = 'Welcome',
        ["That's beautiful"] = "That's beautiful",
    },
    Deutsch = {
        WELCOME = 'Willkommen',
        ["That's beautiful"] = 'Das ist wunderschön',
    }
})

This example adds two phrases each to the English and German languages. While a basic understanding of Lua is helpful, it shouldn't be absolutely necessary.

Note that tokens can be any valid Lua key value. The first style shown above, WELCOME, is a simple token. The other one, ["That's beautiful"], is required wherever a token contains spaces or punctuation. Using the English string as the token makes the mission code more legible.

The definitions are strings. All entries within tables in Lua should be followed by a comma. Definitions might contain tokens; some will be like the ones described in the Core Engine section above, but others might appear in curly braces like {this}. Those tokens should not be modified or translated; they are where the Lua script will insert other values.

Mission flavours

The Translate library also includes methods for dealing with flavours. A flavour is an alternative set of phrases for use in a bulletin board advert, or similar, used to add variety to the same mission.

Flavours are defined as a simple Lua table, and are passed to the Translate:AddFlavour() function, along with the flavour's language and the name of the module. The name of the module must not be changed, or the flavour will not be used. The flavour loader, Translate:AddFlavour, checks for errors. The first flavour to be defined must be English; all others will be checked to make sure that their structure matches that one.

A flavours can be added like this:

Translate:AddFlavour('English','TestModule',{
     title = "Shill bidder wanted for auction",
     greeting = "Hi there.  Want to earn some quick cash?",
     yesplease = "Sure.  What do you need me to do?",
     nothanks = "No, ta - this looks a bit shady.",
})

And another:

Translate:AddFlavour('English','TestModule',{
     title = "Help me win an auction.",
     greeting = "Hello.  I'll pay you to place fake bids for me.  Interested?",
     yesplease = "Yes, I like to live dangerously.",
     nothanks = "No thanks; I'd rather not get arrested for fraud.",
})

The language is specified in the first line as English, and after the language comes the module name, which in this example is testmodule. To add a German flavour, simply copy that structure, change the 'English' to 'Deutsch' and translate the strings between the quotes. As before, if you see tokens like {this}, do not alter them. They will be replaced by another value during the game.

It is not necessary to have the same number of flavours in every language. It is necessary to include all of the keys, and not to add extra ones or mis-spell them. If that happens, it will produce an error.

Submitting work

Ideally, translators should have an account on Github.com and should work from their own fork of the project. New languages, and modifications of existing languages, can be submitted for inclusion in Pioneer by means of a Github.com pull request.

If you do not wish to use Github.com, the next best solution is to submit an email formatted patch set from any other git repository.

If you cannot use git at all, please either email your submission to brian@ppcis.org, or send it to Brianetta on the Space Sim Central forum. Be sure to include your name and email address; these will be used to mark your work on the git commit log.