Download the PHP package deeplcom/deepl-php without Composer

deepl-php

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:

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 DeepLClient 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.

DeepLClient 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 the following properties:

• text is the translated text,
• detectedSourceLang is the detected source language code,
• billedCharacters is the number of characters billed for the text.
• modelTypeUsed indicates the translation model used, but is null unless the model_type option is specified.

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. 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'.
• tag_handling_version: specifies which version of the tag handling algorithm to use. Options are v1 and v2. This parameter is only relevant when tag_handling is set to 'html' or 'xml'.
• context: specifies additional context to influence translations, that is not translated itself. Characters in the context parameter are not counted toward billing. See the API documentation for more information and example usage.
• custom_instructions: an array of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters. Important: The target language must be de, en, es, fr, it, ja, ko, zh or any variants of these languages. Note: Any request with the custom_instructions parameter enabled will use the quality_optimized model type as the default. Requests combining custom_instructions and model_type: latency_optimized will be rejected.
• glossary: glossary ID of glossary to use for translation.
• glossary_ids: an array of up to 5 glossaries to apply for translation, allowing multiple glossaries to be used in a single request. Each element may be a glossary ID string, a GlossaryInfo, or a MultilingualGlossaryInfo object. Requires the sourceLang argument to be set, and cannot be combined with the singular glossary option.
• style_id: specifies a style rule to use with translation, either as a string containing the ID of the style rule, or a StyleRuleInfo object.
• translation_memory_id: specifies a translation memory to use with translation, either as a string containing the ID of the translation memory, or a TranslationMemoryInfo object.
• translation_memory_threshold: an integer from 0 to 100 controlling the minimum matching percentage for translation memory matches. We recommend a minimum threshold of 75%.
• model_type: specifies the type of translation model to use, options are:
  • 'quality_optimized': use a translation model that maximizes translation quality, at the cost of response time. This option may be unavailable for some language pairs.
  • 'prefer_quality_optimized': use the highest-quality translation model for the given language pair.
  • 'latency_optimized': use a translation model that minimizes response time, at the cost of translation quality.

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'.

Rephrasing text

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

The second argument is the target language code, which is optional. If not provided, the text will be rephrased in its original language.

The last argument is optional and specifies extra rephrasing options, see Rephrasing options below.

rephraseText() returns a RephraseTextResult, or an array of RephraseTextResults corresponding to your input text(s), similar to translateText().

Rephrasing options

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

• writing_style: Sets the style for the rephrased text:

  • 'academic': Academic writing style
  • 'business': Business writing style
  • 'casual': Casual writing style
  • 'default': Default writing style
  • 'simple': Simple writing style
  • 'prefer_academic': Use academic style if available, otherwise default
  • 'prefer_business': Use business style if available, otherwise default
  • 'prefer_casual': Use casual style if available, otherwise default
  • 'prefer_simple': Use simple style if available, otherwise default
• tone: Sets the tone for the rephrased text:
  • 'confident': Confident tone
  • 'default': Default tone
  • 'diplomatic': Diplomatic tone
  • 'enthusiastic': Enthusiastic tone
  • 'friendly': Friendly tone
  • 'prefer_confident': Use confident tone if available, otherwise default
  • 'prefer_diplomatic': Use diplomatic tone if available, otherwise default
  • 'prefer_enthusiastic': Use enthusiastic tone if available, otherwise default
  • 'prefer_friendly': Use friendly tone if available, otherwise default

Note: Currently, you can only specify either a style OR a tone, not both at the same time.

The DeepLClientOptions class defines constants for these options:

• RephraseTextOptions::WRITING_STYLE
• RephraseTextOptions::TONE

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.

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

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

• formality: same as in Text translation options.
• glossary: same as in Text translation options.
• glossary_ids: same as in Text translation options. Apply up to 5 glossaries in a single document translation request.
• style_id: same as in Text translation options. Specify a style rule to use for the document translation, either as a style rule ID string or a StyleRuleInfo object.
• translation_memory_id: same as in Text translation options. Specify a translation memory to use for the document translation, either as a translation memory ID string or a TranslationMemoryInfo object.
• translation_memory_threshold: same as in Text translation options. An integer from 0 to 100 controlling the minimum matching percentage for translation memory matches.
• minification: A bool value. If set to true, the library will try to minify a document before translating it through the API, sending a smaller document if the file contains a lot of media. This is currently only supported for pptx files. See also Document minification. Note that this only works in the high-level translateDocument method, not uploadDocument. However, the behavior can be emulated by creating a new DocumentMinifier object and calling the minifier's methods in between.

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:

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.

v2 versus v3 glossary APIs

The newest version of the glossary APIs are the /v3 endpoints, allowing both editing functionality plus support for multilingual glossaries. New methods and objects have been created to support interacting with these new glossaries. Due to this new functionality, users are recommended to utilize these multilingual glossary methods. However, to continue using the v2 glossary API endpoints, please continue to use the existing endpoints in the Translator.php (e.g. createGlossary(), getGlossary(), etc).

To migrate to use the new multilingual glossary methods from the current monolingual glossary methods, please refer to this migration guide.

The following sections describe how to interact with multilingual glossaries using the new functionality:

Creating a glossary

You can create a glossary with your desired terms and name using createMultilingualGlossary(). ach glossary contains a list of dictionaries, where each dictionary 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 createMultilingualGlossary() with the glossary name, and its list of dictionaries. Each dictionary should have source and target language codes and the GlossaryEntries. If successful, the glossary is created and stored with your DeepL account, and a MultilingualGlossaryInfo object is returned including the ID, name, languages and entry count.

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

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:

• getMultilingualGlossary() takes a glossary ID and returns a MultilingualGlossaryInfo object for a stored glossary, or raises an exception if no such glossary is found.
• listMultilingualGlossaries() returns a list of MultilingualGlossaryInfo objects corresponding to all of your stored glossaries.
• deleteMultilingualGlossary() takes a glossary ID or MultilingualGlossaryInfo object and deletes the stored glossary from the server, or raises an exception if no such glossary is found.
• deleteMultilingualGlossaryDictionary() takes a glossary ID or MultilingualGlossaryInfo object to identify the glossary. Additionally takes in a source and target language or a MultilingualGlossaryDictionaryInfo object and deletes the stored dictionary from the server, or raises an exception if no such glossary dictionary is found.

Listing entries in a stored glossary

The MultilingualGlossaryDictionaryInfo 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 getMultilingualGlossaryEntries() providing either the MultilingualGlossaryInfo object or glossary ID and either a MultilingualGlossaryDictionaryInfo or source and target language pair:

Editing a glossary

Functions to edit stored glossaries are also provided:

• updateMultilingualGlossary() takes a glossary ID or MultilingualGlossaryInfo object, and optionally an array of MultilingualGlossaryDictionaryEntries to update or add to glossary and/or a new name for the glossary. For a given glossary dictionary, it will then either update the list of entries for that dictionary (either inserting new entries or replacing the target phrase for any existing entries) or will insert a new glossary dictionary if that language pair is not currently in the stored glossary.
• replaceMultilingualGlossaryDictionary() takes a glossary ID or MultilingualGlossaryInfo object, plus a MultilingualGlossaryDictionaryEntries object representing the updated glossary dictionary. It will then either set the dictionary to whatever was passed in as a parameter, completely replacing any pre-existing entries for that language pair.

Using a stored glossary

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

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

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

To apply multiple glossaries (up to 5) in a single request, use the glossary_ids option instead of glossary, for both text and document translation. Set it to an array of glossary IDs, GlossaryInfo, or MultilingualGlossaryInfo objects. The sourceLang argument is required, and glossary_ids cannot be combined with the singular glossary option:

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.

Listing available languages

You can request the list of languages supported by DeepL API 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.

Listing per-resource language support

getLanguagesForResource() queries the languages supported for a given DeepL resource (text translation, document translation, glossaries, voice, write, style rules), together with per-feature support information. It covers newer languages and features than getSourceLanguages() / getTargetLanguages(), and returns a single list per resource in which each LanguageSupport exposes usableAsSource and usableAsTarget flags.

To discover which features each resource exposes (and whether a feature needs source/target language support), use getLanguageResources():

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.

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').

Style Rules

Style rules allow you to customize your translations using a managed, shared list of rules for style, formatting, and more. Multiple style rules can be stored with your account, each with a user-specified name and a uniquely-assigned ID.

Creating a style rule

Use createStyleRule() to create a new style rule with a name and language. You can optionally pass configured rules and custom instructions:

Getting a style rule

Use getStyleRule() to retrieve a single style rule by its ID or a StyleRuleInfo object:

Listing all style rules

getAllStyleRules() returns a list of StyleRuleInfo objects corresponding to all of your stored style rules. The method accepts optional parameters: page (page number for pagination, 0-indexed), pageSize (number of items per page), and detailed (whether to include detailed configuration rules in the configuredRules property).

Updating a style rule

Use updateStyleRuleName() to rename a style rule, and updateStyleRuleConfiguredRules() to replace the configured rules:

Deleting a style rule

Use deleteStyleRule() to delete a style rule:

Managing custom instructions

Custom instructions allow you to add free-text prompts to a style rule. Use the custom instruction methods to create, get, update, and delete them:

Using a stored style rule

You can use a stored style rule for text translation by setting the style_id option to either the style rule ID or a StyleRuleInfo object:

Style rules are also supported for document translation. Set the style_id option on translateDocument() (or uploadDocument()) in the same way:

Translation Memories

Translation memories allow you to leverage previously translated segments to improve consistency and efficiency. Translation memories are managed on your account, each with a user-specified name and a uniquely-assigned ID.

Translation memories can also be uploaded and managed in the DeepL UI via https://www.deepl.com/translation-memory.

Listing all translation memories

listTranslationMemories() returns a list of TranslationMemoryInfo objects corresponding to all of your stored translation memories. The method accepts optional parameters: page (page number for pagination, 0-indexed) and pageSize (number of items per page).

Getting a translation memory

Use getTranslationMemory() to retrieve a single translation memory by its ID or a TranslationMemoryInfo object:

Listing the segments of a translation memory

listTranslationMemorySegments() returns one page of segments as a TranslationMemorySegments object. Pagination is cursor-based: omit page_cursor on the first call, then pass the previous response's nextPageCursor until it is null. Optionally filter with filter_text (at least 2 characters, matched against both source and target text) and filter_case_sensitive. Note that segmentCount is the translation-memory total and is not reduced by the filter.

Importing a translation memory

importTranslationMemoryFromFilepath() imports a TMX file as a new translation memory: it creates the import job, uploads the file, and waits for processing to finish. The returned TranslationMemoryJob carries the ID of the new translation memory. An import usually takes under a minute; the optional third argument is a maximum time in seconds to wait for it.

The three steps are also available separately, for example to upload the file yourself or to poll for progress. createTranslationMemoryImport() returns an upload URL that the file must be uploaded to before processing starts, then getTranslationMemoryJob() reports the status. Note that the upload URL is a pre-signed storage URL outside the DeepL API, so your authentication key is not sent to it.

Note that the job keeps reporting 'awaiting_input' for a while after the file has been uploaded, because the API detects the upload asynchronously. waitUntilTranslationMemoryJobDone() polls through that status like any other non-terminal one. A job whose file is never uploaded does not finish on its own, so pass a timeout in seconds as the second argument when that is a possibility.

Exporting a translation memory

exportTranslationMemoryToFilepath() exports a translation memory to a TMX file: it creates the export job, waits for it to finish, and writes the result.

As with import, the individual steps are available separately. Note that the API may reuse a previously completed export of an unchanged translation memory, indicated by reusedExisting.

Deleting a translation memory

Use deleteTranslationMemory() to delete a translation memory by its ID or a TranslationMemoryInfo object:

Using a translation memory for translation

You can use a translation memory for text translation by setting the translation_memory_id option to either the translation memory ID or a TranslationMemoryInfo object. Optionally, set translation_memory_threshold to control the minimum similarity score for matches:

Translation memories are also supported for document translation. Set the translation_memory_id (and optionally translation_memory_threshold) option on translateDocument() (or uploadDocument()) in the same way:

Writing a Plugin

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

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 DeeplClientOption will override this setting, if you need to use this, please manually identify your Application in the User-Agent header.

Configuration

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

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.
• 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 that the library should log messages to.

The DeepLClientOptions class defines constants for the options above.

Proxy configuration

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

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 DeepLClient 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 DeepLClient object by setting the send_platform_info flag in the options like so:

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_info option). For example::

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:

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 DeepLClient 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.

Formatting and fixing code

For formatting and fixing code style issues, run this command: