graffpl/deepl-php

DeepL API官方PHP客户端库

维护者

详细信息

github.com/graffpl/deepl-php

源代码

安装: 14

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 23

1.0.1 2023-01-10 10:48 UTC

Requires

Requires (Dev)

MIT b819240a90236498f599852be600a7a6ae690671

  • DeepL SE <open-source.woop@deepl.com>

translationapitranslatordeepl

This package is auto-updated.

Last update: 2024-09-10 14:53:32 UTC

README

Latest Stable Version Minimum PHP version License: MIT

DeepL API的官方PHP客户端库。

DeepL API是一个语言翻译API，允许其他计算机程序将文本和文档发送到DeepL的服务器，并接收高质量的翻译。这为开发者打开了一个全新的世界：任何你可以想象的翻译产品都可以现在基于DeepL最优质的翻译技术构建。

DeepL PHP库为编写PHP应用程序提供了一种方便的方式与DeepL API交互。我们打算使用库支持所有API功能，尽管在API添加新功能后，可能也会将新功能添加到库中。

获取认证密钥

要使用deepl-php，您需要一个API认证密钥。要获取密钥，请在此处创建账户。使用DeepL API免费账户，您可以免费每月翻译高达50万个字符。

安装

要在您的项目中使用此库，请使用Composer进行安装

composer require deeplcom/deepl-php

要求

该库官方支持PHP 7.3及更高版本。

用法

构建一个Translator对象。第一个参数是一个字符串，包含您在DeepL Pro账户中找到的API认证密钥。

请注意不要泄露您的密钥，例如在共享源代码时。

$authKey = "f63c02c5-f056-..."; // Replace with your key
$translator = new \DeepL\Translator($authKey);

$result = $translator->translateText('Hello, world!', null, 'fr');
echo $result->text; // Bonjour, le monde!

Translator接受选项作为第二个参数，有关更多信息，请参阅配置。

翻译文本

要翻译文本，请调用translateText()。第一个参数是一个包含您要翻译的文本的字符串，如果您想翻译多个文本，则是一个字符串数组。

第二个和第三个参数是源语言和目标语言代码。语言代码是ISO 639-1的字符串，例如'de'、'fr'、'ja'。某些目标语言还包括ISO 3166-1的区域变体，例如'en-US'或'pt-BR'。源语言也接受null，以启用自动检测源语言。

translateText()的最后一个参数是可选的，并指定额外的翻译选项，请参阅下面的文本翻译选项。

translateText()返回一个TextResult，或与您的输入文本对应的TextResult数组。TextResult有两个属性：text是翻译后的文本，detectedSourceLang是检测到的源语言代码。

// Translate text into a target language, in this case, French:
$translationResult = $translator->translateText('Hello, world!', 'en', 'fr');
echo $translationResult->text; // 'Bonjour, le monde !'

// Translate multiple texts into British English:
$translations = $translator->translateText(
    ['お元気ですか？', '¿Cómo estás?'],
    null,
    'en-GB',
);
echo $translations[0]->text; // 'How are you?'
echo $translations[0]->detectedSourceLang; // 'ja'
echo $translations[1]->text; // 'How are you?'
echo $translations[1]->detectedSourceLang; // 'es'

// Translate into German with less and more Formality:
echo $translator->translateText('How are you?', null, 'de', ['formality' => 'less']); // 'Wie geht es dir?'
echo $translator->translateText('How are you?', null, 'de', ['formality' => 'more']); // 'Wie geht es Ihnen?'

文本翻译选项

将以下键作为关联数组提供给translateText函数的选项

  • split_sentences：指定如何将输入文本分割成句子，默认：'on'。
    • 'on'：使用换行符和标点符号将输入文本分割成句子。
    • 'off'：不将输入文本分割成句子。适用于每个输入文本只包含一个句子的应用程序。
    • 'nonewlines'：使用标点符号将输入文本分割成句子，但不使用换行符。
  • preserve_formatting：控制自动格式修正。设置为true以防止自动修正格式，默认：false。
  • formality：控制翻译是否倾向于非正式或正式语言。此选项仅适用于某些目标语言，请参阅可用语言列表。使用prefer_*选项在目标语言中应用正式性，否则回退到默认值。
    • 'less'：使用非正式语言。
    • 'more'：使用正式、更礼貌的语言。
    • 'default'：使用默认正式性。
    • 'prefer_less'：如果可用，则使用非正式语言，否则使用默认值。
    • 'prefer_more'：如果可用，则使用正式、更礼貌的语言，否则使用默认值。
  • tag_handling：在翻译之前解析的标签类型，选项是'html'和'xml'。
  • glossary：用于翻译的词汇表ID。

以下选项仅在tag_handling为'xml'时使用

  • outline_detection：指定false以禁用自动标签检测，默认为true。
  • splitting_tags：应用于将文本分割成句子的XML标签列表。标签可以是字符串数组（['tag1', 'tag2']），或以逗号分隔的字符串列表（'tag1,tag2'）。默认为空列表。
  • non_splitting_tags：不应用于将文本分割成句子的XML标签列表。格式和默认值与splitting_tags相同。
  • ignore_tags：包含不应翻译的内容的XML标签列表。格式和默认值与splitting_tags相同。

TranslateTextOptions类定义了上述选项的常量，例如TranslateTextOptions::FORMALITY定义为'formality'。

翻译文档

要翻译文档，请调用translateDocument()。前两个参数是输入和输出文件路径。

第三个和第四个参数是源语言代码和目标语言代码，它们与使用translateText()翻译文本时的用法完全相同。

translateDocument()的最后一个参数是可选的，用于指定额外的翻译选项，请参阅下面的文档翻译选项。

// Translate a formal document from English to German:
try {
    $translator->translateDocument(
        'Instruction Manual.docx',
        'Bedienungsanleitung.docx',
        'en',
        'de',
        ['formality' => 'more'],
    );
} catch (\DeepL\DocumentTranslationException $error) {
    // If the error occurs after the document was already uploaded,
    // documentHandle will contain the document ID and key
    echo 'Error occurred while translating document: ' . ($error->getMessage() ?? 'unknown error');
    if ($error->documentHandle) {
        $handle = $error->documentHandle;
        echo "Document ID: {$handle->documentId}, document key: {$handle->documentKey}";
    } else {
        echo 'Unknown document handle';
    }
}

translateDocument()封装了多个API调用：上传、轮询状态直到翻译完成，以及下载。如果您的应用程序需要单独执行这些步骤，则可以使用以下函数直接

  • uploadDocument(),
  • getDocumentStatus()（或waitUntilDocumentTranslationComplete()），以及
  • downloadDocument()

文档翻译选项

将选项作为关联数组提供给translateDocument函数，使用以下键

uploadDocument函数也支持这些选项。

TranslateDocumentOptions类定义了上述选项的常量，例如TranslateDocumentOptions::FORMALITY定义为'formality'。

词汇表

词汇表允许您使用用户定义的术语自定义翻译。您的帐户可以存储多个词汇表，每个词汇表都有一个用户指定的名称和一个唯一分配的ID。

创建词汇表

您可以使用 createGlossary() 函数创建包含所需术语和名称的词汇表。每个词汇表仅适用于单一的目标源语言对。注意：并非所有语言对都支持词汇表，有关更多信息，请参阅可用的词汇表语言列表。条目应指定为 GlossaryEntries 对象；您可以使用 GlossaryEntries::fromEntries 创建一个对象，使用关联数组，其中源术语作为键，目标术语作为值。

然后使用 createGlossary() 函数，带上词汇表名称、源和目标语言代码以及 GlossaryEntries。如果成功，词汇表将创建并存储在您的 DeepL 账户中，并返回一个包含 ID、名称、语言和条目计数的 GlossaryInfo 对象。

// Create an English to German glossary with two terms:
$entries = GlossaryEntries::fromEntries(['artist' => 'Maler', 'prize' => 'Gewinn']);
$myGlossary = $translator->createGlossary('My glossary', 'en', 'de', $entries);
echo "Created '$myGlossary->name' ($myGlossary->glossaryId) " .
    "$myGlossary->sourceLang to $myGlossary->targetLang " .
    "containing $myGlossary->entryCount entries";
// Example: Created 'My glossary' (559192ed-8e23-...) en to de containing 2 entries

您还可以使用 createGlossaryFromCsv() 函数上传从 DeepL 网站下载的词汇表。类似于 createGlossary，指定词汇表名称、源和目标语言代码，但不是指定术语作为关联数组，而是将 CSV 数据作为字符串指定。

// Read CSV data from a file, for example: "artist,Maler,en,de\nprize,Gewinn,en,de"
$csvData = file_get_contents('/path/to/glossary_file.csv');
$myCsvGlossary = $translator->createGlossaryFromCsv(
    'CSV glossary',
    'en',
    'de',
    $csvData,
)

API 文档 详细说明了预期的 CSV 格式。

获取、列出和删除存储的词汇表

还提供了获取、列出和删除存储词汇表的功能。

  • getGlossary() 函数接受一个词汇表 ID，并返回一个存储词汇表的 GlossaryInfo 对象，如果没有找到此类词汇表，则抛出异常。
  • listGlossaries() 返回一个与您所有存储词汇表对应的 GlossaryInfo 对象列表。
  • deleteGlossary() 函数接受一个词汇表 ID 或 GlossaryInfo 对象，并从服务器删除存储的词汇表，如果没有找到此类词汇表，则抛出异常。
// Retrieve a stored glossary using the ID
$glossaryId = '559192ed-8e23-...';
$myGlossary = $translator->getGlossary($glossaryId);

// Find and delete glossaries named 'Old glossary'
$glossaries = $translator->listGlossaries();
foreach ($glossaries as $glossary) {
    if ($glossary->name === 'Old glossary') {
        $translator->deleteGlossary($glossary);
    }
}

列出存储词汇表中的条目

GlossaryInfo 对象不包含词汇表条目，而是只包含在 entryCount 属性中的条目数量。

要列出存储词汇表内包含的条目，请使用 getGlossaryEntries() 函数，提供 GlossaryInfo 对象或词汇表 ID。返回一个 GlossaryEntries 对象；您可以使用 getEntries() 访问条目作为关联数组。

$entries = $translator->getGlossaryEntries($myGlossary);
print_r($entries->getEntries()); // Array ( [artist] => Maler, [prize] => Gewinn)

使用存储的词汇表

您可以通过设置 glossary 选项为词汇表 ID 或 GlossaryInfo 对象来使用存储的词汇表进行文本翻译。您还必须指定 sourceLang 参数（使用词汇表时必须指定）。

$text = 'The artist was awarded a prize.';
$withGlossary = $translator->translateText($text, 'en', 'de', ['glossary' => $myGlossary]);
echo $withGlossary->text; // "Der Maler wurde mit einem Gewinn ausgezeichnet."

// For comparison, the result without a glossary:
$withGlossary = $translator->translateText($text, null, 'de');
echo $withoutGlossary->text; // "Der Künstler wurde mit einem Preis ausgezeichnet."

使用存储的词汇表进行文档翻译的方式相同：设置 glossary 选项。也必须指定 sourceLang 参数。

$translator->translateDocument(
    $inFile, $outFile, 'en', 'de', ['glossary' => $myGlossary]
)

translateDocument() 和 translateDocumentUpload() 函数都支持 glossary 参数。

检查账户使用情况

要检查账户使用情况，请使用 getUsage() 函数。

返回的 Usage 对象包含最多三个使用子类型，具体取决于您的账户类型：character、document 和 teamDocument。对于 API 账户，character 将被设置，其他为 null。

每个使用子类型（如果设置）都有 count 和 limit 属性，分别表示使用量和最大量，还有一个 limitReached() 函数，用于检查使用量是否达到限制。顶级 Usage 对象有一个 anyLimitReached() 函数，用于检查所有使用子类型。

$usage = $translator->getUsage();
if ($usage->anyLimitReached()) {
    echo 'Translation limit exceeded.';
}
if ($usage->character) {
    echo 'Characters: ' . $usage->character->count . ' of ' . $usage->character->limit;
}
if ($usage->document) {
    echo 'Documents: ' . $usage->document->count . ' of ' . $usage->document->limit;
}

列出可用的语言

您可以使用 getSourceLanguages() 和 getTargetLanguages() 函数请求 DeepL 翻译器支持文本和文档的语言列表。它们都返回一个 Language 对象数组。

name 属性给出语言的英文名称，code 属性给出语言代码。只有对于目标语言，supportsFormality 属性才会出现，它是一个 bool，表示目标语言是否支持可选的 formality 参数。

$sourceLanguages = $translator->getSourceLanguages();
foreach ($sourceLanguages as $sourceLanguage) {
    echo $sourceLanguage->name . ' (' . $sourceLanguage->code . ')'; // Example: 'English (en)'
}

$targetLanguages = $translator->getTargetLanguages();
foreach ($targetLanguages as $targetLanguage) {
    if ($targetLanguage->supportsFormality) {
        echo $targetLanguage->name . ' (' . $targetLanguage->code . ') supports formality';
        // Example: 'German (de) supports formality'
    }
}

列出可用的词汇表语言

支持对一组语言对的术语表。要检索这些语言，请使用 getGlossaryLanguages() 函数，它返回一个 GlossaryLanguagePair 对象数组。每个对象都有 sourceLang 和 targetLang 属性，表示支持该对语言代码。

$glossaryLanguages = $translator->getGlossaryLanguages();
foreach ($glossaryLanguages as $glossaryLanguage) {
    echo "$glossaryLanguage->sourceLang to $glossaryLanguage->targetLang";
    // Example: "en to de", "de to en", etc.
}

您还可以在API 文档中找到支持的语言术语表列表。

请注意，术语表适用于所有目标区域变体：针对目标语言英语（'en'）的术语表支持翻译成美式英语（'en-US'）和英式英语（'en-GB'）。

配置

Translator 构造函数接受配置选项作为第二个参数，例如

$options = [ 'max_retries' => 5, 'timeout' => 10.0 ];
$translator = new \DeepL\Translator('YOUR_AUTH_KEY', $options);

提供以下键的关联数组作为选项

  • max_retries：每个函数调用中失败 HTTP 请求的最大重试次数。默认情况下，将重试 5 次。请参阅请求重试。
  • timeout：用于每个 HTTP 请求重试的连接超时时间（秒）。默认值为 10.0（10 秒）。
  • server_url：包含 DeepL API URL 的字符串，可以根据测试目的进行覆盖。默认情况下，URL 根据用户账户类型（免费或付费）选择。
  • headers：附加到每个 HTTP 请求的额外 HTTP 头。默认情况下，不使用额外头。请注意，自动添加了授权和 User-Agent 头，但可能被此选项覆盖。
  • proxy：指定代理服务器 URL。
  • logger：指定库应记录消息的PSR-3 兼容的记录器。

TranslatorOptions 类定义了上述选项的常量。

代理配置

您可以在创建 Translator 时使用 proxy 选项配置代理

$proxy = 'http://user:pass@10.10.1.10:3128';
$translator = new \DeepL\Translator('YOUR_AUTH_KEY', ['proxy' => $proxy]);

代理选项用于准备 cURL 请求时的 CURLOPT_PROXY 选项，请参阅cURL 文档。

日志记录

要启用日志记录，请将 PSR-3 兼容的记录器指定为 Translator 配置选项中的 'logger' 选项。

请求重试

由于短暂条件（例如，网络超时或高服务器负载）而失败的 DeepL API 请求将被重试。可以在使用 max_retries 选项构建 Translator 对象时配置最大重试次数。可以使用 timeout 选项控制每次请求尝试的超时时间。使用指数退避策略，因此多次失败的请求将产生延迟。

问题

如果您在使用库时遇到问题，或希望请求新功能，请打开一个问题。

开发

我们欢迎拉取请求，请阅读贡献指南。

测试

使用 phpunit 执行测试。测试使用由 DEEPL_AUTH_KEY 环境变量定义的 auth key 与 DeepL API 通信。

请注意，测试会对 DeepL API 进行请求，这些请求会消耗您的 API 使用量。

测试套件也可以配置为与由deepl-mock提供的模拟服务器进行通信。尽管大多数测试用例对两者都有效，但有些测试用例仅与DeepL API或模拟服务器一起工作，否则将跳过。需要模拟服务器的测试用例会触发服务器错误并测试客户端的错误处理。要使用deepl-mock执行测试，请在另一个终端中运行它，同时执行测试。使用phpunit执行测试，并定义DEEPL_MOCK_SERVER_PORT和DEEPL_SERVER_URL环境变量，以便引用模拟服务器。