Repository navigation
TL;DR: new APIs in this release: the Admin API, spoken terms, style profiles and text correction.
Translation memories, style rules and multilingual glossaries gained many options and fixes.
Read Changed and Deprecated before upgrading; no public API is removed in this release.
Added
- Added the document translation step methods
translateDocumentUpload(),
translateDocumentGetStatus(),translateDocumentWaitUntilDone()and
translateDocumentDownload(), replacinguploadDocument(),
getDocumentStatus(),waitUntilDocumentTranslationComplete()and
downloadDocument(). - Added the
timeoutoption (TranslateDocumentOptions::TIMEOUT, seconds) to
translateDocument()andtranslateDocumentWaitUntilDone(). When it
expires,translateDocumentWaitUntilDone()throws aDeepLExceptionand
translateDocument()aDocumentTranslationExceptionwith the document
handle. Without it, both wait without limit as before. - Added the
filenamedocument translation option
(TranslateDocumentOptions::FILENAME), the file name sent with the upload.
It defaults to the base name of the input file path. - Added the
style_rule(TranslateDocumentOptions::STYLE_RULE) and
translation_memory(TranslateDocumentOptions::TRANSLATION_MEMORY)
document translation options, replacingstyle_idand
translation_memory_id. - Added the
DocumentStatusCodeconstants class for the values of
DocumentStatus::$status, andDocumentStatus::$documentId, the
document_idreturned by the API, ornullif the response does not
include it. - Added the
httpStatusCodeandshouldRetryproperties toDeepLException.
httpStatusCodeis the HTTP status of the failed response, ornullif
there was none.shouldRetryistruefor HTTP 429, any 5xx status and
transient connection failures; it was previously only set on
ConnectionException. - Added
Translator::isFreeAccountAuthKey()(also available onDeepLClient),
replacingisAuthKeyFreeAccount(). - Added the
style_profileoption (TranslateTextOptions::STYLE_PROFILE
andTranslateDocumentOptions::STYLE_PROFILE) to translate text and
documents with a style profile, given as an ID string or aStyleProfile. - Added the
style_rule(TranslateTextOptions::STYLE_RULE) and
translation_memory(TranslateTextOptions::TRANSLATION_MEMORY) text
translation options, taking an ID string or aStyleRuleInfo/
TranslationMemoryInfo. They replacestyle_idandtranslation_memory_id. - Added the constants classes
Formality,SentenceSplittingMode,
TagHandlingMode,TagHandlingVersionandModelTypefor the values of the
formality,split_sentences,tag_handling,tag_handling_versionand
model_typeoptions. The options still accept any string. - Added
TextResult::$tagHandlingVersion, thetag_handling_versionreturned
by the API, ornullif the response does not include it. - Added the
DeepLAdminClientclass for the Admin API. It must be created with
an admin API key and supports managing developer keys
(createDeveloperKey(),listDeveloperKeys(),deactivateDeveloperKey(),
renameDeveloperKey(),setDeveloperKeyUsageLimits()) and retrieving usage
analytics (getUsageAnalytics(),getCustomTagUsageAnalytics()).
createDeveloperKey()takes the label as an option
(CreateDeveloperKeyOptions::LABEL). All four developer key changes accept
anextra_body_parametersoption (CreateDeveloperKeyOptionsand
DeveloperKeyOptions::EXTRA_BODY_PARAMETERS), added last to the JSON body.
setDeveloperKeyUsageLimits()changes only the limits given with the
DeveloperKeyUsageLimitsOptionskeys, including speech-to-speech.
DeveloperKey::$label,DeveloperKey::$usageLimits,
KeyUsage::$apiKeyLabel,AdminUsageReport::$totalUsage,
AdminUsageBreakdown::$speechToSpeechMinutesand
CustomTagUsageBreakdown::$speechToSpeechMinutesarenullwhen the
response omits them.createDeveloperKey()is retried only when the request was not
sent: after HTTP 429, a DNS failure, a refused connection or a timeout
before the connection was established.
New public types:DeveloperKey,DeveloperKeyUsageLimits,
DeveloperKeyUsageLimitsOptions,CreateDeveloperKeyOptions,
DeveloperKeyOptions,AdminUsageReport,AdminUsageBreakdown,
AdminUsageGroupBy,KeyUsage,CustomTagUsageReport,CustomTagUsage,
CustomTagUsageBreakdownandCustomTagUsageAggregateBy. - Added language code constants for the target variants
de-CH,de-DE,
es-ES,fr-CAandfr-FRtoLanguageCode. - Added support for the
/v2/write/correctendpoint in theDeepLClientclass:
correctText(). This applies a minimal-change spelling and grammar
correction pass without rewriting the text for style or tone. It takes an
optional options array;CorrectTextOptions::EXTRA_BODY_PARAMETERSadds
parameters last to the request body, replacing fields with the same key. - Added the
extra_body_parametersoption
(RephraseTextOptions::EXTRA_BODY_PARAMETERS) torephraseText(), added
last to the request body and replacing fields with the same key. - Added the
WritingStyleandWritingToneconstants classes for the values
of thewriting_styleandtonerephrase options. Other strings are still
accepted. - Added the
TranslateDocumentOptions::OUTPUT_FORMAToption to request the
file format of the translated document, for exampledocx. When it differs
from the input file's format,ENABLE_DOCUMENT_MINIFICATIONis ignored. - Added the
TranslateDocumentOptions::ENABLE_WATERMARKoption to add a
"Translated by DeepL" watermark to translateddocxandpdfdocuments. - Added the API Pro fields of
getUsage()toUsage:apiKeyCharacter,
speechToTextMinutes,speechToSpeechMinutes,startTime,endTimeand
products(an array of the newUsageProductclass). They arenullwhen
the response does not include them, for example for API Free accounts. The
same holds for the fields of eachUsageProduct. - Added support for the Spoken Terms API (
/v3/spoken-terms) in the
DeepLClientclass:createSpokenTerms(),listSpokenTerms(),
getSpokenTerms(),updateSpokenTerms(),getSpokenTermsEntries(),
replaceSpokenTermsList(),deleteSpokenTerms()and
deleteSpokenTermsList(), with the new classesSpokenTerms,
SpokenTermsList,SpokenTermsEntriesandSpokenTermsOptions.
updateSpokenTerms()takes the new name and the term lists to merge as the
optionsSpokenTermsOptions::NAMEandSpokenTermsOptions::TERM_LISTS.
createSpokenTerms(),updateSpokenTerms()andreplaceSpokenTermsList()
acceptSpokenTermsOptions::EXTRA_BODY_PARAMETERS. Terms are trimmed before
they are checked and sent, and spoken terms IDs are URL-encoded in request
paths. - Added support for the style profile management API (
/v3/style_profiles) in
theDeepLClientclass:listStyleProfiles(),createStyleProfile(),
getStyleProfile(),updateStyleProfile()anddeleteStyleProfile(), with
the new classesStyleProfile,CreateStyleProfileOptionsand
UpdateStyleProfileOptions(which addsNAME). The options of
updateStyleProfile()are optional; without them an empty update is sent.
The glossary, style rule and translation memory ID lists take IDs or
GlossaryInfo/MultilingualGlossaryInfo,StyleRuleInfoand
TranslationMemoryInfoobjects. Both options classes accept
EXTRA_BODY_PARAMETERS.StyleProfile::$creationTimeand$updatedTime
are required: a response without a valid timestamp throws an
InvalidContentException. - Added the
LanguageResourceNameconstants class for the resource values of
getLanguagesForResource()andLanguageResource::$resource, and the
LanguageIncludeconstants class for its include values. getLanguagesForResource()also accepts an options array as its second
parameter, with theincludeoption
(GetLanguagesForResourceOptions::INCLUDE). The plain list of include values
keeps working.- Added
updateMultilingualGlossaryName(),
updateMultilingualGlossaryDictionary(),
updateMultilingualGlossaryDictionaryFromCsv()and
replaceMultilingualGlossaryDictionaryFromCsv(). They take an optional
options array, seeMultilingualGlossaryOptions:EXTRA_BODY_PARAMETERS
adds parameters to the JSON request body. - Added
getMultilingualGlossaryDictionaryEntries(), returning the
MultilingualGlossaryDictionaryEntriesof one dictionary, or throwing
GlossaryNotFoundExceptionif the glossary has no such dictionary. - Added the
TranslationMemoryJobStatusconstants class for the values of
TranslationMemoryJobResult::$status; theTranslationMemoryJobResult::STATUS_*
constants refer to it.
Changed
Content-Type,Content-Length,Transfer-EncodingandHostin the
headersoption are now ignored; previously they were sent and could break
the request.- HTTP 401 now raises
AuthorizationException, like 403; previously a generic
DeepLException. - 3xx responses now raise a
DeepLException; previously they were parsed as
successful results. - The authentication key is now trimmed, and a key that is empty after trimming
throws aDeepLException; previously surrounding whitespace was sent and hid
the:fxsuffix of free keys. - Deprecated methods, options and option values now raise a silenced
E_USER_DEPRECATEDnotice once per process (see Deprecated); previously
none. Error handlers that report silenced deprecations now see them. rephraseText()now sends theextra_body_parametersoption; previously it
was ignored.MultilingualGlossaryDictionaryEntriesterms are now trimmed, then
validated, when sent, and a source term that is a duplicate after trimming
is rejected; previously they were sent untrimmed.- Malformed API responses (a required field missing or of the wrong type) now
raiseInvalidContentException; previously some calls returnednull,
empty or partial results or raised PHP warnings. The affected methods are
listed under Fixed. ResourceFeature::$needsSourceSupportand$needsTargetSupportare now
[secure]when the API omits them, as the API spec defines; previouslynull.- Removed the internal
TranslationMemoryUtilsclass (marked@private); code
using it must stop. - Connection resets (
CURLE_RECV_ERROR) and broken pipes (CURLE_SEND_ERROR)
are now retried like other transient network failures. Proxy failures,
such as a proxy that cannot be resolved (CURLE_COULDNT_RESOLVE_PROXY), are
not retried. translateDocument()now checks that the input file exists before sending
any request and throws aDocumentTranslationExceptionif it does not;
previously the upload request failed.translateDocumentWaitUntilDone()andtranslateDocument()cut the last
sleep of the wait to thetimeout, so the wait no longer runs past it.translateText()accepts theglossaryandglossary_idsoptions without a
source language; the API detects the source language. Document translation
still requiressourceLangwith a glossary.- The
max_retriesoption now counts retries after the first attempt, as
documented:max_retries => 5(the default) sends a request at most 6
times, and0disables retries. Previously it counted attempts, so the
default made only 4 retries andmax_retries => 1made none. - DNS resolution failures (
CURLE_COULDNT_RESOLVE_HOST) are now retried like
other transient network failures.createDeveloperKey()retries them too, as such a request was not
sent. - The User-Agent platform information no longer includes the cURL version, and
has a space between the OS version and the machine type:
deepl-php/<version> (<os>) php/<version>. extra_body_parametersvalues are sent as given in JSON request bodies
(text translation): booleans, numbers, arrays and objects keep their JSON
type. Previously every value was converted to a string, sotruewas sent as
"1"and arrays failed. In document uploads (a multipart form), booleans are
now sent astrue/[secure]and arrays and objects as JSON. Objects with
__toString()that are notJsonSerializableare still sent as their
string, and a value that cannot be JSON-encoded throws aDeepLException.- Target languages
enandptare no longer rejected client-side; the API
translates them toen-USandpt-PTrespectively. getSourceLanguages(),getTargetLanguages(), andgetGlossaryLanguages()
now call/v3/languagesinternally instead of the deprecated
/v2/languagesand/v2/glossary-language-pairsendpoints. The returned
lists may include additional languages. No change to public method
signatures or return types.
Deprecated
- Deprecated
Translator; construct aDeepLClientinstead, which extends
it. The methods ofTranslatormove intoDeepLClientin the next major
version. - Deprecated
GlossaryNotFoundException; catch its parent
NotFoundExceptioninstead. Glossary requests still throw it until the next
major version. - Deprecated
Translator::uploadDocument(),getDocumentStatus(),
waitUntilDocumentTranslationComplete()anddownloadDocument(); use
translateDocumentUpload(),translateDocumentGetStatus(),
translateDocumentWaitUntilDone()andtranslateDocumentDownload(). They
keep working, raise a silencedE_USER_DEPRECATEDnotice once per process,
and will be removed in the next major version. - Deprecated the document translation options
TranslateDocumentOptions::STYLE_IDand
TranslateDocumentOptions::TRANSLATION_MEMORY_ID; useSTYLE_RULEand
TRANSLATION_MEMORYinstead. They keep working, raise a silenced
E_USER_DEPRECATEDnotice once per process, and will be removed in the
next major version. - Deprecated the text translation options
TranslateTextOptions::STYLE_ID
(style_id) andTranslateTextOptions::TRANSLATION_MEMORY_ID
(translation_memory_id); useSTYLE_RULEandTRANSLATION_MEMORYinstead.
They keep working, raise a silencedE_USER_DEPRECATEDnotice once per
process, and will be removed in the next major version. - Deprecated the
split_sentencesaliases'on','default'and'off';
use theSentenceSplittingModevalues'1','0'and'nonewlines'. The
aliases keep working and raise a silencedE_USER_DEPRECATEDnotice once per
process. - Deprecated
Translator::isAuthKeyFreeAccount(); use
isFreeAccountAuthKey()instead. It keeps working and raises a silenced
E_USER_DEPRECATEDnotice once per process. - Deprecated the
LanguageCodeconstants (for exampleLanguageCode::GERMAN).
Pass the language code string instead, for example'de', or use
getSourceLanguages()/getTargetLanguages(). The constants keep working
and will be removed in the next major version. - Deprecated document minification: the
TranslateDocumentOptions::ENABLE_DOCUMENT_MINIFICATIONoption and the
DocumentMinifier,DocumentMinificationExceptionand
DocumentDeminificationExceptionclasses. They keep working and will be
removed in the next major version; the DeepL API accepts larger documents
(see https://developers.deepl.com/docs/resources/usage-limits).
translateDocument()raises a silencedE_USER_DEPRECATEDnotice, once per
process, when the option is set. - Deprecated
DeepLClient::buildRephraseBodyParams()and theGlossaryUtils
class, which are internal. They keep working; in the next major version
buildRephraseBodyParams()becomes private andGlossaryUtilsis removed
from the public API. UseGlossaryEntries::fromTsv(),
GlossaryEntries::fromEntries()andGlossaryEntries::convertToTsv()
instead ofGlossaryUtils. - Deprecated the
LanguageResource::RESOURCE_*constants; use the
LanguageResourceNameconstants instead. Deprecated
LanguageSupport::INCLUDE_BETAandINCLUDE_EXTERNAL; use
LanguageInclude::BETAandEXTERNALinstead. They keep working and will be
removed in the next major version. - Deprecated
getMultilingualGlossaryEntries(), which returns the dictionary
in a one-element array; usegetMultilingualGlossaryDictionaryEntries(). It
keeps working and raises a silencedE_USER_DEPRECATEDnotice once per
process.
Fixed
exportTranslationMemoryToFilepath()now throws aDeepLExceptionbefore
creating the export job if a file already exists at the output path or its
directory does not exist or is not writable. Previously it failed only after
the export job had run.- Fixed a
User-Agentheader spelled in another case in theheadersoption,
such asuser-agent, raising an undefined-key warning on construction and
failing translation memory uploads and export downloads. The custom
User-Agent is now sent to the storage URLs as well. - A negative
max_retriesoption now throws aDeepLExceptionon construction.
Previously no request was sent and the call failed with aTypeError. - Query string values encode a space as
%20instead of+, for example the
langofgetSpokenTermsEntries()and thegroup_byof
getUsageAnalytics(). translateDocument()wraps every failure in aDocumentTranslationException,
including an unreadable input file and exceptions that are not a
DeepLException, and copieshttpStatusCodeandshouldRetryfrom a
DeepLExceptioncause.translateDocumentDownload()throws the API's error message on a failed
download with the built-in cURL transport, instead ofcontent: 1.translateDocumentDownload()anddownloadTranslationMemoryExport()throw a
DeepLExceptionwith a custom HTTP client when the output file cannot be
fully written, instead of leaving a truncated file and returning.- Fixed
waitUntilTranslationMemoryJobDone()running up to 5 seconds past its
timeout; the last sleep is now shortened to the deadline. - Fixed
importTranslationMemoryFromFilepath()emitting a PHP warning for an
input file that exists but cannot be read, which error handlers that turn
warnings into exceptions (Laravel, Symfony) raised asErrorException. It
now raises only aDeepLException, before any request. translateDocument()callsuploadDocument(),getDocumentStatus(),
waitUntilDocumentTranslationComplete()anddownloadDocument()again when
a subclass overrides them.- Fixed
getUsage()raising a rawTypeErrorfor a malformed response. A
response body that is not a JSON object now raises
InvalidContentException, and a usage type whose*_countor*_limitis
missing,nullor not numeric is leftnullinstead. - Fixed
translateDocumentUpload()(and the deprecateduploadDocument())
accepting a non-stringdocument_idordocument_keyin the response, for
example a number; it now raisesInvalidContentException. - Fixed the document ID not being URL-encoded in the request paths of
translateDocumentGetStatus()andtranslateDocumentDownload()(and the
deprecatedgetDocumentStatus()anddownloadDocument()). - Fixed
translateText()raisingInvalidContentExceptionwhen a translation
has nobilled_characters;TextResult::$billedCharactersis nownullin
that case. - Fixed custom
headerswith a different letter case (for example
user-agent) being sent in addition to the default header instead of
replacing it. - Fixed malformed API responses raising PHP warnings, a
TypeErroror a raw
\Exception(for example a missing field or an invalid timestamp) in
translateText(),uploadDocument(),getDocumentStatus(), the glossary,
multilingual glossary, spoken terms and style rule methods. They now raise
InvalidContentException.translateText()with a single text no longer
returnsnullwhen the response has no translations. - Fixed
translateText()changing the process-wide
mb_substitute_character()setting; the caller's value is now restored. - Fixed the README entry of the document minification option: it is named
enable_document_minificationand supportsdocxas well aspptx. The
README no longer states a 30 MB document size limit. - Fixed
downloadDocument()anddownloadTranslationMemoryExport()returning
without an error and without writing a file when the directory of the output
file does not exist. They now throw aDeepLExceptionbefore sending a
request. - Fixed
rephraseText()throwing aTypeErrorwhen called without a target
language and without options. - Fixed
rephraseText()andcorrectText()accepting malformed responses: a
response without animprovementslist returnednullfor a single text,
fewer improvements than texts returned a short array, and an improvement
withouttextreturned an empty text. These now throw an
InvalidContentException. - Fixed malformed responses of
getSourceLanguages(),getTargetLanguages(),
getGlossaryLanguages(),getLanguagesForResource()and
getLanguageResources()raising PHP warnings or aTypeError(for example a
missinglang,nameorstatus, a feature that is not an object, or a
body that is not a list), or silently treating a missingusable_as_source
orusable_as_targetas[secure]. They now raiseInvalidContentException. - Fixed the
LanguageCode::ENGLISHandLanguageCode::PORTUGUESEdoc comments,
which said these codes may only be used as source languages. - Fixed the glossary ID not being URL-encoded in the request paths of the
multilingual glossary methods, and the source and target language not being
URL-encoded in the query ofgetMultilingualGlossaryEntries()and
deleteMultilingualGlossaryDictionary(). - Fixed
updateMultilingualGlossary()sending[]instead of{}as the
request body when neither a name nor dictionaries are given. - Fixed
getMultilingualGlossaryEntries()failing on a dictionary without
entries, and on returned terms that do not pass the validation applied to
entries sent to the API. Returned entries are now read as they are. - Fixed the style rule and custom instruction methods raising a
TypeError
when the response body is valid JSON but not an object (for example a string
ornull). They now raiseInvalidContentException. - Fixed
CustomInstruction::$idbeingnullwhen a returned custom instruction
has noid, both from the custom instruction methods and in
StyleRuleInfo::$customInstructions. A missing or non-stringidnow raises
InvalidContentException. - Fixed the translation memory methods raising an undefined-key warning and a
TypeErrorwhen a response lacks a required field (translation_memory_id,
nameorsource_languageof a translation memory;job_idof a job,
import or export;upload_urlof an import; the IDs, language and text of a
segment or target segment). They now raiseInvalidContentException.