Difference between revisions of "Translation Guide"

From Open Surge Engine Wiki
Jump to: navigation, search
(Created page with '== 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 us…')
 
(Country flags)
 
(51 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Introduction ==
+
== Overview ==
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 [http://notepad-plus.sourceforge.net/ Notepad++]. Once a new .lng file has been put in the languages/ directory, the corresponding new translation will be detected automatically.
+
  
As you'll see in this article, translating the game to other languages is a very straightforward process.
+
=== Introduction ===
 +
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: Notepad, [http://www.vim.org/ Vim], [http://www.emacs.org Emacs], [http://www.pnotepad.org/ Programmer's Notepad], [http://notepad-plus.sourceforge.net/ Notepad++], [http://www.sublimetext.com Sublime Text], among others. You can also use the [[Language Editor]], a graphical tool to open and edit existing language files.
  
== File format ==
+
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.
Once you open a .lng file, you'll see something like that:
+
<pre>
+
# Meta data
+
LANG_LANGUAGE              English
+
LANG_AUTHOR                Alexandre Martins
+
LANG_LASTUPDATE            2009-07-20
+
LANG_COMPATIBILITY          0.1.3
+
  
 +
=== 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).
  
# Colors
+
You need to translate the [https://github.com/alemart/opensurge/blob/master/languages/english.lng updated English language file] (check the link).
COLOR_P1                    0077ff
+
COLOR_P2                    ff7700
+
COLOR_P3                    ff0000
+
COLOR_INPUT                aaaaaa
+
COLOR_SPECIAL              ffff00
+
  
 +
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 Google Translate, nor any other automated translators, to translate the texts. Not even to translate a single text entry!
 +
** Texts are split into different entries. The computer translator will likely not be able to capture the context of things. Its translation is not good enough for our purposes. The meaning of things may be lost!
 +
* Finally, please use the license of the original English translation
  
# Main menu
+
We may accept your translation provided that the project [https://github.com/alemart/opensurge/tree/master/languages 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.
MENU_1PGAME                1P GAME
+
MENU_CUSTOMQUESTS          CUSTOM QUESTS
+
MENU_TUTORIAL              TUTORIAL
+
MENU_LANGUAGE              CHANGE LANGUAGE
+
MENU_CREDITS                CREDITS
+
MENU_EXIT                  EXIT
+
  
 +
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.
  
# and the file goes on...
+
Your help is greatly appreciated!
</pre>
+
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'''. Lines starting with # are comments (meaning that they're ignored by the game engine).
+
  
Now, take a look at the Spanish language file:
+
'''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.
  
<pre>
+
'''Important:''' use UTF-8 encoding (it must be UTF-8 without [http://en.wikipedia.org/wiki/Byte_order_mark BOM]).
# Meta data
+
LANG_LANGUAGE              Español
+
LANG_AUTHOR                Lainz
+
LANG_LASTUPDATE            2009-07-23
+
LANG_COMPATIBILITY          0.1.3
+
  
 +
== How to translate ==
 +
=== File format ===
 +
Once you open a language file, you'll see something like that:
 +
<pre>// ...
  
# Colors
+
// Translation metadata
COLOR_P1                    0077ff
+
LANG_ID                    "en_US"                  // language code & country according to ISO 639-1 & ISO 3166-1, respectively
COLOR_P2                    ff7700
+
LANG_NAME                  "English"                // language name
COLOR_P3                    ff0000
+
LANG_AUTHOR                 "Alexandre Martins"      // translation author
COLOR_INPUT                 aaaaaa
+
LANG_LASTUPDATE            "2019-01-11"              // date format: yyyy-mm-dd
COLOR_SPECIAL              ffff00
+
LANG_COMPATIBILITY          "0.5.0"                  // required engine version
  
 +
// ...
  
# Main menu
+
// Options
MENU_1PGAME                 1P JUEGO
+
OPTIONS_TITLE              "<color=$COLOR_TITLE>OPTIONS</color>"
MENU_CUSTOMQUESTS          PARTIDAS
+
OPTIONS_YES                 "YES"
MENU_TUTORIAL              TUTORIAL
+
OPTIONS_NO                  "NO"
MENU_LANGUAGE              IDIOMAS
+
OPTIONS_GRAPHICS            "GRAPHICS"
MENU_CREDITS                CREDITOS
+
OPTIONS_FULLSCREEN          "Fullscreen"
MENU_EXIT                  SALIR
+
OPTIONS_RESOLUTION          "Screen size"
 +
OPTIONS_RESOLUTION_OPT1    "1X"
 +
OPTIONS_RESOLUTION_OPT2    "2X"
 +
OPTIONS_RESOLUTION_OPT3    "3X"
 +
OPTIONS_RESOLUTION_OPT4    "4X"
  
 +
// ... the file goes on...
 +
</pre>
 +
 +
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:
 +
 +
<pre>// ...
 +
 +
// 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
 +
 +
// ...
 +
 +
// 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"
  
# and the file goes on...
+
// ... the file goes on...
 
</pre>
 
</pre>
  
 
As you can easily notice, '''only the values of each key/value pair have been translated.'''
 
As you can easily notice, '''only the values of each key/value pair have been translated.'''
  
== Special features ==
+
=== Special features ===
=== Constants ===
+
==== Constants ====
Each key/value pair defines a constant. In the examples above, MENU_LANGUAGE stands for ''CHANGE LANGUAGE'' (in English) or ''IDIOMAS'' (in Spanish). You can obtain the corresponding value for the key MENU_LANGUAGE by writing $MENU_LANGUAGE.
+
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.
  
=== Color tags ===
+
==== Comments ====
Text written inside a &lt;color='''RGB_HEX_CODE'''&gt; ... &lt;/color&gt; tag will be colored when displayed to the user. '''RGB_HEX_CODE''' is the hexadecimal RGB code of the color you want to get (so, for example, ff0000 is red). You don't really need to know the fancy details, but it's good to know that this feature exists.
+
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.
 +
{| border="1" cellspacing="0" cellpadding="5"
 +
! style="background-color:#eee" width="20%" | Character
 +
! style="background-color:#eee" width="80%" | Effect
 +
|-
 +
| \n
 +
| New line
 +
|-
 +
| \"
 +
| Double quote
 +
|-
 +
| \\
 +
| Backslash
 +
|}
 +
 
 +
==== Color tags ====
 +
Text written inside a &lt;color='''RGB_HEX_CODE'''&gt; ... &lt;/color&gt; 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:
 
You can also combine color tags with constants. Let's say that you have the following key/value pairs somewhere in your translation file:
  
<pre>
+
<pre style="white-space: pre-wrap">
COLOR_INPUT                 aaaaaa
+
COLOR_TITLE                 "ff8800"
COLOR_SPECIAL              ffff00
+
COLOR_HIGHLIGHT            "ffee11"
TUTORIAL_2_TITLE_2          SPINDASH
+
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!"
TUTORIAL_2_MSG_2            Do you know the <color=$COLOR_SPECIAL>spindash</color> move? Hold <color=$COLOR_INPUT>DOWN</color>, press <color=$COLOR_INPUT>JUMP</color> and then release the <color=$COLOR_INPUT>DOWN</color> button.
+
 
</pre>
 
</pre>
  
 
This is the result:
 
This is the result:
  
[[Image:Tutorialmsg.png|frame|none||||The message displayed in the game]]
+
[[Image:S165.png|frame|none||||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#Multilingual support|Fonts]] describes in detail how to add new fonts to the game and how to configure them for your translation.
 +
 
 +
[[Image:Korean_menu.png|852px|thumb|left|||Game menu in Korean]]
 +
<br clear="all">
 +
 
 +
=== Country flags ===
 +
 
 +
In order to add a country flag to the language setting of the options screen, edit file ''sprites/ui/flag_icons.spr''. Refer to [[Sprites]] for details on .spr files.
 +
 
 +
== Language extensions ==
 +
 
 +
=== Introduction ===
 +
 
 +
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!
 +
 
 +
=== Example ===
 +
 
 +
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
  
== I want to help! ==
+
//
If you want to help the game by translating it to your language, just [http://opensnc.sourceforge.net/home/contact.php send us] your .lng file. Please note that translators must keep their .lng files up to date! The game is still in development and new texts may be included anytime.
+
// EXAMPLE 1
 +
// Replace "Power" by "Coins" in the Heads-Up Display
 +
//
 +
HUD_POWER                  "Coins"
 +
 +
//
 +
// EXAMPLE 2
 +
// Add a new entry to the language file
 +
//
 +
MY_NEW_ENTRY                "My new entry works!!!"
  
See also: [[Job Positions]]
+
[[Category:MODs]]
 +
[[Category:Users]]
 +
[[Category:Cookbooks]]

Latest revision as of 01:18, 26 September 2023

Overview

Introduction

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: Notepad, Vim, Emacs, Programmer's Notepad, Notepad++, Sublime Text, among others. 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)
  • DO NOT use Google Translate, nor any other automated translators, to translate the texts. Not even to translate a single text entry!
    • Texts are split into different entries. The computer translator will likely not be able to capture the context of things. Its translation is not good enough for our purposes. The meaning of things may be lost!
  • 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.

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!

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

// ...

// 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

// ...

// 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 describes in detail how to add new fonts to the game and how to configure them for your translation.

Game menu in Korean


Country flags

In order to add a country flag to the language setting of the options screen, edit file sprites/ui/flag_icons.spr. Refer to Sprites for details on .spr files.

Language extensions

Introduction

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!

Example

Suppose you want to extend the english.lng file (this is the default language file).

  1. Copy the examples below to languages/extends/english.lng
  2. Add or modify entries as in the examples below
  3. Launch the engine and select the English language
//
// EXAMPLE 1
// Replace "Power" by "Coins" in the Heads-Up Display
//
HUD_POWER                   "Coins"

//
// EXAMPLE 2
// Add a new entry to the language file
//
MY_NEW_ENTRY                "My new entry works!!!"