ldoc

• Index

Contents

• Concepts
• Commands
• Events
• Remote Interface

Modules

• Core
• Types
• Concepts
• Cache
• Data
• Entity
• EventManagerLite
• Force
• Gui
• Locale
• Player
• PluginManagerLite
• Prototype
• Remote
• Setting
• Stacktrace
• Surface
• Train
• Wube
• Array
• Class
• Coding
• Color
• Compare
• Debug
• Error
• Filter
• Iter
• Lambda
• LocalisedString
• Lock
• Log
• Logic
• Math
• Meta
• Polygon
• Replicate
• Set
• String
• Table
• Time
• Tool
• Vector
• Verificate
• Version
• remotes
• snippet
• Babelfish

Source

• Introduction

Module Babelfish

Localised string search for mods.

Babelfish is a caching translator for prototype localisations. It automatically detects changes in localisation and updates the translation in the background. 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 is only translated once, so even in Multiplayer the process is instant for most players.

While translation is running a small status indicator in the upper right corner informs each user of the approximate total progress. However there is no such progress information on the API, as the Babelfish uses a SearchTypes priorization system in which i.e. "item_name" may already be completely translated despite the indicator showing a low number like "10%".

Module Status: Experimental.

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.

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 translation status changes.

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.

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 for the syntax). 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 priority order in which translation occurs.

For use with Babelfish.translate_prototype_name you can also activate each _description type. However as most prototypes do not have a description this is discouraged.

To minimize save, load and translation times you should only activate the bare minimum types you need.

"item_name"
"fluid_name"
"recipe_name"
"technology_name"
"equipment_name"
"tile_name"
"entity_name"
"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"

Usage:

LuaGuiElement.add{type = "sprite-button", sprite = "er:babelfish-icon-default"}

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 search may also appear slow if many SearchTypes are activated because it searches them all at once. The sidepanel dynamically shows in red/green which SearchTypes are currently fully translated.

See also: HowToActivateBabelfish.

dump

/babelfish dump Prints internal statistics to the attached terminal. This is meant for library authors and is not useful to players or mod authors.

Events

on_babelfish_translation_state_changed

Called when SearchType translation status changes.

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.

See also: Data-Lifecycle "4. control init".

Fields:

• player_index NaturalNumber

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.

Search Behavior:

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.

As in vanilla, searching is done only on names, not descriptions. And unlocalised names will be found as "Unknown Key:". But there are some sublte intentional differences to vanilla behavior:

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 search result includes names of all matching prototypes including hidden items, void recipes, explosion entities and other garbage.
3. Babelfish understands some unicode whitespace (vanilla does not).

Mod Settings:

Some aspects of the search, such as "fuzzy" mode are controlled directly by each user via mod-settings so you don't have to worry about those.

Performance Tips:

1. Babelfish searches are highly optimized, but in large modpacks they can still take a few milliseconds. When called directly from an on_gui_text_changed event handler this can cause noticible lag-spikes due to the high frequency with which that even occurs while a player is typing. A better solution is to impose a delay after the last keypress or to use an on_tick based polling solution. It is recommended to search only once per second.

2. Babelfish does not impose a minimum word length. The EmptyString will match everything. It is recommended to impose a minimum length of two characters on word, or use the limit option to reduce the size of the returned table.

Parameters:

• pindex NaturalNumber A LuaPlayer.index.
• types string or DenseArray One or more SearchTypes.
• word string The user input.
• options (table)
  • limit Integer Search will return at most this many names. This may result in some of the returned sub-tables being empty. (default inf)

Returns:

1. boolean or nil The status code.

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

   false means: Babelfish is still translating some or all of the requested SearchTypes. An incomplete best-effort search result is returned. You can use that partial result or try again later. If you chose to inform the player you can use the LocalisedString {'babelfish.translation-in-progress'} or a custom message.

   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:

• pindex NaturalNumber A LuaPlayer.index.
• type string A SearchType.
• name string A prototype name.

Returns:

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