Lua Script API: Language Translation

About

Languages are a system of communication that consists of speech, manual (signed), or written symbols. In version 1.0 pre-release of Psych Engine, it added the support for languages to make more accessible to people who don't natively speak English. It uses a language localization file or a lang file to translate words and phrases to different languages without doing it hard-coded.

Setting up

Initially make a lang file that is relative to: assets/shared/data or mods/data. You can name this file anything you want but I'd recommend using the language code format for organization. For instance: en-US for english in USA; en-CA for english in Cananda; and es for spanish. It's your choice if you want to use this format or not.

Translating

The first line of the lang file is the title of the given language, let's say as an example the language is LOLCAT. So basically the title will be: LOLCAT (US), bear in mind that the parenthesis is the country name abbreviated. If you want to override a pre-existing lang file it should have the same title name.

Example:

LOLCAT (US)

Below the title is the main content of the lang file, containing a translatable keys which are special keys that translate word or phrases in a given language. The syntax for the translatable key starts with the title for the key to inherit followed by a colon character :, for example: title_key:. With the given word or phrase for the translatable key to inherit to, for example: "BLASH BLAH BLAJ".

Another thing you can do is insert values to the translatable key's content. It uses a translatable key index to insert any values, the index always starts at 1. It should be always be inclosed with curly-braces {}. This useful if you want to use constantly updating values that change overtime for some reason. For examples: "content {1} content {2}".

Note

If both or more lang files with the same file name exists currently. It will override it each-others translatable key's content that they contain. Mostly the lang files inside the mods folder that will override, The overriding depends on what mod priority level is in.

Syntaxes: (Reference)

title_key: "content"

title_key: "content {1} content {2}"

Example:

LOLCAT (US)

// Custom Stuff
timer_text: "TIM LEFT"
timer_format_text: "MINIT: {1} - SECOND: {2} - MILLISECONDZ: {3}"

There are some pre-existing translatable keys are hard-coded in Psych Engine to modify the text and sprite images of the Pause Menus, Ratings, Achievements, and so on. I won't be listing every translatable keys, but there is a lang file template you can download, just click here.

---

Language Translation Functions

getFileTranslation(key:String)

Gets a translatable key's phrase from a language localization file, lang file. If the translatable key is isn't present inside the file, it returns the key argument given to the function.

• key - The translatable key to get from the given language localization file.

Examples:

LOLCAT (US)

// Gameplay
score_text: "SKOR: {1} | MISEZ: {2} | ACCURACY: {3}"
score_text_instakill: "SKOR: {1} | ACCURACY: {2}"
botplay: "CHEATIN MODE"

function onCreate()
     debugPrint(getFileTranslation('botplay')) --> "CHEATIN MODE"
end

getTranslationPhrase(key:String, ?defaultPhrase:String, ?values:Array = null)

Gets a translatable key's phrase from a language localization file, lang file. It includes a default phrase, if there is non-existing translatable key. Along with a translatable key index for inserting content for updating values.

• key - The translatable key to get from the given language localization file.
• defaultPhrase - An optional parameter, The default phrase to inherit if there is non-existing translatable key.
• values - An optional parameter, The values to insert in each translatable key index; follows a numerical order.

Examples:

LOLCAT (US)

// Gameplay
score_text: "SKOR: {1} | MISEZ: {2} | RATEEZ: {3}"
score_text_instakill: "SKOR: {1} | RATEEZ: {2}"
botplay: "CHEATIN MODE"

function onUpdateScore()
     local score_textPhrase = 'Score: {1} | Misses: {2} | Rating: {3}'
     local score_textValues = {score, misses, string.format('%.2f', math.floor(rating * 100))}
     local score_text = getTranslationPhrase('score_text', score_textPhrase, score_textValues)
     debugPrint(score_text) --> "SKOR: 0 | MISEZ: 0 | Rating: ?"
end