PHPackages bluepsyduck/factorio-translator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. bluepsyduck/factorio-translator ActiveLibrary bluepsyduck/factorio-translator =============================== A library able to translate localised strings from Factorio, given the locale files. 1.0.2(5y ago)02.0k1GPL-3.0-or-laterPHPPHP ^7.4 || ^8.0CI failing Since Jun 24Pushed 5y ago1 watchersCompare [ Source](https://github.com/BluePsyduck/factorio-translator)[ Packagist](https://packagist.org/packages/bluepsyduck/factorio-translator)[ Docs](https://github.com/BluePsyduck/factorio-translator)[ RSS](/packages/bluepsyduck-factorio-translator/feed)WikiDiscussions master Synced 5d ago READMEChangelog (3)Dependencies (7)Versions (4)Used By (1) Factorio Translator Library =========================== [](#factorio-translator-library) [![GitHub release (latest SemVer)](https://camo.githubusercontent.com/25c1151cfa0a9fe33a85b70df6d6d58d55b4908ee483188e982e7596ce3d24a8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f426c75655073796475636b2f666163746f72696f2d7472616e736c61746f72)](https://github.com/BluePsyduck/factorio-translator/releases)[![GitHub](https://camo.githubusercontent.com/d0f380779530f31a7fa7085a448df523fdb57176c34f7a6a0bd5dc4886efb27f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f426c75655073796475636b2f666163746f72696f2d7472616e736c61746f72)](LICENSE.md)[![build](https://camo.githubusercontent.com/c8d9d37d52b4b42c9829722ccbf41083930b77af4919c08577d5c24e0e69c7f7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f426c75655073796475636b2f666163746f72696f2d7472616e736c61746f722f43493f6c6f676f3d676974687562)](https://github.com/BluePsyduck/factorio-translator/actions)[![Codecov](https://camo.githubusercontent.com/a87873791fffa9122c85df5896453087a2e7ce110e791bcd81d7adeee074f022/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f67682f426c75655073796475636b2f666163746f72696f2d7472616e736c61746f723f6c6f676f3d636f6465636f76)](https://codecov.io/gh/BluePsyduck/factorio-translator) 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 -------- [](#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 ------------ [](#installation) The library is available through composer. Install the package using the following command: ``` composer require bluepsyduck/factorio-translator ``` Usage ----- [](#usage) The translator requires some setup steps before it can actually be used. Otherwise it won't do much at all. ### 1. Create instance [](#1-create-instance) Creating the actual instance is straight forward: It does not need any dependencies: ``` use BluePsyduck\FactorioTranslator\Translator; $translator = new Translator(); ``` ### 2. Add mod loaders [](#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. ``` use BluePsyduck\FactorioTranslator\Loader\ModArchiveLoader; use BluePsyduck\FactorioTranslator\Loader\ModDirectoryLoader; $translator->addLoader(new ModDirectoryLoader()) ->addLoader(new ModArchiveLoader()); ``` 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` and `base` mods from the Factorio game itself, as they are shipped uncompressed with the game. ### 3. Load the mods [](#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: ``` $translator->loadMod('/path/to/factorio/data/core') ->loadMod('/path/to/factorio/data/base') ->loadMod('/path/to/factorio/mods/my-fancy-mod_1.33.7.zip'); ``` Some notes on loading mods: - The `core` mod from Factorio should always be loaded first, and the `base` 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 [](#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 [](#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: ``` use BluePsyduck\FactorioTranslator\Processor\Placeholder\PositionPlaceholderProcessor; use BluePsyduck\FactorioTranslator\Processor\Placeholder\EntityPlaceholderProcessor; use BluePsyduck\FactorioTranslator\Processor\Placeholder\ItemPlaceholderProcessor; use BluePsyduck\FactorioTranslator\Processor\Placeholder\PluralPlaceholderProcessor; $translator->addProcessor(new PositionPlaceholderProcessor()) // Handles e.g. __1__ ->addProcessor(new EntityPlaceholderProcessor()) // Handles e.g. __ENTITY__iron-ore__ ->addProcessor(new ItemPlaceholderProcessor()) // Handles e.g. __ITEM_electronic-circuit__ ->addProcessor(new PluralPlaceholderProcessor()); // Handles e.g. __plural_for_parameter_1_{...}__ ``` #### Advanced processors [](#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: ``` use BluePsyduck\FactorioTranslator\Processor\Placeholder\AbstractControlPlaceholderProcessor; use BluePsyduck\FactorioTranslator\TranslatorAwareInterface; use BluePsyduck\FactorioTranslator\TranslatorAwareTrait; $translator->addProcessor( new class extends AbstractControlPlaceholderProcessor implements TranslatorAwareInterface { use TranslatorAwareTrait; protected function processControl(string $locale, string $controlName, int $version): ?string { // Use the translated name of the control (as it appears in the options menu), // and put it into square brackets. $control = $this->translator->translateWithFallback($locale, ["controls.{$controlName}"]); return "[{$control}]"; } } ); ``` ### 5. Usage [](#5-usage) After all these steps, it is time to actually use the translator to translate localised strings. This is rather simple: ``` echo $translator->translate('en', ['item-name.electronic-circuit']); // Electronic circuit echo $translator->translate('de', ['item-name.electronic-circuit']); // Elektronischer Schaltkreis ``` 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-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](https://lua-api.factorio.com/latest/Concepts.html#LocalisedString) - Factorio wiki: [Tutorial:Localisation](https://wiki.factorio.com/Tutorial:Localisation) - Factorio wiki: [Rich text](https://wiki.factorio.com/Rich_text) ### Health Score 30 — LowBetter than 64% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity17 Limited adoption so far Community9 Small or concentrated contributor base Maturity62 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~161 days Total 3 Last Release 1829d ago PHP version history (2 changes)1.0.0PHP ^7.4 1.0.1PHP ^7.4 || ^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/f0409c6a7a462814e06b0ae7d5bb8deb52789b0b5543305e4143ff3ab823838e?d=identicon)[BluePsyduck](/maintainers/BluePsyduck) --- Top Contributors [![BluePsyduck](https://avatars.githubusercontent.com/u/1012405?v=4)](https://github.com/BluePsyduck "BluePsyduck (37 commits)") --- Tags translatorFactorio ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/bluepsyduck-factorio-translator/health.svg) ``` [![Health](https://phpackages.com/badges/bluepsyduck-factorio-translator/health.svg)](https://phpackages.com/packages/bluepsyduck-factorio-translator) ``` ### Alternatives [stichoza/google-translate-php Free Google Translate API PHP Package 2.0k7.6M124](/packages/stichoza-google-translate-php)[barryvdh/laravel-translation-manager Manage Laravel Translations 1.7k3.6M17](/packages/barryvdh-laravel-translation-manager)[deeplcom/deepl-php Official DeepL API Client Library 2616.2M66](/packages/deeplcom-deepl-php)[netgen/query-translator Query Translator is a search query translator with AST representation 2042.0M6](/packages/netgen-query-translator)[statickidz/php-google-translate-free Google Translate Free library for PHP 289258.8k6](/packages/statickidz-php-google-translate-free)[phpmyadmin/motranslator Translation API for PHP using Gettext MO files 591.8M8](/packages/phpmyadmin-motranslator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)