chriskonnertz / deeply
DeepLy 是 DeepL.com 翻译 API 的 PHP 客户端
Requires
- php: >=8.0
- ext-curl: *
Requires (Dev)
- phpunit/phpunit: 9.*
README
DeepLy 2
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 来表示。
💡 文档的生命周期是: queued ➜ translating ➜ done(或 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小时内。