PHPackages graffpl/deepl-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. graffpl/deepl-php ActiveLibrary[API Development](/categories/api) graffpl/deepl-php ================= Official DeepL API Client Library 1.0.1(3y ago)020MITPHPPHP >=7.3.0 Since Jan 10Pushed 3y agoCompare [ Source](https://github.com/graffpl/deepl-php)[ Packagist](https://packagist.org/packages/graffpl/deepl-php)[ RSS](/packages/graffpl-deepl-php/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (5)Versions (4)Used By (0) deepl-php ========= [](#deepl-php) [![Latest Stable Version](https://camo.githubusercontent.com/e5f526435f0f70d054bf244feb79e85ccb192c8cb244bceaa20aac95aec6e993/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f646565706c636f6d2f646565706c2d7068702e737667)](https://packagist.org/packages/deeplcom/deepl-php)[![Minimum PHP version](https://camo.githubusercontent.com/2fb385d9babdb8786f6057c2fa9d46a7fc86308ed192804090be74a56136c60a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f646565706c636f6d2f646565706c2d706870)](https://packagist.org/packages/deeplcom/deepl-php)[![License: MIT](https://camo.githubusercontent.com/0d72c4cb15193b9e2e0f21dfc6ce0c8a1f49edd2719e2f9550808afd5e329576/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c756576696f6c65742e737667)](https://github.com/DeepLcom/deepl-php/blob/main/LICENSE) Official PHP client library for the DeepL API. The [DeepL API](https://www.deepl.com/docs-api?utm_source=github&utm_medium=github-php-readme) 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 ----------------------------- [](#getting-an-authentication-key) To use deepl-php, you'll need an API authentication key. To get a key, [please create an account here](https://www.deepl.com/pro?utm_source=github&utm_medium=github-php-readme#developer). With a DeepL API Free account you can translate up to 500,000 characters/month for free. Installation ------------ [](#installation) To use this library in your project, install it using Composer: ``` composer require deeplcom/deepl-php ``` ### Requirements [](#requirements) The library officially supports PHP 7.3 and later. Usage ----- [](#usage) Construct a `Translator` object. The first argument is a string containing your API authentication key as found in your [DeepL Pro Account](https://www.deepl.com/pro-account/?utm_source=github&utm_medium=github-php-readme). 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](#configuration) for more information. ### Translating text [](#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](#text-translation-options)below. `translateText()` returns a `TextResult`, or an array of `TextResult`s 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 [](#text-translation-options) Provide options to the `translateText` function as an associative array, using the following keys: - `split_sentences`: specify how input text should be split into sentences, default: `'on'`. - `'on'`: input text will be split into sentences using both newlines and punctuation. - `'off'`: input text will not be split into sentences. Use this for applications where each input text contains only one sentence. - `'nonewlines'`: input text will be split into sentences using punctuation but not newlines. - `preserve_formatting`: controls automatic-formatting-correction. Set to `true`to prevent automatic-correction of formatting, default: `false`. - `formality`: controls whether translations should lean toward informal or formal language. This option is only available for some target languages, see [Listing available languages](#listing-available-languages). Use the `prefer_*` options to apply formality if it is available for the target language, or otherwise fallback to the default. - `'less'`: use informal language. - `'more'`: use formal, more polite language. - `'default'`: use default formality. - `'prefer_less'`: use informal language if available, otherwise default. - `'prefer_more'`: use formal, more polite language if available, otherwise default. - `tag_handling`: type of tags to parse before translation, options are `'html'`and `'xml'`. - `glossary`: glossary ID of glossary to use for translation. The following options are only used if `tag_handling` is `'xml'`: - `outline_detection`: specify `false` to disable automatic tag detection, default is `true`. - `splitting_tags`: list of XML tags that should be used to split text into sentences. Tags may be specified as an array of strings (`['tag1', 'tag2']`), or a comma-separated list of strings (`'tag1,tag2'`). The default is an empty list. - `non_splitting_tags`: list of XML tags that should not be used to split text into sentences. Format and default are the same as for `splitting_tags`. - `ignore_tags`: list of XML tags that containing content that should not be translated. Format and default are the same as for `splitting_tags`. The `TranslateTextOptions` class defines constants for the options above, for example `TranslateTextOptions::FORMALITY` is defined as `'formality'`. ### Translating documents [](#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](#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: - `uploadDocument()`, - `getDocumentStatus()` (or `waitUntilDocumentTranslationComplete()`), and - `downloadDocument()` #### Document translation options [](#document-translation-options) Provide options to the `translateDocument` function as an associative array, using the following keys: - `formality`: same as in [Text translation options](#text-translation-options). - `glossary`: same as in [Text translation options](#text-translation-options). The `uploadDocument` function also supports these options. The `TranslateDocumentOptions` class defines constants for the options above, for example `TranslateDocumentOptions::FORMALITY` is defined as `'formality'`. ### Glossaries [](#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 [](#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](#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](https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/?utm_source=github&utm_medium=github-php-readme) explains the expected CSV format in detail. #### Getting, listing and deleting stored glossaries [](#getting-listing-and-deleting-stored-glossaries) Functions to get, list, and delete stored glossaries are also provided: - `getGlossary()` takes a glossary ID and returns a `GlossaryInfo` object for a stored glossary, or raises an exception if no such glossary is found. - `listGlossaries()` returns a list of `GlossaryInfo` objects corresponding to all of your stored glossaries. - `deleteGlossary()` takes a glossary ID or `GlossaryInfo` object and deletes the stored glossary from the server, or raises an exception if no such glossary is found. ``` // 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 [](#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 [](#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 [](#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 [](#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 [](#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](https://www.deepl.com/docs-api/managing-glossaries/?utm_source=github&utm_medium=github-php-readme). 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'`). ### Configuration [](#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: - `max_retries`: the maximum number of failed HTTP requests to retry, per function call. By default, 5 retries are made. See [Request retries](#request-retries). - `timeout`: the number of seconds used as connection timeout for each HTTP request retry. The default value is `10.0` (10 seconds). - `server_url`: `string` containing the URL of the DeepL API, can be overridden for example for testing purposes. By default, the URL is selected based on the user account type (free or paid). - `headers`: extra HTTP headers attached to every HTTP request. By default, no extra headers are used. Note that Authorization and User-Agent headers are added automatically but may be overridden by this option. - `proxy`: specify a proxy server URL. - `logger`: specify a [`PSR-3` compatible logger](http://www.php-fig.org/psr/psr-3/) that the library should log messages to. The `TranslatorOptions` class defines constants for the options above. #### Proxy configuration [](#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](https://www.php.net/manual/en/function.curl-setopt.php). #### Logging [](#logging) To enable logging, specify a [`PSR-3` compatible logger](http://www.php-fig.org/psr/psr-3/) as the `'logger'` option in the `Translator` configuration options. ### Request retries [](#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 ------ [](#issues) If you experience problems using the library, or would like to request a new feature, please open an [issue](https://www.github.com/DeepLcom/deepl-php/issues). Development ----------- [](#development) We welcome Pull Requests, please read the [contributing guidelines](CONTRIBUTING.md). ### Tests [](#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](https://www.github.com/DeepLcom/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. ### Health Score 21 — LowBetter than 18% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity6 Limited adoption so far Community10 Small or concentrated contributor base Maturity43 Maturing project, gaining track record Bus Factor1 Top contributor holds 88.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 1224d ago Major Versions 0.0.1 → 1.0.02023-01-10 ### Community Maintainers ![](https://www.gravatar.com/avatar/60d8abed668520630c0085f029477d9624b8920e2a96345b9e387072aeafaa5c?d=identicon)[graffpl](/maintainers/graffpl) --- Top Contributors [![daniel-jones-dev](https://avatars.githubusercontent.com/u/38475049?v=4)](https://github.com/daniel-jones-dev "daniel-jones-dev (39 commits)")[![KrzysztofNiekrasz](https://avatars.githubusercontent.com/u/137209039?v=4)](https://github.com/KrzysztofNiekrasz "KrzysztofNiekrasz (2 commits)")[![Schleuse](https://avatars.githubusercontent.com/u/2717384?v=4)](https://github.com/Schleuse "Schleuse (2 commits)")[![MartkCz](https://avatars.githubusercontent.com/u/10145362?v=4)](https://github.com/MartkCz "MartkCz (1 commits)") --- Tags apitranslationtranslatordeepl ### Code Quality TestsPHPUnit Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/graffpl-deepl-php/health.svg) ``` [![Health](https://phpackages.com/badges/graffpl-deepl-php/health.svg)](https://phpackages.com/packages/graffpl-deepl-php) ``` ### Alternatives [deeplcom/deepl-php Official DeepL API Client Library 2616.2M66](/packages/deeplcom-deepl-php)[algolia/algoliasearch-client-php API powering the features of Algolia. 69333.0M114](/packages/algolia-algoliasearch-client-php)[chriskonnertz/deeply DeepLy is a PHP client for the DeepL.com translation API 230116.2k8](/packages/chriskonnertz-deeply)[statickidz/php-google-translate-free Google Translate Free library for PHP 289258.8k6](/packages/statickidz-php-google-translate-free)[scn/deepl-api-connector Unofficial PHP Client for the API of deepl.com 16275.2k6](/packages/scn-deepl-api-connector)[webit/w-firma-api wFirma.pl API 1820.2k](/packages/webit-w-firma-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)