Download the PHP package bluepsyduck/factorio-translator without Composer
On this page you can find all versions of the php package bluepsyduck/factorio-translator. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download bluepsyduck/factorio-translator
More information about bluepsyduck/factorio-translator
Files in bluepsyduck/factorio-translator
Package factorio-translator
Short Description A library able to translate localised strings from Factorio, given the locale files.
License GPL-3.0-or-later
Homepage https://github.com/BluePsyduck/factorio-translator
Informations about the package factorio-translator
Factorio Translator Library
The Factorio Translator Library is a library implementing the translator of Factorio in PHP. Given the locale files shipped with the mods it is able to translate the localised strings used by Factorio into any locale provided by the mods.
Features
- Translate any localised string to any locale, providing the locale files of mods.
- Load mods either in their archive format (e.g. downloaded from the Factorio mod portal), or an already extracted directory (as are the core and base mods from Factorio itself).
- Resolve positional parameters
__1__
from the localised strings. - Resolve simple references like
__ITEM__electronic-circuit__
and__ENTITY__iron-ore__
by replacing them with their translated name. - Resolve plural forms like
__plural_for_parameter_1_{1=hour|rest=hours}__
. - Process control references like
__CONTROL__build__
and__ALT_CONTROL__1__build__
by providing an abstract class for implementation. - Process RichText tags like
[item=electronic-circuit]
and[color=red]text[/color]
by providing abstract classes for implementation.
Installation
The library is available through composer. Install the package using the following command:
Usage
The translator requires some setup steps before it can actually be used. Otherwise it won't do much at all.
1. Create instance
Creating the actual instance is straight forward: It does not need any dependencies:
2. Add mod loaders
To be able to actually add mods (or rather their locale files) to the translator, mod loaders must be added first.
The library ships with two loaders, covering the most common use cases:
- ModArchiveLoader: Loads the mods from the zipped archive. This loader can be used to load any mods downloaded from the Factorio mod portal.
- ModDirectoryLoader: Loads mods from a directory. This loader can be used to load the
core
andbase
mods from the Factorio game itself, as they are shipped uncompressed with the game.
3. Load the mods
After the loaders have been added, it is now time to load the mods to use for the translations. Simply add the paths to the mods to the translator, and the loaders will take care of the rest:
Some notes on loading mods:
- The
core
mod from Factorio should always be loaded first, and thebase
mod should always be loaded second. Not doing so may lead to missing translations. - The order of the mods actually matters: If two mods provide a translation for the same key, the later one added will win. This is the same is Factorio would do it. Ideally all mods get added in the same order as Factorio loads them.
4. Add text processors
The translator uses text processors to process translated strings further. An example of such processing is to replace special references in the string with their actual values. While the translator ships with some basic processors, it may be required to implement your own processors to get all the features out of the translators.
Standard processors
The translator comes with some standard processors. It is recommended to always add these to the translator, as they handle very basic features of localised strings.
- PositionPlaceholderProcessor: Handles position references for parameters like
__1__
. - EntityPlaceholderProcessor: Handles entity references like
__ENTITY__iron-ore__
, replacing it with the translated name of the entity. - ItemPlaceholderProcessor: Handles item references like
__ITEM__electronic-circuit__
, replacing it with the translated name of the item. - PluralPlaceholderProcessor: Handles the special plural form syntax of Factorio, like
__plural_for_parameter_1_{1=hour|rest=hours}__
.
Add these processors as following:
Advanced processors
The translator also provides some abstract processor classes, which needs further implementation before they can actually be used. These abstract processors include:
- AbstractControlPlaceholderProcessor: Handles placeholders like
__CONTROL__build__
and__ALT_CONTROL__1__build__
. A derived class must provide the replacement of the control. - AbstractStandaloneTagProcessor: Handles simple RichText tags without content, e.g.
[item=electronic-circuit]
. The abstract class handles parsing of the tags (but not of the tag value), and the derived class must provide the replacement for the tag. - AbstractContentTagProcessor: Handles complex RichText tags, having content between them, like
[color=red]foo[/color]
and[font=bold]foo[/font]
. The abstract class already handles parsing the string for the tags, and the derived class must provide the replacement for them, e.g. HTML format.
The following example shows how to implement and use the control placeholder processor:
5. Usage
After all these steps, it is time to actually use the translator to translate localised strings. This is rather simple:
The first parameter is the locale to translate the localised string into. The values are the same as used by Factorio.
A list of all locales can be obtained by calling $translator->getAllLocales()
.
If a translation is not available, translate()
will return an empty string. If you want to fallback to English
instead, use the method translateWithFallback()
instead.
Note that the localised strings must be specified in PHP syntax, i.e. the lua tables must be transformed to PHP arrays. The translator does not understand the lua syntax.
Further reading
Further information and documentations on how the localised strings and the translation system works in Factorio can be found on the following websites:
- Factorio API: LocalisedString
- Factorio wiki: Tutorial:Localisation
- Factorio wiki: Rich text
All versions of factorio-translator with dependencies
ext-zip Version *