[MOD][i18n] Internationalization - easy localization for mods - update 0.21.x+

[Rinart73]

Originally this mod was developed to show devs that we really need built-in 'getGameLanguage()' function. Also I just wanted to know if it's even possible. Thanks to the devs since game version 0.16.5, there is a 'getCurrentLanguage()' function on client-side. Now the main purpose of this mod is to help modders to easily provide localization files for their mods.

 

GitHub

 

Doesn't need to be installed on server.

Version 1.1.0 works with Avorion 0.21.x+.

 

Making a few small changes in structure of your mod and adding just one line of code, you can easilly provide localization for your mod!

 

Installation

1. Unpack mod archive in your Avorion folder, not in data folder

2. Open "data/scripts/lib/stringutility.lua" and add following code to the bottom of the file:

if not pcall(require, "mods/i18n/scripts/lib/stringutility") then eprint("[ERROR][i18n]: failed to extend stringutility.lua!") end --MOD: i18n

 

Uninstallation

It is safe to uninstall, this mod can't corrupt your galaxy. Just remove the line you added during installation and "i18n" folder from "mods".

 

For users

There is a config file in "mods/i18n/config" folder that has 'SecondaryLanguages' option. There you can specify your secondary languages, i18n will try to load localization files for them if some mod doesn't have translation files for your main language. Also, first language in this array will be used as language for the server side (if you launched server in console).

 

How to adjust your mod

1. First of all, you need to create a folder for your mod localization files - "Avorion/mods/YourModName/localization".

 

2. Create localization files: "de.lua" for Deutsch, "ru.lua" for Russian, "zh-hk.lua" for Hong Kong Chinese e.t.c

These files should have following structure:

return {
  ["This is how it works"] = "So funktioniert es",
  ["i18n /* Internationalization */"] = "Internationalisierung"
}

 

There is no need to create files for languages that you don't have translation yet.

 

Also, if your native language is not english (you're writing a mod in Russian for example), you can easilly switch places for phrases and create "en.lua":

return {
  ["При наличии необходимых файлов это работает и в обратную сторону"] = "If you have the necessary files, this also works in the opposite direction"
}

 

3. Now, just require "stringutility" and register your mod once in every file that you need to localize:

require ("stringutility")
-- some code
if i18n then i18n.registerMod("YourModName") end

 

4. Write your mod as usual, any "YourPhrase"%_t  will be shown as translated from now on.

 

API

 

• function number [, string] i18n.registerMod(string modname [, custompath]) - Registers mod and loads localization from mod folder.
  Arguments
  modname - The name of your mod folder.
  custompath - Optional argument, in case you want to load translation from different folder. Path should end with slash "/".
  Returns
  0 - everything is ok
  1 - there was an error while loading i18n mod
  2 - this mod was already registered
  3 - there was an error while loading localization. This probably means that you have errors in your localization file syntax. There are also a second return value provided that contains an error text.
  4 - translation file wasn't found.
  
• function table i18n.getMods()
  Returns the list of all mods that tried or successfully registered in i18n.
  

 

 

Explanation

 

 

Mod overrides the default interop function which is used to translate things. And it does that only if at least one mod was registered, so there is a minimum performance impact.

All loaded strings are stored together and can override each other, but you can use /* comments */ in your strings to make them unique.

 

 

 

Changelog

 

 

1.1.0

• Changed: 'i18n.registerMod' now first return value can be '4' which means that translation file wasn't found. Return code '3' now stands for all other file errors.
  
• Changed: 'i18n.registerMod' now accepts an optional argument 'custompath' in case you want to load translation from different folder. Path should end with slash "/".
  
• Improved: Updated for Avorion 0.21.4
  

1.0.0

• Added: Added new API function 'i18n.getMods' - returns the list of all mods that tried or successfully registered in i18n
  
• Added: Config - new option 'secondaryLanguages' - mod will try to load translation files for specified languages if it will fail to load for language, determined by 'getCurrentLanguage()'. Also, first language in this array will be used as server language
  
• Improved: Mod updated to Avorion 0.16.5+ - using 'getCurrentLanguage' function now for client-side
  
• Improved: Function 'i18n.registerMod' now returns various error codes that will help to determine the source of a problem
  
• Removed: Config - options 'langCode' and 'detectMode'
  
• Removed: API functions 'i18n.detectLanguage' and 'i18n.getLanguage' were removed. Use native function 'getCurrentLanguage' instead
  

0.0.4

• Fixed: Clientlog will now calculate correct timestamp to compare with old one
  
• Improved: Clientlog performance - regex is now fast
  
• Changed: Due to the improvements, default detect mode was changed to "full" (which uses clientlog)
  

0.0.3

• Initial release
  

 

 

Credits

Thanks to Dirtyredz for coding hints and new mod structure.

 

Download

Second file - the mod itself. First file - mod example for modders.

i18n-example-1.0.0-0.16.5.zip

i18n-1.1.0-0.21.4.zip

[Rinart73]

New version - 0.0.4:

• Fixed: Clientlog will now calculate correct timestamp to compare with old one
  
• Improved: Clientlog performance - regex is fast now
  
• Changed: Due to the improvements, default detect mode was changed to "full" (which uses clientlog)
  

[Hammelpilaw]

Awesome mod, just starting to implement support for it in my own mods and the modpack of Galaxy Gamers server.

[Rinart73]

Awesome mod, just starting to implement support for it in my own mods and the modpack of Galaxy Gamers server.

Thanks for using it :) Devs noticed this mod too and promised to add built-in getCurrentLanguage function in the next patch. As soon as it will be released, I will add it to the mod.

[Rinart73]

Mod was updated to 0.16.5+ with new features and no more predictions. So it's a release now - 1.0.0

• Added: Added new API function 'i18n.getMods' - returns the list of all mods that tried or successfully registered in i18n
  
• Added: Config - new option 'secondaryLanguages' - mod will try to load translation files for specified languages if it will fail to load for language, determined by 'getCurrentLanguage()'. Also, first language in this array will be used as server language
  
• Improved: Mod updated to Avorion 0.16.5+ - using 'getCurrentLanguage' function now for client-side
  
• Improved: Function 'i18n.registerMod' now returns various error codes that will help to determine the source of a problem
  
• Removed: Config - options 'langCode' and 'detectMode'
  
• Removed: API functions 'i18n.detectLanguage' and 'i18n.getLanguage' were removed. Use native function 'getCurrentLanguage' instead
  

 

I'm a slowpoke, I know :)

[Shrooblord]

Omg what a quality mod. I love you for this. I'll have to think about Localisation from now on...... ;)

[Rinart73]

Shrooblord, thank you  :) If you have any suggestions I will be glad to discuss them.

[Rinart73]

1.1.0 is out!

• Changed: 'i18n.registerMod' now first return value can be '4' which means that translation file wasn't found. Return code '3' now stands for all other file errors.
  
• Changed: 'i18n.registerMod' now accepts an optional argument 'custompath' in case you want to load translation from different folder. Path should end with slash "/".
  
• Improved: Updated for Avorion 0.21.4