Skip to content
ArchmageDocs

Archmage.I18n

Holds the localized texts of several languages and looks up a text in a language, falling back to a default language.

Inherits: RefCounted

The texts of each language come from an l10n file, a JSON object that maps each l10n key to its text, such as l10n.json for the fallback language and l10n.fr.json for French. An l10n field of a generated config holds the l10n key.

var i18n := Archmage.I18n.new("en")
var err := i18n.merge_l10n_file("res://configs/l10n.json", "en")
if err == OK:
    err = i18n.merge_l10n_file("res://configs/l10n.fr.json", "fr")
if err != OK:
    push_error(i18n.get_error_message())
var title := i18n.text(atlas.game_cfg.title, "fr")

merge_l10n_file_async() reads and parses the file without blocking the main thread:

var err := await i18n.merge_l10n_file_async("res://configs/l10n.json", "en")

A language is identified by the string passed to the methods, such as "fr"; this class does not interpret it.

Constructor

Section titled “Constructor”

new()

Section titled “new()”
Archmage.I18n.new(fallback_language: String)

Methods

Section titled “Methods”

get_fallback()

Section titled “get_fallback()”
func get_fallback() -> String

Returns the fallback language.

get_all_texts()

Section titled “get_all_texts()”
func get_all_texts() -> Dictionary[String, Dictionary]

Returns the texts of all languages: a Dictionary that maps each language to a Dictionary that maps each l10n key to its text. Changes to the result change later lookups.

merge_texts()

Section titled “merge_texts()”
func merge_texts(texts: Dictionary, lang: String) -> void

Adds the texts of texts, which maps each l10n key to its text, to the language lang. A text replaces the earlier text of the same key.

merge_l10n_data()

Section titled “merge_l10n_data()”
func merge_l10n_data(data: PackedByteArray, lang: String) -> Error

Parses data, the UTF-8 text of an l10n file, and merges its texts into the language lang with merge_texts(). A null text is merged as an empty string, and a null file merges nothing. Returns OK, or ERR_PARSE_ERROR when the data is not a JSON object of strings; get_error_message() then returns the message, and no text is merged.

merge_l10n_file()

Section titled “merge_l10n_file()”
func merge_l10n_file(path: String, lang: String, fs: Archmage.FS = null) -> Error

Reads the l10n file at path from fs, or with Archmage.FileAccessFS when fs is null, and merges it as merge_l10n_data() does. Returns OK, the error code of the file system when the file cannot be read, or ERR_PARSE_ERROR; get_error_message() then returns the message.

merge_l10n_file_async()

Section titled “merge_l10n_file_async()”
func merge_l10n_file_async(path: String, lang: String, fs: Archmage.FS = null) -> Error

Merges the l10n file at path as merge_l10n_file() does, without blocking the main thread, and returns the same codes. Call it on the main thread with await.

A thread of the WorkerThreadPool reads and parses the file, and the main thread merges the texts. Without thread support, as in a Web export without threads, the file is read and parsed on the main thread.

get_error_message()

Section titled “get_error_message()”
func get_error_message() -> String

Returns the message of the last failed merge_l10n_data(), merge_l10n_file() or merge_l10n_file_async(), or an empty string when it succeeded.

get_text()

Section titled “get_text()”
func get_text(key: String, lang: String) -> Variant

Returns the text of key in the language lang, or in the fallback language when lang has none. Returns null when neither language has the key.

text()

Section titled “text()”
func text(key: String, lang: String) -> String

Returns the text of key in the language lang, or in the fallback language when lang has none, or key itself when neither language has it. Use get_text() to detect a missing text.