Skip to main content

Localization

Defining phrases​

Localization of modules are built around what we call phrases. Each phrase has a globally unique lisp-case name and are built from merging all lang.toml files in the repositories subscribed to by the user.

The lang.toml consists of tables of phrases containing key-value pairs of ISO 639‑1 language codes and the respective translations in that locale, you can see an example below.

MyRepo/lang.toml
[good-morning]
en = "Good morning"
de = "Guten Morgen"
zh = "早上好"

[good-night]
en = "Good night"
de = "Gute Nacht"
zh = "晚安"

If the user's language is not present for a phrase after merging of all the tables, we first look for an English translation and if not present the first defined language for the phrase.

Machine translation​

All lang.toml files will be automatically translated using our machine-learning backend unless opted out. In order to give the system more context, we allow a special entry called context. The context should be given an example sentence in English or the first defined language where the word is replaced by {}. You can also set it to ! to disable machine translation.

To demonstrate the use case of this parameter, consider the French word Bleu which can mean bruise, blue, rookie and overall.

MyRepo/Bleu.toml
[bruise]
fr = "bleu"


# Machine generated:
en = "Blue"
de = "Blau"
es = "Azul"
ko = "푸른"
ja = "青い"
zh-cn = "蓝色的"
zh-tw = "藍色的"
ru = "Синий"
pl = "Niebieski"
pt = "Azul"
tr = "Mavi"
da = "Blå"
nl = "Blauw"
fi = "Sininen"
sv = "Blå"
no = "Blå"
el = "Μπλε"
hu = "Kék"
it = "Blu"
cs = "Modrý"
ro = "Albastru"

Zero-overhead replacement​

Localization is a builtin part of our text renderer which allows you to localize phrases with practically zero overhead. Any user-facing text rendered by the following funtions will be automatically checked for any phrases present:

  • Engine.Info
  • Engine.Warn
  • Engine.Error
  • Engine.DisplayMessage
  • Text.Calc, unless disabled using Text.NOLOCAL
  • CommandBuffer.Text2D, unless disabled using Text.NOLOCAL
  • CommandBuffer.Text3D, unless disabled using Text.NOLOCAL

Phrases are escaped using two curly brackets around the phrase name ({{phrase-name}}) and any phrase with no entry in the table will be ignored.

Here's an example using our previous lang.toml example.

MyFriendsRepo/index.ts
Event.OnRender((gfx) => {
    gfx.text2D(vec2(300, 100), 0, "{{good-morning}} {{invalid}}!", 32);
});

Manual translation​

Phrases can also be manually translated using the function Phrase.Translate which replaces all escaped phrases similar to the rendering primitives, or using the table Phrase.Table using the phrase name as the key.

-- Global table with all known phrases.
--
table  Phrase.Table

-- Translates each known phrase in the text according to user locale.
--
string Phrase.Translate(string input)