README

免费的Google翻译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。

支持的语言列在 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翻译提供的原始结果。您可以使用 getResponse 方法做到这一点。

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

自定义URL

您可以通过 setUrl 方法覆盖默认的Google翻译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 Service Unavailable 响应：如果您收到此错误，很可能是 Google 禁止了您的外部 IP 地址，或者需要您解决一个 CAPTCHA。这不是本包的 bug。Google 变得更加严格，他们似乎在不断地降低每个 IP 在一定时间内允许的请求数量。尝试减少请求量以保持在雷达之下，或者频繁更改您的 IP（例如使用代理）。请注意，一旦某个 IP 被禁止，即使只是临时性的，禁止可能持续几分钟到 12-24 小时以上，具体取决于每个案例。
429 Too Many Requests 响应：这个错误基本上与上面的解释相同。
413 Request Entity Too Large 响应：这个错误意味着您的输入字符串太长。Google 只允许一次性翻译最多 5000 个字符。如果您想翻译较长的文本，您可以将其分成较短的段落，然后逐一翻译。
403 Forbidden 响应：这不是本包的问题。Google Translate 本身翻译某些字符和 HTML 实体时存在问题。请参阅 Stichoza#119（评论）

免责声明

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

捐赠

如果这个包帮助您节省了开发时间，或者解决了您遇到的任何重大问题，请随意给我一杯咖啡：）

themismin / google-translate-php

维护者

详细信息