README

DeepL API的官方PHP客户端库。

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

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

获取认证密钥

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

安装

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

composer require deeplcom/deepl-php

要求

该库官方支持PHP 7.3及以后版本。

从2024年开始，我们将停止对已达到官方生命周期的旧PHP版本的支持。您可以在此处找到PHP版本和支持时间表。要继续使用此库，您应升级到PHP 8.1+。

用法

构造一个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是检测到的源语言代码，
billedCharacters是计费文本的字符数。

// 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[0]->billedCharacters;  // 7 - the number of characters in the source text "お元気ですか？"
echo $translations[1]->text; // 'How are you?'
echo $translations[1]->detectedSourceLang; // 'es'
echo $translations[1]->billedCharacters; // 12 - the number of characters in the source text "¿Cómo estás?"

// 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'。
context：指定影响翻译的额外上下文，这些上下文本身不被翻译。context 参数中的字符不计入计费。请参阅API 文档以获取更多信息和使用示例。
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 函数的选项

formality：与文本翻译选项相同。
glossary：与文本翻译选项相同。
minification：一个 bool 值。如果设置为 true，库将尝试在通过 API 翻译之前最小化文档，如果文件包含大量媒体，则发送更小的文档。这目前仅支持 pptx 文件。请参阅文档最小化。请注意，这仅在高级 translateDocument 方法中起作用，而不是 uploadDocument。

uploadDocument 函数还支持这些选项。

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

文档压缩

在某些情况下，可能会得到大型文档文件（例如 PowerPoint 演示文稿或包含许多作者的 Word 文件，尤其是在大型组织中）。然而，DeepL API 对这些文件的大部分内容强制执行 30 MB 的限制（请参阅文档中的使用限制）。如果大部分大小来自文档中包含的媒体（例如图像、视频、动画），则文档压缩可以帮助。在这种情况下，库将创建一个临时目录以提取文档，用微小的占位符替换大型媒体，创建一个压缩文档，通过 API 进行翻译，并将原始媒体重新插入到原始文件中。请注意，这需要一些额外的（临时）磁盘空间，我们建议至少是待翻译文档大小的两倍。

要使用文档压缩，只需将选项传递给 translateDocument 函数

$translator->translateDocument(
    $inFile, $outFile, 'en', 'de', [TranslateDocumentOptions::ENABLE_DOCUMENT_MINIFICATION => true]
);

有关使用 uploadDocument、waitUntilDocumentTranslationComplete 和 downloadDocument 方法以及其他详细信息来使用文档压缩，请参阅 DocumentMinifier 类。

当前支持用于压缩的文档类型

pptx
docx

当前支持用于压缩的媒体类型

png
jpg
jpeg
emf
bmp
tiff
wdp
svg
gif
mp4
asf
avi
m4v
mpg
mpeg
wmv
mov
aiff
au
mid
midi
mp3
m4a
wav
wma

术语表

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

创建术语表

您可以使用 createGlossary() 使用您想要的术语和名称创建术语表。每个术语表适用于单个源-目标语言对。注意：术语表仅支持某些语言对，有关更多信息，请参阅可用术语表语言列表。条目应指定为 GlossaryEntries 对象；您可以使用 GlossaryEntries::fromEntries 使用关联数组（源术语作为键，目标术语作为值）创建一个。

然后使用术语表名称、源和目标语言代码以及 GlossaryEntries 调用 createGlossary()。如果成功，术语表将创建并存储在您的 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'）。

编写插件

如果您在使用此库的应用程序中，请使用app_info翻译器选项标识该应用程序，该选项需要应用程序的名称和版本

$options = ['app_info' => new \DeepL\AppInfo('my-custom-php-chat-client', '1.2.3')];
$translator = new \DeepL\Translator('YOUR_AUTH_KEY', $options);

此信息会在库调用DeepL API时传递。名称和版本都是必需的。请注意，通过headers翻译器选项设置User-Agent标题将覆盖此设置；如果需要使用此选项，请手动在User-Agent标题中标识您的应用程序。

配置

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的string，例如为了测试目的可以进行覆盖。默认情况下，URL根据用户账户类型（免费或付费）选择。
headers: 每个HTTP请求附加的额外HTTP头。默认情况下，不使用额外头。注意，自动添加授权和User-Agent头，但可能被此选项覆盖。
proxy: 指定代理服务器URL。
logger: 指定库应将消息记录到的兼容PSR-3的日志记录器。

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

代理配置

在构建Translator时，可以使用proxy选项配置代理。

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

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

日志记录

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

匿名平台信息

默认情况下，我们会在每个请求中发送有关客户端库运行的平台的一些基本信息，请参见此处的解释。这些数据是完全匿名的，仅用于改进我们的产品，不会跟踪任何个人用户。如果您不希望发送这些数据，可以在创建Translator对象时通过将选项中的send_platform_option标志设置为禁用。

$translator = new \DeepL\Translator('YOUR_AUTH_KEY', ['send_platform_info' => false]);

您还可以通过在选项中通过headers字段显式设置其值来完全自定义User-Agent头（这覆盖了send_platform_option选项）。例如：

$headers = [
    'Authorization' => "DeepL-Auth-Key YOUR_AUTH_KEY",
    'User-Agent' => 'my-custom-php-client',
];
$translator = new \DeepL\Translator('YOUR_AUTH_KEY', ['headers' => $headers]);

自定义HTTP客户端

如果您想设置我们不公开的特定HTTP选项（或以其他方式通过库对API调用进行更多控制），您可以配置库使用您选择的PSR-18兼容HTTP客户端。例如，为了在使用Guzzle代理时设置5.2秒的连接超时和7.4秒的读取超时。

$client = new \GuzzleHttp\Client([
    'connect_timeout' => 5.2,
    'read_timeout' => 7.4,
    'proxy' => 'http://localhost:8125'
]);
$translator = new \DeepL\Translator('YOUR_AUTH_KEY', [TranslatorOptions::HTTP_CLIENT => $client]);
$translator->getUsage(); // Or a translate call, etc

请求重试

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

问题

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

开发

我们欢迎Pull Requests，请阅读贡献指南。

测试

使用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以引用模拟服务器。

deeplcom / deepl-php

维护者

详细信息