README

免费 Google Translate API PHP 包。完全免费翻译。

安装
基本用法
高级用法
已知限制
免责声明
捐赠

安装

通过 Composer 安装此包。

composer require stichoza/google-translate-php

注意 PHP 8.0 或更高版本 需要。为旧版本 PHP 使用以下版本的此包

基本用法

创建 GoogleTranslate 对象

use Stichoza\GoogleTranslate\GoogleTranslate;

$tr = new GoogleTranslate('en'); // Translates into English

或者您可以在之后更改语言

$tr = new GoogleTranslate(); // Translates to 'en' from auto-detected language by default
$tr->setSource('en'); // Translate from English
$tr->setSource(); // Detect language automatically
$tr->setTarget('ka'); // Translate to Georgian

翻译句子

echo $tr->translate('Hello World!');

您还可以使用方法链

echo $tr->setSource('en')->setTarget('ka')->translate('Goodbye');

或者调用简写静态方法 trans

echo GoogleTranslate::trans('Hello again', 'ka', 'en');

高级用法

语言检测

要自动检测语言，只需将源语言设置为 null

$tr = new GoogleTranslate('es', null); // Or simply do not pass the second parameter

$tr->setSource(); // Another way

使用 getLastDetectedSource() 获取检测到的语言

$tr = new GoogleTranslate('fr');

$text = $tr->translate('Hello World!');

echo $tr->getLastDetectedSource(); // Output: en

如果无法检测到语言，返回值将为 null

支持的语言

您可以使用 languages 方法获取所有支持的语言列表。

$tr = new GoogleTranslate();

$languages = $tr->languages(); // Get supported languages in iso-639 format

// Output: [ 'ab', 'ace', 'ach', 'aa', 'af', 'sq', 'alz', ... ]

可选地，传递一个目标语言代码以检索以该语言显示名称的支持语言。

$tr = new GoogleTranslate();

$languages = $tr->languages('en'); // Get supported languages, display name in english
// Output: [ 'en' => English', 'es' => 'Spanish', 'it' => 'Italian', ... ]

echo $languages['en']; // Output: 'English'
echo $languages['ka']; // Output: 'Georgian'

与 translate/trans 方法相同，您还可以使用静态 langs 方法

GoogleTranslate::langs();
// Output: [ 'ab', 'ace', 'ach', 'aa', 'af', 'sq', 'alz', ... ]

GoogleTranslate::langs('en');
// Output: [ 'en' => English', 'es' => 'Spanish', 'it' => 'Italian', ... ]

支持的语言也列在 Google API 文档中。

保留参数

preserveParameters() 方法允许您在执行翻译时保留某些参数。这对于处理本地化文件或模板引擎尤其有用，其中需要排除特定占位符进行翻译。

默认正则表达式是 /:(\w+)/，它涵盖了以冒号开头的参数。这对于翻译 Laravel 和其他框架的语言文件很有用。您还可以传递自定义正则表达式来修改参数语法。

$tr = new GoogleTranslate('de');

$text = $tr->translate('Page :current of :total'); // Seite :aktuell von :gesamt

$text = $tr->preserveParameters()
           ->translate('Page :current of :total'); // Seite :current von :total

或者使用自定义正则表达式

$text = $tr->preserveParameters('/\{\{([^}]+)\}\}/')
           ->translate('Page {{current}} of {{total}}'); // Seite {{current}} von {{total}}

您还可以使用相同的特性与静态 trans() 方法一起使用。

GoogleTranslate::trans('Welcome :name', 'fr', preserveParameters: true); // Default regex

GoogleTranslate::trans('Welcome {{name}}', 'fr', preserveParameters: '/\{\{([^}]+)\}\}/'); // Custom regex

使用原始响应

对于高级用法，您可能需要 Google Translate 提供的原始结果。您可以使用 getResponse 方法来获取这些结果。

$responseArray = $tr->getResponse('Hello world!');

自定义 URL

您可以使用 setUrl 方法覆盖默认的 Google Translate URL。这对于一些国家很有用。

$tr->setUrl('http://translate.google.cn/translate_a/single');

HTTP 客户端配置

此包使用 Guzzle 进行 HTTP 请求。您可以将一个包含 guzzle 客户端配置选项的数组作为第三个参数传递给 GoogleTranslate 构造函数，或者只需使用 setOptions 方法。

您可以使用这些选项配置代理、用户代理、默认头、连接超时等。

$tr = new GoogleTranslate('en', 'ka', [
    'timeout' => 10,
    'proxy' => [
        'http'  => 'tcp://:8125',
        'https' => 'tcp://:9124'
    ],
    'headers' => [
        'User-Agent' => 'Foo/5.0 Lorem Ipsum Browser'
    ]
]);

// Set proxy to tcp://:8090
$tr->setOptions(['proxy' => 'tcp://:8090'])->translate('Hello');

// Set proxy to socks5://:1080
$tr->setOptions(['proxy' => 'socks5://:1080'])->translate('World');

有关更多信息，请参阅 Guzzle 文档中的创建客户端部分。

自定义令牌生成器

您可以通过将生成器对象作为构造函数的第四个参数传递或使用 setTokenProvider 方法来覆盖令牌生成器类。

生成器必须实现 Stichoza\GoogleTranslate\Tokens\TokenProviderInterface。

use Stichoza\GoogleTranslate\Tokens\TokenProviderInterface;

class MyTokenGenerator implements TokenProviderInterface
{
    public function generateToken(string $source, string $target, string $text): string
    {
        // Your code here
    }
}

并且使用

$tr->setTokenProvider(new MyTokenGenerator);

翻译客户端（质量）

Google Translate 有一个名为 client 的参数，用于定义翻译质量。最初它被设置为 webapp，但后来 Google 添加了 gtx 值，这使得翻译在语法和句子整体意义上有了更好的质量。

您可以使用 ->setClient() 方法在客户端之间切换。例如，如果您想使用旧版本的翻译算法，请输入 $tr->setClient('webapp')->translate('lorem ipsum...')。默认值为 gtx。

错误和异常处理

静态方法 trans() 和非静态方法 translate() 和 getResponse() 将抛出以下异常

ErrorException 如果由于某种原因 HTTP 请求失败。
UnexpectedValueException 如果从 Google 收到的数据无法解码。

截至 v5.1.0 版本，具体的异常在 \Stichoza\GoogleTranslate\Exceptions 命名空间中可用

LargeTextException 如果请求的文本太大而无法翻译。
RateLimitException 如果 Google 因请求过多而阻止了您。
TranslationRequestException 如果在翻译过程中发生任何其他与 HTTP 相关的错误。
TranslationDecodingException 如果响应的 JSON 无法解码。

所有具体的异常都是向后兼容的，所以如果您使用的是旧版本，您不需要更新您的代码。

TranslationDecodingException 继承自 UnexpectedValueException，而 LargeTextException、RateLimitException 和 TranslationRequestException 继承自旧版本（<5.1.0）中使用的 ErrorException。

此外，如果不存在翻译，则 translate() 和 trans() 方法将返回 null。

已知限制

503 服务不可用 响应：如果您收到此错误，很可能是 Google 禁用了您的外部 IP 地址和/或要求您解决 CAPTCHA。这不是本包的 bug。Google 变得更加严格，似乎他们不断地降低每个 IP 每一定时间内允许的请求数量。尝试减少请求以保持不被发现，或者频繁更改您的 IP（例如使用代理（例如使用代理））。请注意，一旦 IP 被禁用，即使只是临时性的，禁用可能持续几分钟到超过 12-24 小时，具体情况不同。
429 Too Many Requests 响应：此错误基本上与上述解释相同。
413 Request Entity Too Large 响应：此错误意味着您的输入字符串太长。Google 只允许一次翻译最多 5000 个字符。如果您想翻译更长的文本，可以将它分成较短的段落，并逐个翻译它们。
403 Forbidden 响应：这不是本包的问题。Google 翻译本身在翻译某些字符和 HTML 实体时存在一些问题。请参阅 #119（评论）

免责声明

本包仅用于教育目的开发。不要将此包作为依赖项，因为它可能随时中断，因为它基于爬取 Google 翻译网站。考虑购买官方 Google 翻译 API 用于其他类型的使用。

捐赠

如果您使用此包减少了开发时间或解决了您遇到的任何主要问题，请随意给我一杯咖啡：）

stichoza / google-translate-php

维护者

详细信息