dictionary module

An easy-to-use dictionary system for storing localised string translations.

See also

Usage

local dictionary = require("__flib__.dictionary")

RawDictionary methods

RawDictionary:add(internal, translation) Add a new translation to this dictionary.
new(name[, keep_untranslated][, initial_contents]) Create a new RawDictionary.

Functions

init() Initialize the module's script data table.
load() Set up the module's local references.
translate(player) Request all dictionaries for the given player.
check_skipped() Check for a "skipped" translation and re-request it after three seconds.
process_translation(event_data) Process a returned translation batch, then request the next batch or return the finished dictionaries.
cancel_translation(player_index) Cancel the translation of the player's dictionaries if they are the currently translating player.
set_use_local_storage(value) Set whether or not the module is using local storage mode.

Concepts

RawDictionary A "raw" dictionary containing the actual Concepts.LocalisedStrings for translation.
InternalString The "internal" representation of the translation.
TranslatedString The translated result of a Concepts.LocalisedString for a specific language, or the InternalString if include_failed_translations was enabled when creating the RawDictionary.
DictionaryContents The contents of a translated dictionary.
TranslationFinishedOutput The results of a translated language.

RawDictionary methods

# RawDictionary:add(internal, translation)

Add a new translation to this dictionary.

This method must not be called after control stage initialization and migration. Doing so will result in different languages having different sets of data.

Parameters:
# new(name[, keep_untranslated][, initial_contents])

Create a new RawDictionary.

Parameters:
  • name : (string) The name of the dictionary.
  • keep_untranslated : (boolean) If true, translations that "failed" (begin with Unknown key: will be added to the dictionary with their internal name as their translated name. (optional)
  • initial_contents : (table) The intial contents of the dictionary. This is a table of InternalString -> LocalisedString. (optional)
Returns:

Functions

# init()

Initialize the module's script data table.

Must be called at the beginning of on_init for initial setup, and at the beginning of on_configuration_changed to reset all ongoing translations.

# load()

Set up the module's local references.

Must be called at the beginning of on_load.

If using dictionary.set_use_local_storage, your dictionaries must be re-generated after this function is called.

# translate(player)

Request all dictionaries for the given player.

The dictionary system stores dictionaries by language, not by player. Thus, if this player's language has already been translated, the module will simply return the already existing dictionaries instead of translating them again.

If you wish to re-translate dictionaries, call dictionary.init and call this function for all online players.

The player must be connected to the game in order to call this function. Calling this function on a disconnected player will throw an error.

Parameters:
# check_skipped()

Check for a "skipped" translation and re-request it after three seconds.

Must be called during on_tick.

This is to handle a very specific edge-case where translations that are requested on the same tick that a game is saved will not be returned when that save is loaded.

# process_translation(event_data)

Process a returned translation batch, then request the next batch or return the finished dictionaries.

Must be called during on_string_translated.

Parameters:
  • event_data : (OnStringTranslatedEventData)
Returns:
# cancel_translation(player_index)

Cancel the translation of the player's dictionaries if they are the currently translating player.

If multiple players are waiting on these dictionaries, the translation duties will be handed off to the next player in the list.

Must be called during on_player_left_game.

Parameters:
# set_use_local_storage(value)

Set whether or not the module is using local storage mode.

Must be called in the root scope of your mod if you wish to use local storage.

Using local storage is a technique to reduce the amount of script data that the module saves in the global table. If you enable this, you must re-build all of your dictionaries during on_load, but after calling dictionary.load. Failure to do so will result in a desync.

Only use this function if you understood the above explanation and if you are familiar with how desyncs can occur. Use at your own risk!

Parameters:
  • value : (boolean) Whether or not to use local storage.
Usage:
local dictionary = require("__flib__.dictionary")
dictionary.set_use_local_storage(true)

Concepts

# RawDictionary

A "raw" dictionary containing the actual Concepts.LocalisedStrings for translation.

This object contains a metatable giving access to all of the methods in the RawDictionary object methods section.

This object must not be stored in the global table. Doing so will result in a desync if the game is saved and loaded and you attempt to call methods on it.

Usage:
local MyDictionary = dictionary.new("my_dictionary")
MyDictionary:add("iron-ore", {"item-name.iron-ore"})
# InternalString

The "internal" representation of the translation.

This is a consistent, language-agnostic identifier that corresponds to the translation.

# TranslatedString

The translated result of a Concepts.LocalisedString for a specific language, or the InternalString if include_failed_translations was enabled when creating the RawDictionary.

# DictionaryContents

The contents of a translated dictionary.

A table of InternalString -> TranslatedString.

# TranslationFinishedOutput

The results of a translated language.

  • language : (string) The language that was translated.
  • dictionaries : (table) The resulting dictionaries, in the format of dictionary_name -> DictionaryContents.
  • players : (array[number]) The players who were waiting for this language to complete translation.