--- title: "Request Translation" method: POST path: "/v2/translate" tags: ["TranslateText"] --- # Request Translation `POST /v2/translate` ## Request body - object - `text` string[], required — Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified many times in a single request, within the request size limit (128KiB). Translations are returned in the same order as they are requested. Each text in the array is translated independently — texts do not share context with each other. - `source_lang` string — Language of the text to be translated. If this parameter is omitted, the API will attempt to detect the language of the text and translate it. For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/docs/languages/using-the-languages-api). - `target_lang` string, required — The language into which the text should be translated. For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/docs/languages/using-the-languages-api). - `context` string — Additional context that can influence a translation but is not translated itself. Characters included in the `context` parameter will not be counted toward billing. - `show_billed_characters` boolean — When true, the response will include the billed_characters parameter, giving the number of characters from the request that will be counted by DeepL for billing purposes. - `split_sentences` '0' | '1' | 'nonewlines' — Sets whether the translation engine should first split the input into sentences. Possible values are: * 0 - no splitting at all, whole input is treated as one sentence * 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines - `preserve_formatting` boolean — Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. - `formality` 'default' | 'more' | 'less' | 'prefer_more' | 'prefer_less' — Sets whether the translated text should lean towards formal or informal language. This feature is only available for certain target languages. Setting this parameter with a target language that does not support formality will fail, unless one of the `prefer_...` options are used. Possible options are: * `default` (default) * `more` - for a more formal language * `less` - for a more informal language * `prefer_more` - for a more formal language if available, otherwise fallback to default formality * `prefer_less` - for a more informal language if available, otherwise fallback to default formality - `model_type` 'quality_optimized' | 'prefer_quality_optimized' | 'latency_optimized' — Specifies which DeepL model should be used for translation. - `glossary_id` string — Specify the glossary to use for the translation. **Important:** This requires the `source_lang` parameter to be set. The language pair of the glossary has to match the language pair of the request. Cannot be used together with `glossary_ids`. - `glossary_ids` string[] — Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation. **Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair. Cannot be used together with `glossary_id`. - `style_id` string — Specify the [style rule list](/docs/customize/using-style-rules) to use for the translation. **Important:** The target language has to match the language of the style rule list. All `model_type` values are supported. - `translation_memory_id` string, uuid — A unique ID assigned to a translation memory. - `translation_memory_threshold` integer — The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). - `custom_instructions` string[] — Specify a list 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. - `tag_handling` 'xml' | 'html' — Sets which kind of tags should be handled. Options currently available: * `xml` * `html` - `tag_handling_version` 'v2' | 'v1' — Sets which version of the tag handling algorithm should be used. Options currently available: * `v1`: Traditional algorithm (currently the default, will become deprecated in the future). * `v2`: Improved algorithm released in October 2025 (will become the default in the future). - `outline_detection` boolean — Disable the automatic detection of XML structure by setting the `outline_detection` parameter to `false` and selecting the tags that should be considered structure tags. This will split sentences using the `splitting_tags` parameter. - `enable_beta_languages` boolean — This parameter is maintained for backward compatibility and has no effect. - `non_splitting_tags` string[] — Comma-separated list of XML tags which never split sentences. - `splitting_tags` string[] — Comma-separated list of XML tags which always cause splits. - `ignore_tags` string[] — Comma-separated list of XML tags that indicate text not to be translated. ## Response `200` The translate function returns a JSON representation of the translations in the order the text parameters have been specified. - object - `translations` object[] - `detected_source_language` string — The language detected in the source text. It reflects the value of the `source_lang` parameter, when specified. - `text` string — The translated text. - `billed_characters` integer — Number of characters counted by DeepL for billing purposes. Only present if the show_billed_characters parameter is set to true. - `model_type_used` string — Indicates the translation model used. Only present if model_type parameter is included in the request. - `tag_handling_version` 'v2' | 'v1' — The version of the tag handling algorithm used for the translation. Only present when the `tag_handling` parameter (`xml` or `html`) is set. If you don't specify `tag_handling_version`, this shows the default that was applied. ## Other responses - `400` — Bad request. Please check error message and your parameters. - `403` — Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. This error is also returned when the API key is scoped but does not include the scope required for this endpoint. - `404` — The requested resource could not be found. - `413` — The request size exceeds the limit. - `414` — The request URL is too long. You can avoid this error by using a POST request instead of a GET request, and sending the parameters in the HTTP body. - `429` — Too many requests. Please wait and resend your request. - `456` — Quota exceeded. The character limit has been reached. - `500` — Internal error. - `504` — Resource currently unavailable. Try again later. - `529` — Too many requests. Please wait and resend your request. --- [API](https://skmtc.dev/deepl/apis/deepl-api-documentation.md) · [All operations](https://skmtc.dev/deepl/apis/deepl-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/deepl/deepl-api-documentation/revisions/3c422fcc9c54/schema)