README

将消息批次发送到 Azure 翻译服务。可以选择将变量作为格式化消息处理。

安装

$ composer require marketforce-info/azure-translator

需求

访问 Azure 身份验证详细信息。支持订阅密钥和授权令牌机制。
依赖于 psr/http-client 的具体实现

用法

use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory as GuzzleFactory;
use MarketforceInfo\AzureTranslator\Translator;

$factory = new GuzzleFactory();
$client = new Translator\Client(
    new GuzzleClient(),
    new Translator\RequestFactory($factory, $factory, [Translator\Language::french])
);

$translator = new Translator($client);
$translator->onTranslate(static function (Translator\Translation $translation) {
        // do something with the message
    })
    ->begin(static function (Translator\Delegate $translator) use ($messages) {
        foreach ($messages as $message) {
            $translator->translate($message);
        }
    });

使用 Builder 类的更深入示例。

use \MarketforceInfo\AzureTranslator\Builder;
use \MarketforceInfo\AzureTranslator\MessageFormatter\BasicFormatter;
use \MarketforceInfo\AzureTranslator\Translator;

$factory = new GuzzleFactory();
$translator = (new Builder())
    ->withBaseUrl(Translator\RequestFactory::BASE_URL_US)
    ->withHttp(new GuzzleClient(), $factory, $factory)
    ->withLanguages([Translator\Language::arabic], Translator\Language::french)
    ->withBearerToken('<bearer-token>')
    ->withMessageFormatter(new BasicFormatter('[', ']'))
    ->withTraceIdCallback(fn () => 'xxxx-XXXX-xxxx-XXXX-xxxx')
    ->when(
        $_ENV['delete_profanity'] === true,
        fn (Builder $builder) => $builder->withProfanityDeleted(),
        fn (Builder $builder) => $builder->withProfanityMarked(static fn (string $word) => '*censored*')
    )
    ->create();

翻译消息

onTranslate 回调方法接收一个用于语言的 DTO 翻译消息。它包含四个属性

$message 是翻译消息的字符串。

$language 是消息翻译成的 Language 枚举。

$traceId 是用于跟踪请求的跟踪 ID（下面有更多信息）。

$state 是针对原始未翻译消息的用户指定数据。

可以在请求点（translate）处可选地设置状态。

foreach ($messages as $messageId => $message) {
    $translator->translate($message, ['id' => $messageId]);
}

然后在 onTranslate 回调中。

static function (Translation $translation) use ($db) {
    $db->replace(
        table: 'translations',
        where: [
            'id' => $translation->state['id'],
            'language' => $translation->language->value
        ],
        data: ['message' => $translation->message]
    );
};

翻译请求

请求消息的批处理会自动处理。通过 Delegate 类传递要翻译的消息。必须在定义了 onTranslate 行为之后才能调用 begin 方法。

$translator->begin(static function (Delegate $translator) use ($untranslatedMessages) {
    foreach ($untranslatedMessages as $message) {
        $translator->translate($message);
    }
});

功能

HTTP 客户端

此库依赖于提供三个 PSR 接口实现。分别为 HTTP 客户端提供 ClientInterface，为创建请求提供 RequestFactoryInterface，为创建请求体提供 StreamFactoryInterface。例如，在 Guzzle 实现中，请求和流工厂是相同的实现。

$builder->withHttp($client, $requestFactory, $streamFactory);

提供者

身份验证

有两种方法可以指定身份验证令牌。

$builder->withSubscriptionKey('<subscription-key>');
// or
$builder->withBearerToken('<bearer-token>');

更复杂的情况应通过 HTTP 客户端的插件/中间件处理。

消息格式

默认情况下，没有消息格式化。以下概述了允许不同翻译行为的替代方案。

基本

允许在消息中进行基本语法替换。例如

Welcome {name} to the monthly newsletter from {company}

格式化器将替换变量，这样它们就不会被翻译，然后在最终的翻译消息中替换它们。

use \MarketforceInfo\AzureTranslator\MessageFormatter\BasicFormatter;
$builder->withMessageFormatter(new BasicFormatter());

基本格式化器的默认语法为 {} 样式，但可以在构造函数中更改。

ICU 消息格式

需要额外的组件来解析 ICU 消息格式，以便将表示发送到翻译服务。

安装

$ composer require marketforce-info/message-format-parser

用法

use \MarketforceInfo\AzureTranslator\MessageFormatter\IcuFormatter;
$builder->withMessageFormatter(new IcuFormatter());

注意事项

创建发送到翻译服务的表示的过程会产生冗长的输出，这可能对字符计数和随后的 Azure 服务计费产生不利影响。此外，ICU 解析尝试通过在 ICU 消息格式使用 select、selectordinal 或 plural 时组合消息的变体来实现最佳的翻译结果。

自定义消息格式

可以创建自定义消息格式类。withMessageFormatter 方法接受任何实现 MessageFormatter 接口的实现。

跟踪请求

对 Azure 服务的每个单独请求都包含一个客户端跟踪 ID。默认情况下，这是自动处理的。可以通过以下方法进行覆盖。

用户定义函数

$builder->withTraceIdCallback(fn () => 'xxxx-XXXX-xxxx-XXXX-xxxx');
// or
$builder->withTraceIdCallback([$this, 'traceFunction']);
// or
$builder->withTraceIdCallback(fn (\Closure $generatorFn) => $generatorFn());

生成器函数

如图所示，回调函数传递了一个参数，允许使用内部生成器函数。这在记录每个请求的跟踪ID的情况下非常有用。

处理粗俗语言

Azure提供了三种处理粗俗语言的选项：不处理、删除或用星号或标签标记。组件允许指定这一点。默认情况下，不会启用粗俗语言处理。它允许回调函数自定义粗俗短语的显示方式。

可用方法

$builder->withoutProfanityHandling(); // default
$builder->withProfanityDeleted();
$builder->withProfanityMarked(); // words replaced with *
$builder->withProfanityMarked(static function (string $phrase) {
    return '<span class="profanity">' . str_pad('', mb_strlen($phrase), 'x') . '</span>';
});

获取指标数据

在每次对翻译服务的请求中，都会在处理过程中返回处理字符数的信息。这可以在完成后检索。

$translator->getMeteredUsage();

这返回了一个数组，包含每个请求及其返回的数据。

{
    "1234-1234-1234-1234": [
        "182"
    ]
}

贡献

欢迎以问题或PR的形式提交贡献。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件appsupport_uk@marketforce.com联系，而不是使用问题跟踪器。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

marketforce-info / azure-translator

维护者

详细信息