Download the PHP package deeplcom/deepl-php without Composer
On this page you can find all versions of the php package deeplcom/deepl-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download deeplcom/deepl-php
More information about deeplcom/deepl-php
Files in deeplcom/deepl-php
Informations about the package deepl-php
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 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.
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 TextResult
s
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.
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 totrue
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 theprefer_*
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'
.context
: specifies additional context to influence translations, that is not translated itself. Characters in thecontext
parameter are not counted toward billing. See the API documentation for more information and example usage.glossary
: glossary ID of glossary to use for translation.
The following options are only used if tag_handling
is 'xml'
:
outline_detection
: specifyfalse
to disable automatic tag detection, default istrue
.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 forsplitting_tags
.ignore_tags
: list of XML tags that containing content that should not be translated. Format and default are the same as forsplitting_tags
.
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.
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()
(orwaitUntilDocumentTranslationComplete()
), anddownloadDocument()
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.minification
: Abool
value. If set totrue
, 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 forpptx
files. See also Document minification. Note that this only works in the high-leveltranslateDocument
method, notuploadDocument
.
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:
pptx
docx
Currently supported media types for minification:
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
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.
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:
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:
getGlossary()
takes a glossary ID and returns aGlossaryInfo
object for a stored glossary, or raises an exception if no such glossary is found.listGlossaries()
returns a list ofGlossaryInfo
objects corresponding to all of your stored glossaries.deleteGlossary()
takes a glossary ID orGlossaryInfo
object and deletes the stored glossary from the server, or raises an exception if no such glossary is found.
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()
:
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):
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.
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 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.
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'
).
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:
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:
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 is10.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 aPSR-3
compatible logger that the library should log messages to.
The TranslatorOptions
class defines constants for the options above.
Proxy configuration
You can configure a proxy using the proxy
option when constructing a
Translator
:
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:
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::
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 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.
All versions of deepl-php with dependencies
psr/log Version ^1.1 || ^2.0 || ^3.0
psr/http-client Version ^1.0
php-http/discovery Version ^1.18
ext-json Version *
ext-curl Version *
ext-mbstring Version *
psr/http-client-implementation Version *
psr/http-factory-implementation Version *
php-http/multipart-stream-builder Version ^1.3