README

Factorio翻译库是一个实现PHP中Factorio翻译的库。对于随mod提供的地区文件，它能够将Factorio使用的本地化字符串翻译成mod提供的任何地区。

特性

• 将任何本地化字符串翻译成任何地区，提供mod的地区文件。
• 以存档格式（例如从Factorio mod门户下载的）或已提取的目录（如Factorio本身的核心和基础mod）加载mod。
• 从本地化字符串中解析位置参数 __1__。
• 解析简单的引用，如 __ITEM__electronic-circuit__ 和 __ENTITY__iron-ore__，通过用其翻译名称替换它们。
• 解析复数形式，如 __plural_for_parameter_1_{1=hour|rest=hours}__。
• 通过提供实现的具体类来处理控制引用，如 __CONTROL__build__ 和 __ALT_CONTROL__1__build__。
• 通过提供实现的具体类来处理RichText标签，如 [item=electronic-circuit] 和 [color=red]text[/color]。

安装

该库通过composer提供。使用以下命令安装包

composer require bluepsyduck/factorio-translator

用法

翻译器在使用前需要一些设置步骤。否则，它不会做任何事情。

1. 创建实例

创建实际的实例很简单：它不需要任何依赖项

use BluePsyduck\FactorioTranslator\Translator;

$translator = new Translator();

2. 添加mod加载器

为了能够实际添加mod（或者更确切地说，它们的地区文件）到翻译器，必须首先添加mod加载器。

use BluePsyduck\FactorioTranslator\Loader\ModArchiveLoader;
use BluePsyduck\FactorioTranslator\Loader\ModDirectoryLoader;

$translator->addLoader(new ModDirectoryLoader())
           ->addLoader(new ModArchiveLoader());

该库包含两个加载器，涵盖了最常见的用例

• ModArchiveLoader：从压缩存档中加载mod。此加载器可以用于加载从Factorio mod门户下载的任何mod。
• ModDirectoryLoader：从目录中加载mod。此加载器可以用于加载Factorio游戏本身中的 core 和 base mod，因为它们与游戏一起以未压缩的形式提供。

3. 加载mod

在添加加载器后，现在是时候加载用于翻译的mod了。只需将mod的路径添加到翻译器中，加载器将处理其余部分

$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');

关于加载mod的一些说明

• Factorio的 core mod 应始终首先加载，而 base mod 应始终其次加载。如果不这样做，可能会导致翻译丢失。
• mod的实际顺序很重要：如果两个mod为同一密钥提供翻译，则最后添加的将获胜。这与Factorio的行为相同。理想情况下，所有mod都应该按照Factorio加载它们的顺序添加。

4. 添加文本处理器

翻译器使用文本处理器来进一步处理翻译后的字符串。此类处理的一个例子是将字符串中的特殊引用替换为其实际值。虽然翻译器自带一些基本处理器，但可能需要实现自己的处理器以充分利用翻译器的所有功能。

标准处理器

翻译器自带一些标准处理器。建议始终将这些处理器添加到翻译器中，因为它们处理本地化字符串的非常基本的功能。

• 位置占位符处理器（PositionPlaceholderProcessor）：处理如 __1__ 这样的参数位置引用。
• 实体占位符处理器（EntityPlaceholderProcessor）：处理如 __ENTITY__iron-ore__ 这样的实体引用，并将其替换为实体的翻译名称。
• 物品占位符处理器（ItemPlaceholderProcessor）：处理如 __ITEM__electronic-circuit__ 这样的物品引用，并将其替换为物品的翻译名称。
• 复数占位符处理器（PluralPlaceholderProcessor）：处理Factorio的特殊复数形式语法，如 __plural_for_parameter_1_{1=hour|rest=hours}__。

以下是将这些处理器添加的方法

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_{...}__

高级处理器

翻译器还提供了一些抽象处理器类，在它们实际可以使用之前需要进一步实现。这些抽象处理器包括

• 抽象控制占位符处理器（AbstractControlPlaceholderProcessor）：处理如 __CONTROL__build__ 和 __ALT_CONTROL__1__build__ 这样的占位符。派生类必须提供控制替换。
• 抽象独立标签处理器（AbstractStandaloneTagProcessor）：处理没有内容的简单富文本标签，例如 [item=electronic-circuit]。抽象类处理标签的解析（但不处理标签值），派生类必须提供标签的替换。
• 抽象内容标签处理器（AbstractContentTagProcessor）：处理具有内容之间的复杂富文本标签，例如 [color=red]foo[/color] 和 [font=bold]foo[/font]。抽象类已经处理了字符串的标签解析，派生类必须提供标签的替换，例如HTML格式。

以下示例展示了如何实现和使用控制占位符处理器

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. 使用方法

完成所有这些步骤后，现在是时候真正使用翻译器来翻译本地化字符串了。这相当简单

echo $translator->translate('en', ['item-name.electronic-circuit']); // Electronic circuit
echo $translator->translate('de', ['item-name.electronic-circuit']); // Elektronischer Schaltkreis

第一个参数是要将本地化字符串翻译成的地方。值与Factorio中使用的值相同。可以通过调用 $translator->getAllLocales() 获取所有地方列表。

如果不可用翻译，translate() 将返回空字符串。如果您想回退到英语，请使用 translateWithFallback() 方法。

请注意，本地化字符串必须指定为PHP语法，即Lua表必须转换为PHP数组。翻译器不理解Lua语法。

进一步阅读

有关Factorio中本地化字符串和翻译系统如何工作的更多信息，可以在以下网站上找到

• Factorio API: LocalisedString
• Factorio 维基： 教程：本地化
• Factorio 维基： 富文本