DeepLy 是 DeepL.com 翻译 API 的 PHP 客户端

v2.2.0 2023-07-06 14:00 UTC

README

alt text

DeepLy 2

Build Status Version GitHub license Version

DeepL 是一种新一代翻译服务。DeepLy 是一个无需依赖的 PHP 库,它使用 API 密钥实现与 DeepL API 的交互。您可以在他们的 网站上 免费获取 API 密钥。DeepLy 自动支持免费和付费 API。有关交互式演示脚本,请查看 演示文件夹

安装

此库需要 PHP 8.0 或更高版本以及 cURL 扩展。通过 Composer 安装 DeepLy

composer require chriskonnertz/deeply

示例

$deepLy = new ChrisKonnertz\DeepLy\DeepLy('your-api-key');

$translatedText = $deepLy->translate('Hello world!', 'DE');
    
echo $translatedText; // Prints "Hallo Welt!"

💡 包含一个交互式 PHP 演示脚本。它位于 demos/demo_translate.php

高级示例

$deepLy = new ChrisKonnertz\DeepLy\DeepLy('your-api-key');

try {
    $translatedText = $deepLy->translate('Hello world!', DeepLy::LANG_EN, DeepLy::LANG_AUTO);
    
    echo $translatedText; // Prints "Hallo Welt!"
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

始终在 translate 方法的调用中包裹 try-catch 块,因为如果参数无效或 API 调用失败,它们可能会抛出异常。异常将包含解释性消息和特定的错误代码。

最好使用 DeepLy 类的语言代码常量作为语言参数,而不是使用硬编码的字符串。该类还提供如 getLangCodes($withAuto = true)supportsLangCode($langCode) 等方法。

如果需要指定高级设置,请使用 setSettings() 方法:$deepLy->setSettings($glossaryId);

自动检测语言

⚠️ 注意:使用此方法会增加您账户的使用统计!

DeepLy 有一个方法使用 DeepL API 检测文本的语言

$languageCode = $deepLy->detectLanguage('Hello world!');

这将返回 'EN'。文本的语言必须是支持的语言之一,否则结果将不正确。如果您不需要语言代码,但需要其英文名称,可以调用 $deepLy->getLangName($langCode) 方法。

API 通常可以处理包含不同语言部分的文本,如果语言切换不在句子中。但是,detectLanguage() 方法只会返回 一种 语言代码。如果无法自动检测语言,它将抛出异常。这种情况很少发生,更有可能的是 API 会返回“假阳性”:它更可能检测到错误的语言,而不是检测不到语言。

💡 包含一个交互式 PHP 演示脚本。它位于 demos/demo_detect

支持的语言

DeepL(y) 支持以下语言

💡 注意,只能自动检测源语言。

术语表

要获取所有术语表的信息列表,请执行

$glossaries = $deepLy->getGlossaries();
print_r($glossaries); // Prints an array with Glossary objects

输出

Array
(
    [0] => ChrisKonnertz\DeepLy\Models\Glossary Object
        (
            [glossaryId] => 56cab399-ac8e-4a57-aadc-fa95103f2de5
            [entryCount] => 2
            ...
        )
    [2] => ChrisKonnertz\DeepLy\Models\Glossary Object
        (
            [glossaryId] => d9eb53b5-3929-49a1-b5e1-df1eb8be93c9
            [entryCount] => 5
            ...
        )
)

要获取特定术语表的信息,请执行

$glossary = $deepLy->getGlossary('your-glossary-id');
print_r($glossary); // Prints a \stdClass

输出

ChrisKonnertz\DeepLy\Models\Glossary Object
(
    [glossaryId] => d9eb53b5-3929-49a1-b5e1-df1eb8be93c9
    [name] => DeepLy Test
    [ready] => 1
    [from] => en
    [to] => de
    [creationTimeIso] => 2022-04-21T17:46:31.83913+00:00
    [creationDateTime] => DateTime Object
    [entryCount] => 2
)

要获取特定术语表的翻译条目,请执行

$entries = $deepLy->getGlossaryEntries('your-glossary-id');
print_r($entries);  // Prints an array with string items

输出

Array
(
    [Entry 1 DE] => Entry 1 EN
    [Entry 2 DE] => Entry 2 EN
)

要创建带有翻译条目的新术语表,请执行

$glossary = $deepLy->createGlossary('test', 'de', 'en', ['Example DE' => 'Example EN']);

要删除现有的术语表,请执行

$deepLy->deleteGlossary('your-glossary-id');

💡 包含一个交互式 PHP 演示脚本。它位于 demos/demo_glossaries.php

文档

翻译文档包括三个步骤。第一步是上传文档

$filename = __DIR__.'/test_document_original.pdf';
$result = $deepLy->uploadDocument($filename, 'DE');

var_dump($result);

输出

ChrisKonnertz\DeepLy\Models\DocumentHandle Object
(
  [documentId] => D014F316B7A173079074BE76F530F846
  [documentKey] => 39FF8B10D20621096F23BF96CC103E12074727007C62963CF49AE8A9965D7695
)

💡 任何文档的最大上传限制为 10 MB 和 100 万个字符。

⚡ 每次文件上传至少收费 50,000 个字符!

第二步是等待 DeepL.com API 完成文档的处理(翻译)。您可以检查状态

$result = $deepLy->getDocumentState($result->documentId, $result->documentKey);

var_dump($result);

输出

ChrisKonnertz\DeepLy\Models\DocumentState Object
(
    [documentId] => D014F316B7A173079074BE76F530F846
    [status] => done
    [billedCharacters] => 50000
    [secondsRemaining] => null
)

在这种情况下,文档已被处理。这可以通过 "status" 为 "done" 和 "seconds_remaining" 为 null 来表示。

💡 文档的生命周期是: queuedtranslatingdone(或 error

有一些常量可以用来检查这些值:DocumentState\STATUS_DONE 等。

第三步是下载文档

$deepLy->downloadDocument($documentId, $documentKey, 'test_document_translated.pdf');

如果您不想存储文件,请

$contents = $deepLy->downloadDocument($documentId, $documentKey);

⚡ 文档只能下载一次!

💡 包含了一个交互式 PHP 示例脚本。它位于 demos/demo_documents.php

使用统计

要获取使用统计信息,请

$usage = $deepLy->usage(); // Returns an object of type "Usage"

echo $usage->characterCount.'/'.$usage->characterLimit
    . ' characters ('.round($usage->characterQuota * 100).'%)';

根据用户账户类型,某些使用类型将为 null。了解更多信息:https://www.deepl.com/de/docs-api/other-functions/monitoring-usage/

框架集成

DeepLy 支持 Laravel 5.5+,并且由于它还支持 包自动发现,它将被自动检测。但是,您必须手动在 .env 文件中存储您的 DeepL API 密钥,如下所示

DEEPL_API_KEY = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

之后,您可以通过这种方式访问 DeepLy:$ping = \DeepLy::ping();

HTTP 客户端

默认情况下,DeepLy 使用基于 cURL 的最小化 HTTP 客户端。如果您想使用不同的 HTTP 客户端,例如 Guzzle,创建一个实现 HttpClient\HttpClientInterface 的类,并使用替代 HTTP 客户端的 方法。然后使用 $deepLy->setHttpClient($yourHttpClient) 注入它。

💡 注意:如果您遇到与集成 cURL 客户端相关的问题,这些问题可以通过将 CURLOPT_SSL_VERIFYPEER 设置为 false 来解决,请首先阅读此信息:snippets.webaware.com.au/../

如果不起作用,请尝试:$deepLy->getHttpClient()->setSslVerifyPeer(false)

💡 您可以使用以下方式设置代理:$deepLy->getHttpClient()->setProxy('ip:port', 'user:password')

测试

导出您的 API 密钥

export DEEPL_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

在 DeepLy 目录中运行 composer install,然后运行测试

./vendor/phpunit/phpunit/phpunit

与 V1 的区别

要从 v1 升级到 v2,请确保在实例化 DeepLy 对象时指定 API 密钥。除了上面提到的更改外,只要您没有编写自己的 HTTP 客户端或使用自定义类扩展 DeepLy 类,您的 v1 代码应该仍然与 v2 一起工作。要了解更多有关更改的信息,请参阅 changelog

免责声明

这不是官方包。它是 100% 开源和非商业的。

DeepL 是 DeepL GmbH 的产品。更多信息:deepl.com/publisher.html

注意事项

  • 文本必须使用 UTF8 编码。

  • 如果您正在寻找使用 DeepLy 的实际示例应用程序,您可以查看 Translation Factory

  • 此库的代码格式符合由以下定义的代码风格
    PSR-2 标准。

  • 本仓库的状态:维护中。创建一个 问题,您将收到回复,通常在48小时内。