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小时内。

chriskonnertz / deeply

维护者

详细信息