Difference between revisions of "Translation Guide"

From Open Surge Engine Wiki
Jump to: navigation, search
m (I want to help!)
m (I want to help!)
Line 23: Line 23:
 
'''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 and enter. You'll see a list displaying all level files.
 
'''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 and enter. You'll see a list displaying all level files.
  
'''Important:''' use UTF-8 encoding (it should be UTF-8 without [http://en.wikipedia.org/wiki/Byte_order_mark BOM]).
+
'''Important:''' use UTF-8 encoding (it must be UTF-8 without [http://en.wikipedia.org/wiki/Byte_order_mark BOM]).
  
 
== How to translate ==
 
== How to translate ==

Revision as of 21:01, 30 January 2020

Overview

Introduction

Translations are language files located in the languages/ folder. A language file is a simple text-based file with the .lng extension. You may open it using a simple text editor like Notepad, Vim, Programmer's Notepad, or Notepad++. You can also use the Language Editor, a graphical tool to open and edit existing language files.

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.

I want to help!

If you enjoy Open Surge and would like to contribute translating it to your language, send your .lng file to Alexandre - see: Contact the developers (if you're familiar with Git, do a pull request).

You need to translate the updated English language file (check the link).

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)
  • Finally, please 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 may be included in new versions.

Your help is greatly appreciated!

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 and enter. You'll see a list displaying all level files.

Important: use UTF-8 encoding (it must be UTF-8 without BOM).

How to translate

File format

Once you open a language file, you'll see something like that:

// ...

// Translation metadata
LANG_ID                     "en_US"                   // language code & country according to ISO 639-1 & ISO 3166-1, respectively
LANG_NAME                   "English"                 // language name
LANG_AUTHOR                 "Alexandre Martins"       // translation author
LANG_LASTUPDATE             "2019-01-11"              // date format: yyyy-mm-dd
LANG_COMPATIBILITY          "0.5.0"                   // required engine version

// Colors
COLOR_TITLE                 "ff8800"
COLOR_HIGHLIGHT             "ffee11"
COLOR_HUD                   "ffff00"
COLOR_HUDDANGER             "ff0000"

// ...

// Options
OPTIONS_TITLE               "<color=$COLOR_TITLE>OPTIONS</color>"
OPTIONS_YES                 "YES"
OPTIONS_NO                  "NO"
OPTIONS_GRAPHICS            "GRAPHICS"
OPTIONS_FULLSCREEN          "Fullscreen"
OPTIONS_RESOLUTION          "Screen size"
OPTIONS_RESOLUTION_OPT1     "1X"
OPTIONS_RESOLUTION_OPT2     "2X"
OPTIONS_RESOLUTION_OPT3     "3X"
OPTIONS_RESOLUTION_OPT4     "4X"

// ... the file goes on...

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_LASTUPDATE             "2019-11-01"              // date format: yyyy-mm-dd
LANG_COMPATIBILITY          "0.5.0"                   // required engine version

// Colors
COLOR_TITLE                 "ff8800"
COLOR_HIGHLIGHT             "ffee11"
COLOR_HUD                   "ffff00"
COLOR_HUDDANGER             "ff0000"

// ...

// Options
OPTIONS_TITLE               "<color=$COLOR_TITLE>CONFIGURAÇÕES</color>"
OPTIONS_YES                 "SIM"
OPTIONS_NO                  "NÃO"
OPTIONS_GRAPHICS            "GRÁFICOS"
OPTIONS_FULLSCREEN          "Tela cheia"
OPTIONS_RESOLUTION          "Tamanho"
OPTIONS_RESOLUTION_OPT1     "1X"
OPTIONS_RESOLUTION_OPT2     "2X"
OPTIONS_RESOLUTION_OPT3     "3X"
OPTIONS_RESOLUTION_OPT4     "4X"

// ... the file goes on...

As you can easily notice, only the values of each key/value pair have been translated.

Special features

Constants

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.

Comments

Lines starting with // are comments. They are ignored by the game engine, but can be used to convey meaningful information to humans.

Special characters

You may include special characters in your messages.

Character Effect
\n New line
\" Double quote
\\ Backslash

Color tags

Text written inside a <color=RGB_HEX_CODE> ... </color> tag will be colored when displayed to the user. RGB_HEX_CODE is the hexadecimal RGB code of the color you want to get (for example, ff0000 is red - see Colors for more details). You don't really need to know the fancy details, but it's good to know that this feature exists.

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:

The message displayed in the game

Adding new glyphs

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 describe in detail how to add new fonts to the game and how to configure them to be used with your translation (multilingual support).

Game menu in Korean