translation guide
Translations are language files located in the languages/ folder. A language file is a simple text file with the .lng extension. You may open it using a text editor such as: Windows Notepad, Vim, Emacs, Programmer's Notepad, Notepad++, Sublime Text, among others.
Once a new .lng file has been put in the languages/ directory, the new translation will be detected automatically. As you'll see in this article, translating the game to other languages is a very straightforward process.
If you enjoy Open Surge and would like to contribute translating it to your language, send your .lng file to Alexandre, preferably by opening a pull request. You need to translate the updated English language file.
Please observe the following:
- Test your translation before submitting it to the project!
-
All texts must be rendered correctly (within their graphical boundaries)
- This requires manual examination of all the texts during gameplay
- Make sure that all texts are correct (no typos / mistranslations)
-
DO NOT use machine translators such as Google Translate to translate the texts.
- Machine translations are not acceptable!
- Finally, use the license of the original English translation
We may accept your translation provided that the project hasn't been translated to your language yet. Please note that translators are asked to keep their .lng files up to date. The game is in development and new texts are often included in new versions.
If you find that a translation for your language already exists (made by someone else), but is currently incomplete or can be improved, you are welcome to send a patch as well. Your help is greatly appreciated!
Important
Use UTF-8 encoding. In your text editor, select UTF-8 without BOM (if available).
Tip
To help you test all texts during gameplay, you may open the secret debug screen. In the options screen, highlight "Stage select", press RIGHT 3 times. Next, enter the Developer Mode. You'll see a list displaying all level files.
Once you open a language file, you'll see something like this:
// ...
// Translation metadata
LANG_ID "en_US" // language code & country according to ISO 639-1 & ISO 3166-1, respectively
LANG_NAM "English" // language name
LANG_AUTHOR "Alexandre Martins" // translation author
LANG_COMPATIBILITY "0.5.0" // required engine version
// ...
This is the English language file. It's a list of key/value pairs, each per line. The first word of the line is the key and the text that secedes it is the value. Now, take a look at the Portuguese language file:
// ...
// Translation metadata
LANG_ID "pt_BR" // language code & country according to ISO 639-1 & ISO 3166-1, respectively
LANG_NAME "Português (Brasil)" // language name
LANG_AUTHOR "Alexandre Martins" // translation author
LANG_COMPATIBILITY "0.5.0" // required engine version
// ...
As you can easily notice, only the values of each key/value pair have been translated.
Each key/value pair defines a constant. In the examples above, OPTIONS_YES stands for YES (in English) or SIM (in Portuguese). You can obtain the value of a key by prefixing it with a dollar sign ($). Example: the value of the key OPTION_YES is obtained by writing $OPTION_YES.
Lines starting with // are comments. They are ignored by the game engine, but can be used to convey meaningful information to humans.
You may include special characters in your messages.
| Character | Effect |
|---|---|
\n |
New line |
\" |
Double quote |
\\ |
Backlash |
Text written inside a <color=RGB_HEX_CODE>...</color> tag will be colored. RGB_HEX_CODE is the hexadecimal RGB code of the color you want to use.
- For example, ff0000 is red and 0000ff is blue; you can get these values with an image editor.
You can also combine color tags with constants. Let's say that you have the following key/value pairs somewhere in your translation file:
COLOR_TITLE "ff8800"
COLOR_HIGHLIGHT "ffee11"
LEV_DEMO_3 "<color=$COLOR_TITLE>Unleash your creativity!</color>\nOne of the key features in Open Surge is <color=$COLOR_HIGHLIGHT>SurgeScript</color>. It's scripting for games! Use it to build anything your imagination can conceive!"
This is the result:
It's possible that the default fonts shipped with the game do not include the glyphs required to translate the game to your language. If this is the case, you will need to add a new font that include those glyphs. Article Fonts describes in detail how to add new fonts to the game and how to configure them for your translation.
In order to add a country flag to the language setting of the options screen, edit file sprites/ui/flag_icons.spr. Refer to the Sprites article for details on how to edit sprites.
If you're creating your own game and you wish to add and/or modify translatable text to your project, you're highly encouraged to use language extensions. Language extensions are available since Open Surge version 0.6.0.
Language extensions are used to add and modify entries of language files without altering those files directly. They are .lng files located in languages/extends/ (this is a special folder). Such .lng files must have the same name as the files you intend to extend. Example: if you want to extend languages/english.lng, then you need to write your entries to langugages/extends/english.lng.
The key benefit of using language extensions reside in the fact that your modifications are kept separated from the files that are shipped with the engine. When upgrading the engine, you will typically overwrite the default .lng files. However, if you use language extensions, you will be able to keep your modifications!
Suppose you want to extend the english.lng file (this is the default language file).
- Copy the examples below to languages/extends/english.lng
- Add or modify entries as in the examples below
- Launch the engine and select the English language
//
// EXAMPLE 1
// Replace "Power" by "Pickups" in the Heads-Up Display
//
HUD_POWER "Pickups"
//
// EXAMPLE 2
// Add a new entry to the language file
//
MY_NEW_ENTRY "My new entry works!!!"