README

为 Symfony Translation component 提供服务的 Charcoal 服务提供商。

为多语言应用程序提供国际化（I18N）工具，用于翻译消息和管理地区。

安装

首选（也是唯一支持）的方法是使用Composer
```
★ composer require locomotivemtl/charcoal-translator
```

添加服务提供商，并通过应用程序配置集或服务容器配置默认翻译/地区服务

"service_providers": {
    "charcoal/translator/service-provider/translator": {}
},

"translator": {
    // …
},

"locales": {
    // …
}

或通过服务容器

$container->register(new \Charcoal\Translator\ServiceProvider\TranslatorServiceProvider());

$container['translator/config'] = new \Charcoal\Translator\TranslatorConfig([
    // …
]);

$container['locales/config'] = new \Charcoal\Translator\LocalesConfig([
    // …
]);

如果您使用 locomotivemtl/charcoal-app，则 [TranslatorServiceProvider][translator-provider] 由 AppServiceProvider 自动注册。

依赖关系

必需

PHP 5.6+: 推荐使用 PHP 7。
symfony/translation: Charcoal的翻译服务扩展的翻译组件。
pimple/pimple: 符合PSR-11的服务容器和提供者库。
locomotivemtl/charcoal-config: 用于配置翻译服务和地区。

PSR

PSR-7: HTTP消息的通用接口。遵循 LanguageMiddleware。
PSR-11: 依赖容器的通用接口。由Pimple实现。

依赖关系

locomotivemtl/charcoal-admin: Charcoal应用程序的行政界面。
locomotivemtl/charcoal-app: 符合PSR-7的Web应用程序框架。
通过 LanguageMiddleware 解决当前地区。
locomotivemtl/charcoal-cms: 预设模型和基本工具，用于内容管理（页面、新闻、事件）。
支持多语言模型属性和本地化模型描述符。
locomotivemtl/charcoal-property：模型属性值和元数据。
用于支持多语言值和属性描述的本地化。

功能

翻译对象

Charcoal\Translator\Translation

翻译对象存储给定字符串在所有可用语言/区域的所有翻译数据。

// Get a translation object from the Translator
$translation = $container['translator']->translation([
    'en' => 'Hello World',
    'fr' => 'Bonjour'
]);

// If cast to string, the default language will be used.
echo $translation;

// Use ArrayAccess to get (or set) a translated value.
echo $translation['fr'];
$translation['fr'] => 'Bonjour le monde';

// To loop through all translations:
foreach ($translation->data() as $lang => $translatedValue) {
    // ...
}

翻译服务

Charcoal\Translator\Translator

Charcoal的翻译器扩展了Symfony的Translator，也提供了两种新的翻译方法（translation($val)和translator($val)），都可以接受混合参数，在translation()的情况下返回Translation对象，在translate($val)的情况下返回字符串。

地区管理器

Charcoal\Translator\LocalesManager

区域管理器用于管理可用的区域/语言，并跟踪当前语言。

解析脚本

Charcoal\Translator\Script\TranslationParserScript

解析器脚本用于抓取包含可翻译内容的文件。将以下路由添加到您的应用程序配置中

"scripts": {
    "charcoal/translator/parse": {
        "ident": "charcoal/translator/script/translation-parser"
    }
}

服务提供商

TranslatorServiceProvider为将您的应用程序翻译成不同的语言提供服务和选项。

参数

locales/config：定义可用语言的配置对象，回退和默认值。
locales/default-language：应用程序的默认语言，可选地是导航器的首选语言。
locales/browser-language：导航器接受的语言。
locales/fallback-languages：翻译器的回退语言代码列表。
locales/available-languages：从可用区域中获取的语言代码列表。
locales/languages：应用程序的可用语言结构列表。
translator/config：翻译服务的配置对象，消息目录和目录加载器。
translator/translations：按域和区域分组的其他翻译字典。

服务

locales/manager：一个LocalesManager实例，用于处理可用语言、它们的定义、默认语言和跟踪当前语言。
translator：一个Translator实例，用于翻译。
translator/message-selector：一个Symfony\Component\Translation\MessageSelector实例。
translator/loader/*：翻译Symfony\Component\Translation\Loader\LoaderInterface实例。

配置

以下是一个配置示例

"locales": {
    "languages": {
        "de": {},
        "en": {},
        "es": {
            "active": false
        },
        "fr": {}
    },
    "default_language": "fr",
    "fallback_languages": [
        "en", 
        "fr"
    ],
    "auto_detect": true
},
"translator": {
    "loaders": [
        "xliff",
        "json",
        "php"
    ],
    "paths": [
        "translations/",
        "vendor/locomotivemtl/charcoal-app/translations/"
    ],
    "debug": false,
    "cache_dir": "cache/translation/",
    "translations": {
        "messages": {
            "de": {
                "hello": "Hallo {{ name }}",
                "goodbye": "Auf Wiedersehen!"
            },
            "en": {
                "hello": "Hello {{ name }}",
                "goodbye": "Goodbye!"
            },
            "es": {
                "hello": "Hallo {{ name }}",
                "goodbye": "Adios!"
            },
            "fr": {
                "hello": "Bonjour {{ name }}",
                "goodbye": "Au revoir!"
            }
        },
        "admin": {
            "fr": {
                "Save": "Enregistrer"
            }
        }
    }
}

中间件

LanguageMiddleware适用于支持中间件的PSR-7应用程序。中间件使用Accept-Language HTTP头、URI路径、查询字符串或主机来检测首选语言。

如果您使用locomotivemtl/charcoal-app，您可以通过应用程序配置集添加中间件

"middlewares": {
    "charcoal/translator/middleware/language": {
        "active": true,
        "use_params": true,
        "param_key": "hl"
    }
}

否则，使用例如Slim

$app = new \Slim\App();

// Register middleware
$app->add(new \Charcoal\Translator\Middleware\LanguageMiddleware([
    'default_language' => 'fr',
    'use_params'       => true,
    'param_key'        => 'hl',
]));

中间件包含一组默认选项，可以单独覆盖。

助手

TranslatorAwareTrait

Charcoal\Translator\TranslatorAwareTrait

TranslatorAwareTrait作为便利性提供，以避免重复/样板代码。它只是设置和获取一个Translator服务属性。

使用setTranslator()设置，使用translator()获取。两者都是受保护的方法。（该特性没有公开接口。）

开发

安装开发环境

★ composer install --prefer-source

运行脚本（phplint，phpcs 和 phpunit）

★ composer tests

API 文档

自动生成的 phpDocumentor API 文档可在以下位置获取
https://locomotivemtl.github.io/charcoal-translator/docs/master/
自动生成的 apigen API 文档可在以下位置获取
https://codedoc.pub/locomotivemtl/charcoal-translator/master/

开发依赖

编码风格

charcoal-translator 模块遵循 Charcoal 编码风格

PSR-1
PSR-2
PSR-4，因此自动加载由 Composer 提供。
phpDocumentor 注释。
phpcs.xml.dist 和 .editorconfig 用于编码标准。

可以使用composer phpcs执行编码风格验证/强制执行。还提供有自动修复工具，使用composer phpcbf。

鸣谢

许可

Charcoal 采用 MIT 许可证授权。有关详细信息，请参阅LICENSE。

locomotivemtl / charcoal-translator

维护者

详细信息

README

目录

安装

依赖关系

必需

PSR

依赖关系

功能

翻译对象

翻译服务

地区管理器

解析脚本

服务提供商

参数

服务

配置

中间件

助手

TranslatorAwareTrait

开发

API 文档

开发依赖

编码风格

鸣谢

许可