README

一款用于本地化消息的便捷工具。

Localisator 使用三个元素来翻译您的消息

LocaleOrder -- 决定应该使用哪种语言（们），
Providers -- 从源（文件、数据库、缓存等）中获取特定键的翻译，
Transformers -- 使用更高级的逻辑（复数、回退、嵌套等）修改翻译。

安装

composer require avris/localisator

用法

该库提供了一个简单的 LocalisatorBuilder，如果您只想使用默认配置。使用它，使用方法就像这样

$locale = $_SESSION['_locale'] ?? 'en';
$dirs = [
    __DIR__ . '/translations',
];

$localisator = (new LocalisatorBuilder())
    ->registerExtension(new LocalisatorExtension($locale, $dirs))
    ->build(LocalisatorInterface::class);

如果 translations 目录，您可以定义自己的翻译，例如

app.en.yml:

homepage:
    title: My Website
    hello: Hello!
post:
    list: List of posts
    count: <> One post|%count% posts

app.pl.yml:

homepage:
    title: Moja strona
    hello: Witaj!
post:
    list: Lista postów
    count: <polishDeclination> Post|%count% posty|%count% postów

然后，每当您想要翻译内容时，只需使用

$localisator->get('post.count', ['count' => 3]); // Returns "3 posts" for "en" or "3 posty" for "pl"

地区

地区标识符是：ISO 639-1 语言代码，然后是一个下划线（_），然后是 ISO 3166-1 alpha-2 国家代码。或者它可能只是语言代码本身。

包含国家的地区是扩展/指定只有语言代码的地区。例如，您可能有 en、en_GB 和 en_GB。第一个文件将包含英国和美式英语共享的所有单词和短语，而 en_GB 可能看起来像这样

color: Colour
dateFormat: d/m/Y
currency: £

和 en_US 像这样

color: Color
dateFormat: m/d/Y
currency: $

命名空间

您可以将翻译分组到命名空间中，app 是默认的。例如，如果您想将表单验证消息放在一个地方，请将它们放入 validator.*.yml 文件中，并使用 $translator->get('validator:minLength', ['min' => 5]) 表示法访问这些翻译。

助手

本地化是任何项目广泛使用的事物，您的应用程序的几乎所有部分可能都想翻译一些字符串。如果您不想担心将这些地方的 Localisator 注入到所有这些地方，您可能想为本地化对纯 DI 进行例外。

这就像使用 new DateTime('tomorrow') 而不是一些假设的 $this->timeManager->createDateTime('tomorrow')。

要设置它，您只需在脚本开始时调用此方法一次

LocalisedString::setLocalisator($localisator);

然后，每当您需要翻译某些内容时，只需创建一个 LocalisedString 实例。当转换为字符串时，它将被翻译

echo new LocalisedString('post.count', ['count' => 5]); // echoes "5 posts"

或者更短一些，使用助手

echo l('post.count', ['count' => 5]); // echoes "5 posts"

Twig

如果您注册了 Avris\Localisator\LocalisatorTwig 扩展，您可以使用 Localisator 作为函数或过滤器

{{ 'entity:Post.create.success'|l({title: post.title}) }}

{{ l('entity:Post.create.success', {title: post.title}) }}

配置

提供者

翻译提供者通过命名空间、键和地区从某些源（如文件或数据库）检索数据，并返回翻译的字符串（如果没有找到，则为 null）。

DirsTranslationProvider 从给定的目录中读取所有文件的翻译，这些目录可以使用 FileReader 实现读取（目前支持 Yaml 和 PHP 文件），
ModuleDirTranslationProvider 找到所有具有 translations 目录的 Micrus 模块并将它们加载，
CacheTranslationProvider 包装另一个提供者，并使用任何 PSR-6 缓存池缓存其翻译；它还提供了一个函数来预热缓存。

转换器

变压器将翻译字符串（如果未找到则返回null）和提供的替换项，并对它们进行操作。

它们使用Avris Dispatcher（事件translationTransform）执行，该Dispatcher负责处理转换的顺序（使用监听器优先级）。

内置提供者按执行顺序为

FallbackToPatternTransformer（已禁用）：如果未找到翻译，但键与正则表达式模式匹配，则返回模式中的第一个匹配项。例如对于entity => ['^(.*)\.singular$']，当您想要翻译entity:Post.singular但不存在时，将回退到"Post"。
FallbackToWordTransformer（已禁用）：如果未找到翻译，则回退到显示输入键。
NestedTransformer（已禁用）：如果like的翻译为"I like [[food.pizza.plural]] and [[food.banana.plural]]"，对于food.pizza.plural它是"Pizzas"，对于food.banana.plural是"Bananas"，则结果将是"I like Pizzas and Bananas"。
SelectorsTransformer：根据替换数组中的数据选择翻译的其中一个版本
- CountVersion：<> a dog|%count% dogs将在count等于1时选择"a dog"，否则选择"%count% dogs"。您还可以指定更复杂的范围：<> {0} no dogs|{1} a dog|{2-4} couple dogs|{5-} many dogs。
- PolishDeclination（已禁用）：<polishDeclination> pies|%count% psy|%count% psów将根据波兰语变格规则选择正确的版本（例如"pies"，"2 psy"，"5 psów"）。
ReplacementsTransformer：用替换数组中的值替换翻译字符串的部分，例如l('dogs.count', ['count' => 5]) -> %count% dogs -> 5 dogs。

框架集成

Micrus

尽管现在Localisator可以独立使用，但它最初是作为Micrus框架的一部分编写的。与它的集成非常简单。在您的App\App:registerModules中注册Localisator模块

yield new \Avris\Localisator\LocalisatorModule;

并在您的config/services.yml中注册一个处理器

Avris\Localisator\Handler\SessionLocaleHandler: []
# or:
Avris\Localisator\Handler\UrlLocaleHandler: []

第一个会将用户的区域设置存储在会话中，另一个会在URI中（例如/de/login）。

在config/localisation.yml中指定支持的语言和回退区域设置，例如当一个新用户（未在会话中存储选择的区域设置）来到网站，而你不支持其Accepted-Language头中的任何语言时。

supported:
   en_GB: English (GB)
   en_US: English (USA)
   pl: Polski
   de: Deutsch
 fallback: en_GB

Micrus会自动从所有具有translations目录的模块中加载翻译。

它还将尝试确定给定请求的最佳区域设置 - 从URI、会话、Accept-Language头和回退区域设置。

在Twig中，您可以访问当前区域设置

<html lang="{{ currentLocale().language }}">

并生成切换链接（SessionLocaleHandler或UrlLocaleHandler会处理它们）

{% for code, name in locales %}
    <a href="{{ route('changeLocale', { locale: code }) }}">
        {{ name }}
    </a>
{% endfor %}

l()辅助函数在整个应用程序中可用。

Symfony

Symfony有自己的优秀本地化工具。但如果你仍然想在其中使用Localisator（例如，如果库需要它，如TimeDiff所做的那样），你可以使用以下容器配置来快速设置它

对于LocalisatorBuilder

Avris\Localisator\LocalisatorBuilder:
    calls:
        - [registerExtension, ['@Avris\Localisator\LocalisatorExtension']]
Avris\Localisator\LocalisatorExtension:
    arguments:
        $locale: '%locale%'
Avris\Localisator\LocalisatorInterface:
    factory: ['@Avris\Localisator\LocalisatorBuilder', build]
    arguments: ['Avris\Localisator\LocalisatorInterface']
Avris\Localisator\LocalisatorTwig: ~

或对于完整配置

Avris\Localisator\LocalisatorInterface: '@Avris\Localisator\Localisator'
Avris\Localisator\Localisator: ~
Avris\Localisator\LocalisatorTwig: ~

Avris\Localisator\Provider\TranslationProviderInterface: '@Avris\Localisator\Provider\CacheTranslationProvider'
Avris\Localisator\Provider\CacheTranslationProvider:
    arguments:
        $provider: '@Avris\Localisator\Provider\DirsTranslationProvider'
Avris\Localisator\Provider\DirsTranslationProvider:
    arguments:
        $dirs:
          - '%kernel.project_dir%/vendor/avris/time-diff/translations'
        $fileReaders:
          - '@Avris\Localisator\Provider\FileReader\YamlFileReader'
          - '@Avris\Localisator\Provider\FileReader\PhpFileReader'
Avris\Localisator\Provider\FileReader\YamlFileReader: ~
Avris\Localisator\Provider\FileReader\PhpFileReader: ~

Avris\Localisator\Order\LocaleOrderProviderInterface: '@Avris\Localisator\Order\SimpleLocaleOrderProvider'
Avris\Localisator\Order\SimpleLocaleOrderProvider:
    arguments:
        $locale: '%locale%'

Avris\Dispatcher\EventDispatcherInterface: '@Avris\Dispatcher\EventDispatcher'
Avris\Dispatcher\EventDispatcher:
    calls:
        - [registerSubscriber, ['@Avris\Localisator\Transformer\ReplacementsTransformer']]
        - [registerSubscriber, ['@Avris\Localisator\Transformer\SelectorsTransformer']]
        # - [registerSubscriber, ['@Avris\Localisator\Transformer\NestedTransformer']]
        # - [registerSubscriber, ['@Avris\Localisator\Transformer\FallbackToWordTransformer']]
        # - [registerSubscriber, ['@Avris\Localisator\Transformer\FallbackToPatternTransformer']]
Avris\Localisator\Transformer\ReplacementsTransformer: ~
Avris\Localisator\Transformer\SelectorsTransformer:
    arguments:
        $translationSelectors:
            - '@Avris\Localisator\Transformer\Selector\CountVersion'
            - '@Avris\Localisator\Transformer\Selector\PolishDeclination'
Avris\Localisator\Transformer\Selector\CountVersion: ~
Avris\Localisator\Transformer\Selector\PolishDeclination: ~

avris / localisator

维护者

详细信息