You are not logged in.

A guide to multilingual add-ons

Dear visitor, welcome to Allods Online Forum. If this is your first visit here, please read the Help. It explains in detail how this page works. To use all features of this page, you should consider registering. Please use the registration form, to register here or read more information about the registration process. If you are already registered, please login here.

1

Tuesday, April 25th 2023, 7:14pm

Eksperyment

Beginner

  • "Eksperyment" started this thread

Posts: 12

  • Send private message

A guide to multilingual add-ons

Welcome to the guide about adding multilingual support to add-ons. It happens quite often that at the time of the release of an add-on, the author might have not considered multilingual support. As a result, many add-ons limit the available languages to only English and Russian, skipping others such as French, German, and Turkish, and creating a barrier for potential users who don't speak these languages.

The good news is that you can still add multilingual support to most of such add-ons. With the proper guidance many of such add-ons are very easy to localize. This guide aims to provide you with all the information you need to add multilingual support to most of them.

There are generally two ways to localize add-on:
  • with .txt files
  • with .lua files
How to localize txt files?

This one is fairly easy to add new languages.
To check if it’s the case in our add-on open AddonDesc.(UIAddon).xdb and if you see <textsGroups> it means add-on is translated using txt files.

Example that contains all supported languages localizaton:
<textsGroups>
<Item>
<groupName>rus</groupName>
<texts href="Locales/rus/Locale.(UIRelatedTexts).xdb#xpointer(/UIRelatedTexts)"/>
</Item>
<Item>
<groupName>eng_eu</groupName>
<texts href="Locales/eng_eu/Locale.(UIRelatedTexts).xdb#xpointer(/UIRelatedTexts)"/>
</Item>
<Item>
<groupName>ger</groupName>
<texts href="Locales/ger/Locale.(UIRelatedTexts).xdb#xpointer(/UIRelatedTexts)"/>
</Item>
<Item>
<groupName>fra</groupName>
<texts href="Locales/fra/Locale.(UIRelatedTexts).xdb#xpointer(/UIRelatedTexts)"/>
</Item>
<Item>
<groupName>tr</groupName>
<texts href="Locales/tr/Locale.(UIRelatedTexts).xdb#xpointer(/UIRelatedTexts)"/>
</Item>
</textsGroups>

Let’s explain what it all means, <groupName>rus</groupName> is a name of localization used in-game returned by common.GetLocalization() API function.

Here are all languages and value they return:
  • " rus " - Russian
  • "eng_eu" - English
  • "ger" - German
  • "fra" - French
  • “tr" - Turkish
<texts href="Locales/rus/Locale.(UIRelatedTexts).xdb#xpointer(/UIRelatedTexts)"/>- shows you where are the texts with localization.
If your locale name is missing in <textsGroups> add it there following the example above.

It’s time to move on to folder with localization files, in our example it’s Locales:

This is our example, in this case we want to add German support and as all language folders are symmetrical, all we have to do is copy one of the folders, let’s use “eng_eu” and after copying rename it to “ger”.
Now all that’s left is to translate the text files. Note that all text files must be encoded in UTF-16LE (UCS-2 Little Endian in notepad++) .

How to localize lua files?

This one is a lot more complicated. Unfortunately lua doesn’t work properly with Unicode as it only supports 8-bit strings. Therefore, each language has its own encoding in which its localization strings must be stored:
  • Windows-1251 - Russian and English
  • Windows-1252 - German, French
  • Windows-1254 - Turkish

However you can write unsupported letters in windows-1251 encoded files with their ASCII codes:
French:
é: ASCII code 233
è: ASCII code 232
ê: ASCII code 234
ë: ASCII code 235
à: ASCII code 224
â: ASCII code 226
î: ASCII code 238
ô: ASCII code 244
û: ASCII code 251
German:
ä: ASCII code 228
ö: ASCII code 246
ü: ASCII code 252
ß: ASCII code 223
Turkish:
ş: ASCII code 351
Ş: ASCII code 350
ğ: ASCII code 287
Ğ: ASCII code 286
ı: ASCII code 305
İ: ASCII code 304
ö: ASCII code 246
Ö: ASCII code 214
ü: ASCII code 252
Ü: ASCII code 220
ç: ASCII code 231
Ç: ASCII code 199

Start the search for a file containing localization, usually it’s locales.lua or files located in Locales folder, there aren't any rules for that and texts might be located in code itself and any multilingual support wasn’t taken into account when creating add-on.

This file might look like this:

Global("Locales", {})

function getLocale()
return Locales[common.GetLocalization()] or Locales["eng_eu"]
end

--------------------------------------------------------------------------------
-- Russian
--------------------------------------------------------------------------------
Locales["rus"]={}
Locales["rus"]["red"]="Красный"
Locales["rus"]["green"]="Зелёный"
Locales["rus"]["blue"]="Синий"
Locales["rus"]["zone"]="Ирэне"
--------------------------------------------------------------------------------
-- English
--------------------------------------------------------------------------------
Locales["eng"]={}

And it will be encoded in windows-1251, if you want to add English support you have to add eng_eu texts into the table:

--------------------------------------------------------------------------------
-- Russian
--------------------------------------------------------------------------------
Locales["rus"]={}
Locales["rus"]["red"]="Красный"
Locales["rus"]["green"]="Зелёный"
Locales["rus"]["blue"]="Синий"
Locales["rus"]["zone"]="Ирэне"
--------------------------------------------------------------------------------
-- English
--------------------------------------------------------------------------------
Locales["eng_eu"]={}
Locales["eng_eu"]["red"]="Red"
Locales["eng_eu"]["green"]="Green"
Locales["eng_eu"]["blue"]="Blue"
Locales["eng_eu"]["zone"]="Irene"

Adding English support is that simple! Unfortunately every other language is a lot more work, In this guide I will focus on doing everything in encoding windows-1251.

Let’s try adding French:
--------------------------------------------------------------------------------
-- Russian
--------------------------------------------------------------------------------
Locales["rus"]={}
Locales["rus"]["red"]="Красный"
Locales["rus"]["green"]="Зелёный"
Locales["rus"]["blue"]="Синий"
Locales["rus"]["zone"]="Ирэне"
--------------------------------------------------------------------------------
-- English
--------------------------------------------------------------------------------
Locales["eng_eu"]={}
Locales["eng_eu"]["red"]="Red"
Locales["eng_eu"]["green"]="Green"
Locales["eng_eu"]["blue"]="Blue"
Locales["eng_eu"]["zone"]="Irene"
--------------------------------------------------------------------------------
-- French
--------------------------------------------------------------------------------
Locales["fra"]={}
Locales["fra"]["red"]="Rouge"
Locales["fra"]["green"]="Vert"
Locales["fra"]["blue"]="Bleu"
Locales["fra"]["zone"]="Ir\232ne"

è - is not supported in cp-1251 which means we had to use ASCII code \232, Turkish and German can be localized in same way.

While this guide is quite basic and doesn’t delve into details it should provide condensed knowledge ready to use. I might also release a more in depth guide for developers on alloder.pro at some point in the future.

Hopefully this guide will help make more and more add-ons multilingual and allow them to become accessible to a wider audience.

At the end I have a request, please provide add-on authors with files localized in this way to allow them to integrate new languages fast and easily. Simply find the chosen add-on support topic on alloder.pro and share your translation.

1 user apart from you is browsing this thread:

1 guests

Similar threads

Used tags

add-ons, localization

Rate this thread