README

目录

1. 安装
2. 配置
3. 使用
4. 更新日志
5. 贡献

1. 安装

要求

SDK 需要安装 cURL PHP 扩展。

使用 composer

使用 composer 安装最新稳定版本： composer require potsky/microsoft-translator-php-sdk

或将 potsky/microsoft-translator-php-sdk 添加到您的 composer.json

{
    "require": {
        "potsky/microsoft-translator-php-sdk": "*"
    }
}

手动

是时候迁移到 composer 了吗？

不是现在？好的，只需在您的 PHP 脚本中包含 src/MicrosoftTranslator.php

include_once( 'src/MicrosoftTranslator.php' );

2. 配置

2.1 Microsoft 账户

1. 注册一个 Microsoft Azure 账户（需要信用卡）

   如果您还没有 Azure 账户，请在 http://azure.com 注册一个 Microsoft Azure 账户。

2. 在您创建了一个 Azure 账户之后，订阅 Azure。除非您使用它，否则您不会为 Azure 付费。然后登录到 Azure 门户 http://portal.azure.com。

3. 将 Microsoft Translator API 订阅添加到您的 Azure 账户中。

   • 选择 + 新建 选项
   • 从 Azure 服务列表中选择 AI + 人工智能服务
   • 选择 文本翻译 API
   • 当您准备好创建 Microsoft Translator API 订阅时，请按 创建 按钮。
   • 完成字段并按 创建 按钮，您现在已订阅 Microsoft Translator。

4. 获取您的认证密钥。

   • 前往 所有资源 并选择您订阅的 Microsoft Translator API 订阅账户。
   • 选择 密钥 选项并复制第一个订阅密钥以访问服务。

2.2 SDK

在实例化新的客户端时，您将传递一个配置参数数组

$msTranslator = new MicrosoftTranslator\Client( $configuration );

以下是可用的参数列表，其中一些是必填的

3. 使用

3.1 方法

使用您的凭据定义客户端

<?php
include 'src/MicrosoftTranslator.php';

$msTranslator = new \MicrosoftTranslator\Client( array(
	'log_level'         => \MicrosoftTranslator\Logger::LEVEL_DEBUG ,
	'api_client_key'     => 'your-client-key' ,
) );

翻译文本

翻译德语中的单词 chair。API 将尝试猜测输入语言

print_r( $msTranslator->translate( 'chair' , 'de' )->getBody() );

结果

Stuhl

通过指定初始句子是法语来翻译德语中的单词 chair

print_r( $msTranslator->translate( 'chair' , 'de' , 'fr' )->getBody() );

结果

Fleisch

翻译文本数组

print_r( $msTranslator->translateArray( array( 'dog' , 'cat' ) , 'fr' )->getBody() );

结果

Array
(
    [dog] => chien
    [cat] => chat
)

您可以像往常一样指定输入语言。

转换文本

仅支持英语。

print_r( $msTranslator->TransformText( 'WTF I am not here!' , 'en' )->getBody() );

结果

Array
(
    [ec] => 0
    [em] => OK
    [sentence] => WHAT THE HECK I am not here!
)

识别文本的语言

print_r( $msTranslator->detect( 'The dog is red' )->getBody() );

结果

en

识别文本数组的语言

print_r( $msTranslator->detectArray( array( 'The dog is red' , 'Le chien est rouge' ) )->getBody() );

结果

Array
(
    [The dog is red] => en
    [Le chien est rouge] => fr
)

获取语言名称

print_r( $msTranslator->getLanguageNames( 'fr' , array( 'en' , 'jp' , 'fr' ) )->getBody() );

结果

Array
(
    [en] => Anglais
    [jp] =>
    [fr] => Français
)

获取可用的翻译语言

print_r( $msTranslator->getLanguagesForTranslate()->getBody() );

结果

Array
(
    [0] => ar
    [1] => bs-Latn
    [2] => bg
    [3] => ca
    [4] => zh-CHS
    [5] => zh-CHT
    [6] => hr
    [7] => cs
    [8] => da
    [9] => nl
    ...
)

分割句子

print_r( $msTranslator->breakSentences( 'The dog is red. The cat is blue. The fish is yellow submarine.' , 'en' )->getBody() );

结果

Array
(
    [0] => The dog is red.
    [1] => The cat is blue.
    [2] => The fish is yellow submarine.
)

3.2 处理错误

SDK 在几种情况下可能会抛出 MicrosoftTranslator\Exception

• cURL 的 HTTP 问题
• API 问题...
• 错误的凭据
• ...

您应该像这样捕获这些错误

try
{
	...

}
catch ( \MicrosoftTranslator\Exception $e )
{
	$error = sprintf( "Error #%s with message : %s" , $e->getCode() , $e->getMessage() );
	$msg   = sprintf( "|    %s    |" , $error );
	$line  = str_repeat( '-' , strlen( $msg ) );
	echo sprintf( "%s\n%s\n%s\n" , $line , $msg , $line );
}

或者通过检查返回的代码来捕获这些错误

try
{
	...
}
catch ( \MicrosoftTranslator\Exception $f )
{
	if ( $f->getCode() === 500 )
	{
		echo sprintf( "Oups, error #%s : %s." , $f->getCode() , $f->getMessage() );
	}
	else
	{
		echo sprintf( "Error #%s : %s\n" , $f->getCode() , $f->getMessage() );
	}
}

3.3 自定义 SDK

您可以使用您自己的类来实现 SDK 的几个部分。您的类需要实现接口，它们将在构造函数中获取配置数组。然后您可以在运行时自定义您的类。

3.3.1 注入新的 Logger

您可以使用您自己的 Logger 类。Logger 类用于记录 SDK 消息。

它必须实现 \MicrosoftTranslator\LoggerInterface 接口。

然后在实例化客户端时使用它

$msTranslator = new \MicrosoftTranslator\Client( $config , null , null , $my_logger );

3.3.2 注入新的HTTP管理器

您可以使用自己的 Http 类。该 Http 类负责管理到累加器API的HTTP连接。

它必须实现 \MicrosoftTranslator\HttpInterface 接口。

然后在实例化客户端时使用它

$msTranslator = new \MicrosoftTranslator\Client( $config , $my_http_manager );

3.3.3 注入新的认证管理器

您可以使用自己的 Auth 类。Auth 类的职责是获取访问令牌并将其提供给 Guard 管理器。

它必须实现 \MicrosoftTranslator\AuthInterface 接口。

然后在实例化客户端时使用它

$msTranslator = new \MicrosoftTranslator\Client( $config , null , $my_auth_manager );

3.3.4 注入新的Guard管理器

您可以使用自己的 Guard 管理器。Guard 类的职责是存储访问令牌并管理过期时间。

Guard 注入与其他注入略有不同，因为它是在配置数组中完成的。这是一个 setter 依赖注入，而不是 实例化 依赖注入。

它必须实现 \MicrosoftTranslator\GuardInterface 接口。

通过配置数组注入新的 Guard 管理器

$msTranslator = new \MicrosoftTranslator\Client( array(
	'guard_type' => 'MyNameSpace\\MyGuard'
) );

3.4 管理已保存的访问令牌

SDK通过Guard对象维护访问令牌。默认Guard是GuardFile，它在文件中存储访问令牌。

如果您需要删除所有已保存的访问令牌，可以这样做

$msTranslator->getAuth()->getGuard()->deleteAllAccessTokens();

要删除仅过期的访问令牌，请运行此命令

$msTranslator->getAuth()->getGuard()->cleanAccessTokens();

4. 变更日志

• v0.0.3
  • 切换到Azure API
  • 在 example 目录中添加了一个可用的示例
• v0.0.2
  • 当无法检索访问令牌时，SDK现在返回 MicrosoftTranslator\Exception
• v0.0.1
  • 从这里开始

5. 贡献

1. Fork它
2. 创建您的功能分支（git checkout -b my-new-feature）
3. 提交您的更改（git commit -am '添加一些功能'）
4. 将更改推送到分支（git push origin my-new-feature）
5. 创建新的Pull Request

测试在 tests 目录中。要运行测试：vendor/bin/phpunit。

合并后覆盖率不能降低。要跟踪文件覆盖率，请运行 vendor/bin/phpunit --coverage-html coverage 并打开 coverage/index.html 检查未覆盖的代码行。