Vendetta/babel

Babel is a lightweight library that helps plugins provide easy dictionary-based translation to their interfaces
If a mod provides a table of translations for a provided language and references each line by key, it can provide a language selection for the user. If the requested language module is not available for the given plugin, or if babel is not present, it falls back to the default language contained within the plugin. In this way, Babel is an optional feature for users, but a powerful benefit to multi-lingual players.

You can download this application at the following locations

NexusMods	v1.1.1
VOUPR	v1.1.1
Github	v1.2.0 (in-development)

For users

Babel can be installed like any LME plugin. By default, it internally only supports EN, ES, FR, and PT languages. These languages can be easily expanded with additional addons. Plugins must also support the language being used, but this can likewise be expanded easily.

Once added to your game, verify it is enabled. The first time it is ever run, it will try to default to the user's selected game locale, or use english. To select another language to use in Babel and all supported plugins, open the configuration interface with the command /babel, or by using the config option in your LME manager; the language options will be visible in a drop-down.

For modders

Using Babel

Babel provides a small API that provides simplified table translation to any plugin, and only minimal setup is required in a plugin's code to access this functionality. While Babel **could** be listed as a hard dependency in a plugin's declaration file, the documentation on this page will assume Babel is being listed as an **optional** feature. The actual API is listed at the bottom of this page.

• First, construct the placeholder functions and requirements to use if Babel is not yet loaded or is not on the user's system:

local babel, lang_key
local bstr = function(id, val)
	return val
end

• Next, add the function to update the local babel values when Babel is loaded:

local babel_func = function()
	babel = lib.get_class("babel", "0")
	lang_key = babel.register(<your plugins path> .. "lang/", {'en', 'es', 'fr', 'pt'}) --<or whatever list of languages you directly support>
	
	bstr = function(id, val)
		return babel.fetch(lang_key, id, val)
	end
	
	--<optional, but add this to your public-facing LME class table to let others add new languages to your plugin>
	public.add_translation = function(path, lang_code)
		babel.add_new_lang(lang_key, path, lang_code)
	end
	
	--or whatever you do to update your class table. This will re-trigger it, but now bstr() will pass translated strings
	update_class()
end

--actually add this to the queue for when Babel is loaded. Will load immediately if Babel loaded already! Will NEVER load if Babel is not loaded.
lib.require({{name = "babel", version = "0"}}, babel_func)

Once those two are set up, you simply call bstr(index, string) when accessing any and all strings (or at least the parts you want translated). Since bstr() will always pass the default value until Babel is loaded, make sure your plugin loads strings or generates interface elements only after Babel has been given the chance to load, or add additional functionality to update interfaces post-creation.

Babel Terminology

Internally, Babel uses a few terms when referencing parts of translations. These aren't specifically important to know or use Babel, but referencing them as such can help improve readability when sharing code.

Shelf	A shelf is an individual plugin's 'space' where all translations are stored.
Book	A book is a single translation provided for a shelf. For instance, one 'book' would provide 'english' as a language for a particular shelf.
Tower	The tower is the container of all individual shelves.

Language table

Language tables are INI files, and should be named as <language_code>.ini. For instance, per the ISO 639 two-letter set-1 standard, a table that represents the english language would be 'en', so 'en.ini', where spanish would be 'es', so 'es.ini'. All primary supported languages should be put in the same folder and loaded when using the register function. While standard languages should follow the ISO 639 standard for consistancy, non-standard languages (such as 'pirate speak', 'klingon', 'elvish', or some other unusual language) are up to the community to support.

[babel]
0=<language long name>
flag=<path/to/language's/flag.png>
1=translated line 1
2=translated line 2
...

• Key 0 is used by Babel to display the language that this file represents in the primary interface - you only need to include this if you are adding additional language support to Babel, not adding a translation to your own plugin.
• flag is likewise an optional key only used for languages being added to Babel itself, and is used for the visual language selector. If a flag option is not present, a placeholder is used instead.
• All numemric key indexes contain actual translated lines, and should be a complete numeric series from 1 till the last entry. While Babel will not fail to obtain numbers that are not in a series, it will prevent pre-caching for users who select that option.

Modding usage (as a hybrid plugin)

Babel, as documented in the example above, should be easily converted to work in a hybrid plugin. All elements that require an LME to be present can be stuck inside the standard check for LME existence. If they are never run, then the function 'bstr' would never be updated to do anything except pass along the default entry. The example file provided here can be a starting point for developing hybrid plugins with Babel support.

Modding API

Function	Input arguments	Output values	Description
add_translation	babel.add_translation(string file_path, string lang_code)	returns nil	Registers a new language to be used with Babel's interface and language selector.
register_custom_lang	babel.register_custom_lang(string file_path, string lang_code)	returns nil	v1.0.x name of the 'add_translation' function. This keyword will be deprecated eventually.
add_new_lang	babel.add_new_lang(*type shelf_reference, string file_path, string language_code	return boolean status	Registers an additional translation 'book' to an existing 'shelf', providing new translations. Usually used as a way for mods using Babel to allow external additions to their supported languages
register	babel.register(string folder_path, table language_code_list)	return *type shelf_reference	Creates a new shelf and preloads it with translation 'books' provided by the language code list.
fetch	babel.fetch(*type shelf_reference, number string_id, string default_text)	return string output_text	Looks up and provides the translation for the provided line number.
get_user_lang	babel.get_user_lang (nil)	return string user_locale	Returns the language code the user has selected. If no locale is set by the user, the game locale will be passed.
get_langs_on_shelf	babel.get_langs_on_shelf (*type shelf_reference)	return table existing_language_codes	Returns the language codes supported by the provided shelf reference. If the shelf reference is nil, Babel's own language support is provided instead.
get_lang_flag	babel.get_lang_flag (string lang_code)	return string file_path	Returns a country or language flag image file associated with the provided language, if one exists.
get_config	babel.get_config (string option_to_retrieve)	return string option_current_value	Gets the current configuration setting for the specified value
set_config	babel.set_config (string option_to_modify, string new_value)	return nil	Writes the new configuration value. Some changes may require the interface to reload.