|
|
| Line 1: |
Line 1: |
| − | 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. | + | All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know. |
| | | | |
| − | 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.
| + | == For translators == |
| | | | |
| − | 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.
| + | All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project]. |
| | | | |
| − | ==Core engine translation==
| + | Changes to translations are automatically pulled into the master git repo once per day, and from there to the builds when they're next run. |
| − | 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 <code>.txt</code> filename extension. <code>English.txt</code> should always be present. It is the master language. All other language files should be a translation of <code>English.txt</code>, 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:
| + | In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it. |
| | | | |
| − | # This is a comment
| + | If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you. |
| − | 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.
| + | English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal. |
| | | | |
| − | ===Tokens===
| + | Untranslated strings will use the value from the English version. |
| | | | |
| − | 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.
| + | You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string. |
| | | | |
| − | ===Definitions=== | + | == For mod developers == |
| | | | |
| − | 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.
| + | Each module gets its own translation resource, called <tt>module-foo</tt>. |
| | | | |
| − | 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 [https://github.com/pioneerspacesim/pioneer/issues Github issue tracker] so that it can be tokenized.
| + | To get at the strings for your module, do something like: |
| | | | |
| − | 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:
| + | local Lang = import("Lang") |
| | + | local l = Lang.GetResource("module-foo") |
| | | | |
| − | NUMBER_TONNES
| + | Then you can get at the string by its token: |
| − | %{mass}t
| |
| | | | |
| − | Tokens within definitions must not be changed or translated. If the token is changed, it will stop working.
| + | print(l.SOME_TRANSLATED_STRING) |
| | | | |
| − | ==Lua module translation==
| + | While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository. |
| − | ===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.
| + | Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an tables of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex. |
| | | | |
| − | 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:
| + | If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include <tt>en.json</tt> in your patch. |
| | | | |
| − | Translate:Add({
| + | == For core developers == |
| − | 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.
| + | The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>. |
| − | | |
| − | 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 [mailto:brian@ppcis.org 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.
| |
All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.
For translators
All our translations are managed through Transifex, a web-based translation service. To start writing translations, sign up there, and then take a look at the Pioneer project.
Changes to translations are automatically pulled into the master git repo once per day, and from there to the builds when they're next run.
In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.
If you want to translate Pioneer to an entirely new language, please open an issue on the tracker and someone will create the translation for you.
English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.
Untranslated strings will use the value from the English version.
You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.
For mod developers
Each module gets its own translation resource, called module-foo.
To get at the strings for your module, do something like:
local Lang = import("Lang")
local l = Lang.GetResource("module-foo")
Then you can get at the string by its token:
print(l.SOME_TRANSLATED_STRING)
While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository.
Translations are chrome.i18n JSON files. The format is fairly simple - an tables of tokens as keys, with values of a table with two keys, message and description. message is the text that will appear in the game, while description provides instructions for the translator that will be displayed in Transifex.
If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include en.json in your patch.
For core developers
The core resource is magical. If you add a string to it, you also need to add it to LangStrings.inc.h and recompile. It will then be available as Lang::SOME_TRANSLATED_STRING.
