search

DeepLcom / deepl-php

Official PHP library for the DeepL language translation API.
MIT License
202 stars 23 forks source link
api deepl i18n language official php translation translator

readme

deepl-php

Latest Stable Version Minimum PHP version License: MIT

Official PHP client library for the DeepL API.

The DeepL API is a language translation API that allows other computer programs to send texts and documents to DeepL's servers and receive high-quality translations. This opens a whole universe of opportunities for developers: any translation product you can imagine can now be built on top of DeepL's best-in-class translation technology.

The DeepL PHP library offers a convenient way for applications written for PHP to interact with the DeepL API. We intend to support all API functions with the library, though support for new features may be added to the library after they’re added to the API.

Getting an authentication key

To use deepl-php, you'll need an API authentication key. To get a key, please create an account here. With a DeepL API Free account you can translate up to 500,000 characters/month for free.

Installation

To use this library in your project, install it using Composer:

composer require deeplcom/deepl-php

Requirements

The library officially supports PHP 7.3 and later.

Starting in 2024, we will drop support for older PHP versions that have reached official end-of-life. You can find the PHP versions and support timelines here. To continue using this library, you should update to PHP 8.1+.

Usage

Construct a Translator object. The first argument is a string containing your API authentication key as found in your DeepL Pro Account.

Be careful not to expose your key, for example when sharing source code.

$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 accepts options as the second argument, see Configuration for more information.

Translating text

To translate text, call translateText(). The first argument is a string containing the text you want to translate, or an array of strings if you want to translate multiple texts.

The second and third arguments are the source and target language codes. Language codes are case-insensitive strings according to ISO 639-1, for example 'de', 'fr', 'ja''. Some target languages also include the regional variant according to ISO 3166-1, for example 'en-US', or 'pt-BR'. The source language also accepts null, to enable auto-detection of the source language.

The last argument to translateText() is optional, and specifies extra translation options, see Text translation options below.

translateText() returns a TextResult, or an array of TextResults corresponding to your input text(s). TextResult has two properties: text is the translated text, and detectedSourceLang is the detected source language code.

// 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?'

Text translation options

Provide options to the translateText function as an associative array, using the following keys:

The following options are only used if tag_handling is 'xml':

The TranslateTextOptions class defines constants for the options above, for example TranslateTextOptions::FORMALITY is defined as 'formality'.

Translating documents

To translate documents, call translateDocument(). The first and second arguments are the input and output file paths.

The third and fourth arguments are the source and target language codes, and they work exactly the same as when translating text with translateText().

The last argument to translateDocument() is optional, and specifies extra translation options, see Document translation options below.

// 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() wraps multiple API calls: uploading, polling status until the translation is complete, and downloading. If your application needs to execute these steps individually, you can instead use the following functions directly:

Document translation options

Provide options to the translateDocument function as an associative array, using the following keys:

The uploadDocument function also supports these options.

The TranslateDocumentOptions class defines constants for the options above, for example TranslateDocumentOptions::FORMALITY is defined as 'formality'.

Document minification

In some contexts, one can end up with large document files (e.g. PowerPoint presentations or Word files with many contributors, especially in a larger organization). However, the DeepL API enforces a limit of 30 MB for most of these files (see Usage Limits in the docs). In the case that most of this size comes from media included in the documents (e.g. images, videos, animations), document minification can help. In this case, the library will create a temporary directory to extract the document into, replace the large media with tiny placeholders, create a minified document, translate that via the API, and re-insert the original media into the original file. Please note that this requires a bit of additional (temporary) disk space, we recommend at least 2x the file size of the document to be translated.

To use document minification, simply pass the option to the translateDocument function:

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

In order to use document minification with the lower-level uploadDocument, waitUntilDocumentTranslationComplete and downloadDocument methods as well as other details, see the DocumentMinifier class.

Currently supported document types for minification:

  1. pptx
  2. docx

Currently supported media types for minification:

  1. png
  2. jpg
  3. jpeg
  4. emf
  5. bmp
  6. tiff
  7. wdp
  8. svg
  9. gif
  10. mp4
  11. asf
  12. avi
  13. m4v
  14. mpg
  15. mpeg
  16. wmv
  17. mov
  18. aiff
  19. au
  20. mid
  21. midi
  22. mp3
  23. m4a
  24. wav
  25. wma

Glossaries

Glossaries allow you to customize your translations using user-defined terms. Multiple glossaries can be stored with your account, each with a user-specified name and a uniquely-assigned ID.

Creating a glossary

You can create a glossary with your desired terms and name using createGlossary(). Each glossary applies to a single source-target language pair. Note: Glossaries are only supported for some language pairs, see Listing available glossary languages for more information. The entries should be specified as a GlossaryEntries object; you can create one using GlossaryEntries::fromEntries using an associative array with the source terms as keys and the target terms as values.

Then use createGlossary() with the glossary name, source and target language codes and the GlossaryEntries. If successful, the glossary is created and stored with your DeepL account, and a GlossaryInfo object is returned including the ID, name, languages and entry count.

// 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

You can also upload a glossary downloaded from the DeepL website using createGlossaryFromCsv(). Similar to createGlossary, specify the glossary name, and source and target language codes, but instead of specifying the terms as an associative array, specify the CSV data as a string:

// 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,
)

The API documentation explains the expected CSV format in detail.

Getting, listing and deleting stored glossaries

Functions to get, list, and delete stored glossaries are also provided:

// 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);
    }
}

Listing entries in a stored glossary

The GlossaryInfo object does not contain the glossary entries, but instead only the number of entries in the entryCount property.

To list the entries contained within a stored glossary, use getGlossaryEntries() providing either the GlossaryInfo object or glossary ID. A GlossaryEntries object is returned; you can access the entries as an associative array using getEntries():

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

Using a stored glossary

You can use a stored glossary for text translation by setting the glossary option to either the glossary ID or GlossaryInfo object. You must also specify the sourceLang argument (it is required when using a glossary):

$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."

Using a stored glossary for document translation is the same: set the glossary option. The sourceLang argument must also be specified:

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

The translateDocument() and translateDocumentUpload() functions both support the glossary argument.

Checking account usage

To check account usage, use the getUsage() function.

The returned Usage object contains up to three usage subtypes, depending on your account type: character, document and teamDocument. For API accounts character will be set, the others null.

Each usage subtypes (if set) have count and limit properties giving the amount used and maximum amount respectively, and the limitReached() function that checks if the usage has reached the limit. The top level Usage object has the anyLimitReached() function to check all usage subtypes.

$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;
}

Listing available languages

You can request the list of languages supported by DeepL Translator for text and documents using the getSourceLanguages() and getTargetLanguages() functions. They both return an array of Language objects.

The name property gives the name of the language in English, and the code property gives the language code. The supportsFormality property only appears for target languages, and is a bool indicating whether the target language supports the optional formality parameter.

$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'
    }
}

Listing available glossary languages

Glossaries are supported for a subset of language pairs. To retrieve those languages use the getGlossaryLanguages() function, which returns an array of GlossaryLanguagePair objects. Each has sourceLang and targetLang properties indicating that that pair of language codes is supported.

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

You can also find the list of supported glossary language pairs in the API documentation.

Note that glossaries work for all target regional-variants: a glossary for the target language English ('en') supports translations to both American English ('en-US') and British English ('en-GB').

Writing a Plugin

If you use this library in an application, please identify the application with the app_info TranslatorOption, which needs the name and version of the app:

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

This information is passed along when the library makes calls to the DeepL API. Both name and version are required. Please note that setting the User-Agent header via the headers TranslatorOption will override this setting, if you need to use this, please manually identify your Application in the User-Agent header.

Configuration

The Translator constructor accepts configuration options as a second argument, for example:

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

Provide the options as an associative array with the following keys:

The TranslatorOptions class defines constants for the options above.

Proxy configuration

You can configure a proxy using the proxy option when constructing a Translator:

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

The proxy option is used for the CURLOPT_PROXY option when preparing the cURL request, see the documentation for cURL.

Logging

To enable logging, specify a PSR-3 compatible logger as the 'logger' option in the Translator configuration options.

Anonymous platform information

By default, we send some basic information about the platform the client library is running on with each request, see here for an explanation. This data is completely anonymous and only used to improve our product, not track any individual users. If you do not wish to send this data, you can opt-out when creating your Translator object by setting the send_platform_option flag in the options like so:

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

You can also customize the User-Agent header completely by setting its value explicitly in the options via the headers field (this overrides the send_platform_option option). For example::

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

Custom HTTP client

If you want to set specific HTTP options that we don't expose (or otherwise want more control over the API calls by the library), you can configure the library to use a PSR-18 compliant HTTP client of your choosing. For example, in order to use a connect timeout of 5.2 seconds and read timeout of 7.4 seconds while using a proxy with Guzzle:

$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

Request retries

Requests to the DeepL API that fail due to transient conditions (for example, network timeouts or high server-load) will be retried. The maximum number of retries can be configured when constructing the Translator object using the max_retries option. The timeout for each request attempt may be controlled using the timeout option. An exponential-backoff strategy is used, so requests that fail multiple times will incur delays.

Issues

If you experience problems using the library, or would like to request a new feature, please open an issue.

Development

We welcome Pull Requests, please read the contributing guidelines.

Tests

Execute the tests using phpunit. The tests communicate with the DeepL API using the auth key defined by the DEEPL_AUTH_KEY environment variable.

Be aware that the tests make DeepL API requests that contribute toward your API usage.

The test suite may instead be configured to communicate with the mock-server provided by deepl-mock. Although most test cases work for either, some test cases work only with the DeepL API or the mock-server and will be otherwise skipped. The test cases that require the mock-server trigger server errors and test the client error-handling. To execute the tests using deepl-mock, run it in another terminal while executing the tests. Execute the tests using phpunit with the DEEPL_MOCK_SERVER_PORT and DEEPL_SERVER_URL environment variables defined referring to the mock-server.