Skip to content

v1.21.0

Latest

Choose a tag to compare

@github-actions github-actions released this 02 Nov 11:36

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(), replacing uploadDocument(),
    getDocumentStatus(), waitUntilDocumentTranslationComplete() and
    downloadDocument().
  • Added the timeout option (TranslateDocumentOptions::TIMEOUT, seconds) to
    translateDocument() and translateDocumentWaitUntilDone(). When it
    expires, translateDocumentWaitUntilDone() throws a DeepLException and
    translateDocument() a DocumentTranslationException with the document
    handle. Without it, both wait without limit as before.
  • Added the filename document 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, replacing style_id and
    translation_memory_id.
  • Added the DocumentStatusCode constants class for the values of
    DocumentStatus::$status, and DocumentStatus::$documentId, the
    document_id returned by the API, or null if the response does not
    include it.
  • Added the httpStatusCode and shouldRetry properties to DeepLException.
    httpStatusCode is the HTTP status of the failed response, or null if
    there was none. shouldRetry is true for HTTP 429, any 5xx status and
    transient connection failures; it was previously only set on
    ConnectionException.
  • Added Translator::isFreeAccountAuthKey() (also available on DeepLClient),
    replacing isAuthKeyFreeAccount().
  • Added the style_profile option (TranslateTextOptions::STYLE_PROFILE
    and TranslateDocumentOptions::STYLE_PROFILE) to translate text and
    documents with a style profile, given as an ID string or a StyleProfile.
  • Added the style_rule (TranslateTextOptions::STYLE_RULE) and
    translation_memory (TranslateTextOptions::TRANSLATION_MEMORY) text
    translation options, taking an ID string or a StyleRuleInfo /
    TranslationMemoryInfo. They replace style_id and translation_memory_id.
  • Added the constants classes Formality, SentenceSplittingMode,
    TagHandlingMode, TagHandlingVersion and ModelType for the values of the
    formality, split_sentences, tag_handling, tag_handling_version and
    model_type options. The options still accept any string.
  • Added TextResult::$tagHandlingVersion, the tag_handling_version returned
    by the API, or null if the response does not include it.
  • Added the DeepLAdminClient class 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
    an extra_body_parameters option (CreateDeveloperKeyOptions and
    DeveloperKeyOptions::EXTRA_BODY_PARAMETERS), added last to the JSON body.
    setDeveloperKeyUsageLimits() changes only the limits given with the
    DeveloperKeyUsageLimitsOptions keys, including speech-to-speech.
    DeveloperKey::$label, DeveloperKey::$usageLimits,
    KeyUsage::$apiKeyLabel, AdminUsageReport::$totalUsage,
    AdminUsageBreakdown::$speechToSpeechMinutes and
    CustomTagUsageBreakdown::$speechToSpeechMinutes are null when 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,
    CustomTagUsageBreakdown and CustomTagUsageAggregateBy.
  • Added language code constants for the target variants de-CH, de-DE,
    es-ES, fr-CA and fr-FR to LanguageCode.
  • Added support for the /v2/write/correct endpoint in the DeepLClient class:
    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_PARAMETERS adds
    parameters last to the request body, replacing fields with the same key.
  • Added the extra_body_parameters option
    (RephraseTextOptions::EXTRA_BODY_PARAMETERS) to rephraseText(), added
    last to the request body and replacing fields with the same key.
  • Added the WritingStyle and WritingTone constants classes for the values
    of the writing_style and tone rephrase options. Other strings are still
    accepted.
  • Added the TranslateDocumentOptions::OUTPUT_FORMAT option to request the
    file format of the translated document, for example docx. When it differs
    from the input file's format, ENABLE_DOCUMENT_MINIFICATION is ignored.
  • Added the TranslateDocumentOptions::ENABLE_WATERMARK option to add a
    "Translated by DeepL" watermark to translated docx and pdf documents.
  • Added the API Pro fields of getUsage() to Usage: apiKeyCharacter,
    speechToTextMinutes, speechToSpeechMinutes, startTime, endTime and
    products (an array of the new UsageProduct class). They are null when
    the response does not include them, for example for API Free accounts. The
    same holds for the fields of each UsageProduct.
  • Added support for the Spoken Terms API (/v3/spoken-terms) in the
    DeepLClient class: createSpokenTerms(), listSpokenTerms(),
    getSpokenTerms(), updateSpokenTerms(), getSpokenTermsEntries(),
    replaceSpokenTermsList(), deleteSpokenTerms() and
    deleteSpokenTermsList(), with the new classes SpokenTerms,
    SpokenTermsList, SpokenTermsEntries and SpokenTermsOptions.
    updateSpokenTerms() takes the new name and the term lists to merge as the
    options SpokenTermsOptions::NAME and SpokenTermsOptions::TERM_LISTS.
    createSpokenTerms(), updateSpokenTerms() and replaceSpokenTermsList()
    accept SpokenTermsOptions::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
    the DeepLClient class: listStyleProfiles(), createStyleProfile(),
    getStyleProfile(), updateStyleProfile() and deleteStyleProfile(), with
    the new classes StyleProfile, CreateStyleProfileOptions and
    UpdateStyleProfileOptions (which adds NAME). 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, StyleRuleInfo and
    TranslationMemoryInfo objects. Both options classes accept
    EXTRA_BODY_PARAMETERS. StyleProfile::$creationTime and $updatedTime
    are required: a response without a valid timestamp throws an
    InvalidContentException.
  • Added the LanguageResourceName constants class for the resource values of
    getLanguagesForResource() and LanguageResource::$resource, and the
    LanguageInclude constants class for its include values.
  • getLanguagesForResource() also accepts an options array as its second
    parameter, with the include option
    (GetLanguagesForResourceOptions::INCLUDE). The plain list of include values
    keeps working.
  • Added updateMultilingualGlossaryName(),
    updateMultilingualGlossaryDictionary(),
    updateMultilingualGlossaryDictionaryFromCsv() and
    replaceMultilingualGlossaryDictionaryFromCsv(). They take an optional
    options array, see MultilingualGlossaryOptions: EXTRA_BODY_PARAMETERS
    adds parameters to the JSON request body.
  • Added getMultilingualGlossaryDictionaryEntries(), returning the
    MultilingualGlossaryDictionaryEntries of one dictionary, or throwing
    GlossaryNotFoundException if the glossary has no such dictionary.
  • Added the TranslationMemoryJobStatus constants class for the values of
    TranslationMemoryJobResult::$status; the TranslationMemoryJobResult::STATUS_*
    constants refer to it.

Changed

  • Content-Type, Content-Length, Transfer-Encoding and Host in the
    headers option 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 a DeepLException; previously surrounding whitespace was sent and hid
    the :fx suffix of free keys.
  • Deprecated methods, options and option values now raise a silenced
    E_USER_DEPRECATED notice once per process (see Deprecated); previously
    none. Error handlers that report silenced deprecations now see them.
  • rephraseText() now sends the extra_body_parameters option; previously it
    was ignored.
  • MultilingualGlossaryDictionaryEntries terms 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
    raise InvalidContentException; previously some calls returned null,
    empty or partial results or raised PHP warnings. The affected methods are
    listed under Fixed.
  • ResourceFeature::$needsSourceSupport and $needsTargetSupport are now
    [secure] when the API omits them, as the API spec defines; previously null.
  • Removed the internal TranslationMemoryUtils class (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 a DocumentTranslationException if it does not;
    previously the upload request failed.
  • translateDocumentWaitUntilDone() and translateDocument() cut the last
    sleep of the wait to the timeout, so the wait no longer runs past it.
  • translateText() accepts the glossary and glossary_ids options without a
    source language; the API detects the source language. Document translation
    still requires sourceLang with a glossary.
  • The max_retries option now counts retries after the first attempt, as
    documented: max_retries => 5 (the default) sends a request at most 6
    times, and 0 disables retries. Previously it counted attempts, so the
    default made only 4 retries and max_retries => 1 made 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_parameters values 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, so true was sent as
    "1" and arrays failed. In document uploads (a multipart form), booleans are
    now sent as true/[secure] and arrays and objects as JSON. Objects with
    __toString() that are not JsonSerializable are still sent as their
    string, and a value that cannot be JSON-encoded throws a DeepLException.
  • Target languages en and pt are no longer rejected client-side; the API
    translates them to en-US and pt-PT respectively.
  • getSourceLanguages(), getTargetLanguages(), and getGlossaryLanguages()
    now call /v3/languages internally instead of the deprecated
    /v2/languages and /v2/glossary-language-pairs endpoints. The returned
    lists may include additional languages. No change to public method
    signatures or return types.

Deprecated

  • Deprecated Translator; construct a DeepLClient instead, which extends
    it. The methods of Translator move into DeepLClient in the next major
    version.
  • Deprecated GlossaryNotFoundException; catch its parent
    NotFoundException instead. Glossary requests still throw it until the next
    major version.
  • Deprecated Translator::uploadDocument(), getDocumentStatus(),
    waitUntilDocumentTranslationComplete() and downloadDocument(); use
    translateDocumentUpload(), translateDocumentGetStatus(),
    translateDocumentWaitUntilDone() and translateDocumentDownload(). They
    keep working, raise a silenced E_USER_DEPRECATED notice once per process,
    and will be removed in the next major version.
  • Deprecated the document translation options
    TranslateDocumentOptions::STYLE_ID and
    TranslateDocumentOptions::TRANSLATION_MEMORY_ID; use STYLE_RULE and
    TRANSLATION_MEMORY instead. They keep working, raise a silenced
    E_USER_DEPRECATED notice once per process, and will be removed in the
    next major version.
  • Deprecated the text translation options TranslateTextOptions::STYLE_ID
    (style_id) and TranslateTextOptions::TRANSLATION_MEMORY_ID
    (translation_memory_id); use STYLE_RULE and TRANSLATION_MEMORY instead.
    They keep working, raise a silenced E_USER_DEPRECATED notice once per
    process, and will be removed in the next major version.
  • Deprecated the split_sentences aliases 'on', 'default' and 'off';
    use the SentenceSplittingMode values '1', '0' and 'nonewlines'. The
    aliases keep working and raise a silenced E_USER_DEPRECATED notice once per
    process.
  • Deprecated Translator::isAuthKeyFreeAccount(); use
    isFreeAccountAuthKey() instead. It keeps working and raises a silenced
    E_USER_DEPRECATED notice once per process.
  • Deprecated the LanguageCode constants (for example LanguageCode::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_MINIFICATION option and the
    DocumentMinifier, DocumentMinificationException and
    DocumentDeminificationException classes. 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 silenced E_USER_DEPRECATED notice, once per
    process, when the option is set.
  • Deprecated DeepLClient::buildRephraseBodyParams() and the GlossaryUtils
    class, which are internal. They keep working; in the next major version
    buildRephraseBodyParams() becomes private and GlossaryUtils is removed
    from the public API. Use GlossaryEntries::fromTsv(),
    GlossaryEntries::fromEntries() and GlossaryEntries::convertToTsv()
    instead of GlossaryUtils.
  • Deprecated the LanguageResource::RESOURCE_* constants; use the
    LanguageResourceName constants instead. Deprecated
    LanguageSupport::INCLUDE_BETA and INCLUDE_EXTERNAL; use
    LanguageInclude::BETA and EXTERNAL instead. They keep working and will be
    removed in the next major version.
  • Deprecated getMultilingualGlossaryEntries(), which returns the dictionary
    in a one-element array; use getMultilingualGlossaryDictionaryEntries(). It
    keeps working and raises a silenced E_USER_DEPRECATED notice once per
    process.

Fixed

  • exportTranslationMemoryToFilepath() now throws a DeepLException before
    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-Agent header spelled in another case in the headers option,
    such as user-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_retries option now throws a DeepLException on construction.
    Previously no request was sent and the call failed with a TypeError.
  • Query string values encode a space as %20 instead of +, for example the
    lang of getSpokenTermsEntries() and the group_by of
    getUsageAnalytics().
  • translateDocument() wraps every failure in a DocumentTranslationException,
    including an unreadable input file and exceptions that are not a
    DeepLException, and copies httpStatusCode and shouldRetry from a
    DeepLException cause.
  • translateDocumentDownload() throws the API's error message on a failed
    download with the built-in cURL transport, instead of content: 1.
  • translateDocumentDownload() and downloadTranslationMemoryExport() throw a
    DeepLException with 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 as ErrorException. It
    now raises only a DeepLException, before any request.
  • translateDocument() calls uploadDocument(), getDocumentStatus(),
    waitUntilDocumentTranslationComplete() and downloadDocument() again when
    a subclass overrides them.
  • Fixed getUsage() raising a raw TypeError for a malformed response. A
    response body that is not a JSON object now raises
    InvalidContentException, and a usage type whose *_count or *_limit is
    missing, null or not numeric is left null instead.
  • Fixed translateDocumentUpload() (and the deprecated uploadDocument())
    accepting a non-string document_id or document_key in the response, for
    example a number; it now raises InvalidContentException.
  • Fixed the document ID not being URL-encoded in the request paths of
    translateDocumentGetStatus() and translateDocumentDownload() (and the
    deprecated getDocumentStatus() and downloadDocument()).
  • Fixed translateText() raising InvalidContentException when a translation
    has no billed_characters; TextResult::$billedCharacters is now null in
    that case.
  • Fixed custom headers with 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 TypeError or 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
    returns null when 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_minification and supports docx as well as pptx. The
    README no longer states a 30 MB document size limit.
  • Fixed downloadDocument() and downloadTranslationMemoryExport() returning
    without an error and without writing a file when the directory of the output
    file does not exist. They now throw a DeepLException before sending a
    request.
  • Fixed rephraseText() throwing a TypeError when called without a target
    language and without options.
  • Fixed rephraseText() and correctText() accepting malformed responses: a
    response without an improvements list returned null for a single text,
    fewer improvements than texts returned a short array, and an improvement
    without text returned an empty text. These now throw an
    InvalidContentException.
  • Fixed malformed responses of getSourceLanguages(), getTargetLanguages(),
    getGlossaryLanguages(), getLanguagesForResource() and
    getLanguageResources() raising PHP warnings or a TypeError (for example a
    missing lang, name or status, a feature that is not an object, or a
    body that is not a list), or silently treating a missing usable_as_source
    or usable_as_target as [secure]. They now raise InvalidContentException.
  • Fixed the LanguageCode::ENGLISH and LanguageCode::PORTUGUESE doc 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 of getMultilingualGlossaryEntries() 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
    or null). They now raise InvalidContentException.
  • Fixed CustomInstruction::$id being null when a returned custom instruction
    has no id, both from the custom instruction methods and in
    StyleRuleInfo::$customInstructions. A missing or non-string id now raises
    InvalidContentException.
  • Fixed the translation memory methods raising an undefined-key warning and a
    TypeError when a response lacks a required field (translation_memory_id,
    name or source_language of a translation memory; job_id of a job,
    import or export; upload_url of an import; the IDs, language and text of a
    segment or target segment). They now raise InvalidContentException.