Skip to main content

​
Overview

Tag handling v2 is an improved algorithm for translating XML and HTML content. Set tag_handling_version=v2 to enable it.

​
What’s New in v2

Tag handling v2 uses an algorithm that balances both translation quality and formatting. Sentences are now translated more naturally without being constrained by tag placement in the source text. It also handles edge cases around tag preservation, DOM hierarchy, and character escaping. V2 enforces strict XML parsing and will return an error if invalid XML is submitted.

​
Usage Examples

​
Translation with v2

Parameters
tag_handling=html, tag_handling_version=v2
Request
<!DOCTYPE html>
<html>
  <body>
    <h1>Welcome to Our Service</h1>
    <p>This is a <strong>premium</strong> feature.</p>
  </body>
</html>
Response
<!DOCTYPE html>
<html>
  <body>
    <h1>Willkommen bei unserem Service</h1>
    <p>Dies ist eine <strong>Premium</strong>-Funktion.</p>
  </body>
</html>

​
Strict XML Parsing

Tag handling v2 enforces strict XML parsing. If invalid XML is submitted, the API will return an error:

Invalid XML error response

Parameters
tag_handling=xml, tag_handling_version=v2
Request (Invalid XML)
<p>This tag is not closed properly</a>
Response (Error)
{
  "Message": "Tag handling parsing failed, please check input."
}
Only XML is strictly parsed. HTML is not strictly parsed.

​
Compatibility

Tag handling v2 is currently only compatible with the quality_optimized model type. Support for latency_optimized will be added in a future update.
Model Typev1 Supportv2 Support
quality_optimized✅✅
latency_optimized✅❌
When you set tag_handling_version to v2, the model_type is implicitly set to quality_optimized.
Requests that specify both model_type=latency_optimized and tag_handling_version=v2 will return an error.

​
Migration Guide

Tag handling is expected to give different results between v1 and v2. Thoroughly test your system and verify any differences in output before switching to v2 in production.

​
1. Test Your Content

Run v2 translations on representative samples of your content, especially:
  • Text with deep tag hierarchies
  • Text with inline markup, attributes, and special characters
  • Edge cases such as empty or self-closing tags

​
2. Compare Outputs

Compare v1 and v2 outputs, and make any updates needed to maintain your workflows.
  • Ensure that the tags are preserved correctly
  • Compare any differences in translation
  • Note any formatting changes

​
3. Validate XML Syntax

Since v2 enforces strict XML parsing:
  • Ensure all your XML input is well-formed
  • Add error handling for invalid XML responses
  • Update any XML generation logic if needed
For more information about XML and HTML tag handling:

​
FAQ

Q: What is the default tag handling version? A: Customers who had not used tag handling prior to 2025-12-01 default to v2. All other customers default to v1. Q: Should I upgrade to v2? A: Upgrading to v2 is strongly recommended and will provide improvements to both translation quality and structural correctness. Test thoroughly with your specific content before switching in production. Q: What happens if my XML is invalid? A: Tag handling v2 enforces strict XML parsing. Invalid XML will return an error response. Ensure your XML is well-formed before submission. Q: Can I switch back to v1 if needed? A: Yes, simply set tag_handling_version: v1 in your API requests. Q: Does v2 work with all DeepL API features? A: Tag handling v2 works with all standard API features including glossaries and formality settings. However, it currently only supports the quality_optimized model type. Q: Is HTML also strictly parsed? A: No, any HTML can be submitted for translation without throwing an error. Only XML is strictly parsed and requires valid XML.