Module Babelfish

Localised string search for mods.

Babelfish is a caching translator for standard prototype localisations. When it detects changes in the locale it starts a background task to translate all prototype names and descriptions. In Singleplayer this process happens during the loading screen and is invisible to the player. In Multiplayer translation is done gradually in on_tick to prevent network congestion. Each language only needs to be translated once, so even in Multiplayer the process is instant for most users.

While translation is running a small status indicator in the upper right corner informs each user of the approximate progress. However there is no such progress information on the API as the real progress is much more complex and prioritized SearchTypes like "item_name" may already be completely translated despite the indicator showing i.e. "10%".

Module Status: Polishing.

Concepts

HowToActivateBabelfish Babelfish must be activated before use by calling the global function erlib_enable_plugin in settings.lua.
SearchType What to search.
Sprites Babelfish built-in sprites.

Remote Interface

RemoteInterfaceName The remote interface is named "babelfish".
can_translate(pindex, types) Reports if all of the given types are completely translated yet.
find_prototype_names(pindex, types, word, options) Given a user input, finds prototype names.
translate_prototype_name(pindex, type, name) Retrieves the localised name or description of a single prototype.

Commands

update /babelfish update Updates Singleplayer language when detection failed.
reset /babelfish reset Deletes all translations and starts from scratch.
demo /babelfish demo Opens a rudimentary demonstration GUI.
dump /babelfish dump Prints internal statistics to the attached terminal.

Events

on_babelfish_translation_state_changed Called when SearchType availability changes.


Concepts

HowToActivateBabelfish

Babelfish must be activated before use by calling the global function erlib_enable_plugin in settings.lua. You must also activate at at least one SearchType by passing an array of search types (see the code box below). Once a search type has been activated by any mod it can not be deactivated again. You can call erlib_enable_plugin repeatedly to add more search types later.

erlib_enable_plugin('babelfish', {
  search_types = {'item_name', 'fluid_name', 'recipe_name'}
  })

The Demo-Gui must be activated seperately. It should only be activated during development.

erlib_enable_plugin('babelfish-demo')
SearchType

What to search. One of the following strings. This is also the order in which translation occurs. Once translation for a type is complete it can be fully searched, regardless of the translation status of the other types.

Note: In vanilla factorio all search functions search only the name, never the description. As descriptions can be very long and thus slow to translate it is recommended to not activate them.

"item_name"
"fluid_name"
"recipe_name"
"technology_name"
"item_description"
"fluid_description"
"recipe_description"
"technology_description"
"equipment_name"
"equipment_description"
"tile_name"
"tile_description"
"entity_name"
"entity_description"
"virtual_signal_name"
Sprites

Babelfish built-in sprites. Can be used to decorate mod guis. All icons are 256x256 pixels with 4 mip-map levels.

SpritePaths:

 "er:babelfish-icon-default"
 "er:babelfish-icon-green"
 "er:babelfish-icon-red"

Remote Interface

RemoteInterfaceName
The remote interface is named "babelfish".
can_translate(pindex, types)
Reports if all of the given types are completely translated yet.

Uses the same parameters and does the same internal checks as Babelfish.find_prototype_names but does not conduct a search, and only returns the status code.

Parameters:

  • pindex
  • types

Returns:

    boolean or nil The status code.
find_prototype_names(pindex, types, word, options)
Given a user input, finds prototype names. Can search the localised name and description of all common prototypes to deliver a native search experience. Translation is granular per SearchType.

All searches are conducted in lower-case (as far as string.lower works in that language). In the SearchType order given, and in prototype order specific order.

The search result is identical to vanilla search even for unlocalised names and descriptions (i.e. "Unknown Key:").

With some intentional exceptions:
1) If word is an exact prototype name (i.e. "iron-plate") that name will additionally be included in the search result.
2) Babelfish does not filter prototypes. The serch result includes names of all matching prototypes including hidden items, void recipes, etc.
3) Babelfish understands unicode language spaces (vanilla does not).

Parameters:

  • pindex NaturalNumber A LuaPlayer.index.
  • types string or DenseArray One or more SearchTypes.
  • word string The user input. Interpreted according to the users chosen search mode: plaintext, fuzzy or lua pattern (per-player mod setting). For best performance it is recommended to not search for strings shorter than length 2.
  • options (table)
    • limit Integer Search will abort after this many hits and return the (partial) result. (default inf)

Returns:

  1. boolean or nil The status code.

    nil means: The language for that player has not been detected yet. This should hardly ever happen in reality. Just try again a second later.

    false means: Babelfish is still translating some or all of the requested SearchTypes. A best-effort search result is included but likely to be incomplete. It is recommended to try again after translation is complete.
    You can show {'babelfish.translation-in-progress'} to the player.

    true means: No problems occured.

  2. table or nil The search result. A table mapping each requested SearchType to a set of prototype names.

Usage:

    -- First lets make a shortcut.
    local babelfind = (function(c) return function(...)
      return c('babelfish', 'find_prototype_names', ...)
      end end)(remote.call)
    
    -- For demonstration purposes let's use a player with a German locale.
    local ok, results
      = babelfind(game.player.index, {'item_name', 'recipe_name'}, 'Kupfer')
    if ok then print(serpent.block(results)) end
    
    > {
    >   item_name = {
    >     ["copper-cable"] = true,
    >     ["copper-ore"  ] = true,
    >     ["copper-plate"] = true
    >   },
    >   recipe_name = {
    >     ["copper-cable"] = true,
    >     ["copper-plate"] = true
    >   }
    > }
    
translate_prototype_name(pindex, type, name)
Retrieves the localised name or description of a single prototype.

Parameters:

Returns:

    string or nil The translation, or nil if that entry is not translated yet, or the name is unknown. Empty descriptions will return an empty string. Empty names return the usual "Unknown key:". The result should be used immediately or it may become outdated.

Commands

update
/babelfish update Updates Singleplayer language when detection failed.
reset
/babelfish reset Deletes all translations and starts from scratch. Use only when everything else failed.
demo
/babelfish demo Opens a rudimentary demonstration GUI. Just type in the upper box to start searching. The gui is not optimized so the generation of the result icons is a bit slow for large modpacks. The sidepanel dynamically shows in red/green which SearchTypes are fully translated.

See also: HowToActivateBabelfish.

dump
/babelfish dump Prints internal statistics to the attached terminal.

Events

on_babelfish_translation_state_changed
Called when SearchType availability changes. SearchTypes can become available or unavailable.

Mods that want to dynamically adjust their gui or similar must call can_translate during this event to get the new state. Other mods can safely ignore this event.

Use remotes.events or EventManagerLite.events to get the event id.

Fields:

generated by LDoc 1.4.6 Last updated 2021-07-28 22:23:33