DeepLcom · shirgoldbird · Dec 15, 2025 · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025
diff --git a/docs/xml-and-html-handling/tag-handling-v2.mdx b/docs/xml-and-html-handling/tag-handling-v2.mdx
@@ -1,26 +1,184 @@
 ---
 title: "New: XML/HTML handling v2"
-description: "Information on the improved version 2 of tag-handling translations"
+description: "Learn about the benefits of tag handling v2 and how to migrate."
 ---
 
-In 2025, we completely overhauled the tag-handling algorithm that backs translation of XML and HTML in the DeepL API.
+## Overview
 
-The new **tag handling v2** represents a major step forward for customers who need best-in-class XML and HTML tag handling.
-To enable it and benefit from all the improvements, set the 'tag_handling_version' parameter to 'v2'.
-Our updates ensure the best possible translation quality across all use cases.
+Tag handling v2 is an improved algorithm for translating XML and HTML content. Set `tag_handling_version=v2` to enable it.
 
-As a result of these major updates, tag handling is expected to give different results when v2 is used. 
-Before switching to `v2`, thoroughly test your system and verify any differences in output.
+## What's New in v2
 
-Additionally, v2 enforces strict parsing of XML. If invalid XML is submitted, the API will return an error.
+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.
 
-<Info>
-  Please note that after 1 December 2025, new customers will default to v2. Existing customers will continue to default to v1 for the time being.
-</Info>
+V2 enforces strict XML parsing and will return an error if invalid XML is submitted.
 
-<Info>
-  As of now, tag handling v2 is only compatible with the <a href="/api-reference/translate#param-model-type">quality-optimized model type</a>.
-  When you set `tag_handling_version` to `v2`, the `model_type` is implicitly set to `quality_optimized`. 
+## Usage Examples
 
+### Translation with v2
+
+<Tabs>
+  <Tab title="HTML">
+    ```text Parameters
+    tag_handling=html, tag_handling_version=v2
+    ```
+
+    ```markup Request
+    <!DOCTYPE html>
+    <html>
+      <body>
+        <h1>Welcome to Our Service</h1>
+        <p>This is a <strong>premium</strong> feature.</p>
+      </body>
+    </html>
+    ```
+
+    ```markup Response
+    <!DOCTYPE html>
+    <html>
+      <body>
+        <h1>Willkommen bei unserem Service</h1>
+        <p>Dies ist eine <strong>Premium</strong>-Funktion.</p>
+      </body>
+    </html>
+    ```
+  </Tab>
+  <Tab title="XML: Simple Markup">
+    ```text Parameters
+    tag_handling=xml, tag_handling_version=v2
+    ```
+
+    ```markup Request
+    Press <b>Continue</b> to advance.
+    ```
+
+    ```markup Response
+    Drücken Sie <b>„Weiter",</b> um fortzufahren.
+    ```
+  </Tab>
+  <Tab title="XML: With Attributes">
+    ```text Parameters
+    tag_handling=xml, tag_handling_version=v2
+    ```
+
+    ```markup Request
+    <x id="17">Please welcome the participants</x> to today's meeting.
+    ```
+
+    ```markup Response
+    <x id="17">Bitte begrüßen Sie die Teilnehmer</x> an der heutigen Sitzung.
+    ```
+  </Tab>
+  <Tab title="XML: Nested Tags">
+    ```text Parameters
+    tag_handling=xml, tag_handling_version=v2
+    ```
+
+    ```markup Request
+    The firm said it had been conducting an <a>internal <b>investigation</b></a> for several months.
+    ```
+
+    ```markup Response
+    Das Unternehmen gab an, dass es seit mehreren Monaten eine <a>interne <b>Untersuchung</b></a> durchgeführt habe.
+    ```
+  </Tab>
+</Tabs>
+
+### Strict XML Parsing
+
+Tag handling v2 enforces strict XML parsing. If invalid XML is submitted, the API will return an error:
+
+<Card title="Invalid XML error response">
+  ```text Parameters
+  tag_handling=xml, tag_handling_version=v2
+  ```
+
+  ```markup Request (Invalid XML)
+  <p>This tag is not closed properly</a>
+  ```
+
+  ```json Response (Error)
+  {
+    "Message": "Tag handling parsing failed, please check input."
+  }
+  ```
+</Card>
+
+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 Type | v1 Support | v2 Support |
+|------------|:----------:|:----------:|
+| `quality_optimized` | ✅ | ✅ |
+| `latency_optimized` | ✅ | ❌ |
+
+When you set `tag_handling_version` to `v2`, the `model_type` is implicitly set to `quality_optimized`.
+
+<Warning>
   Requests that specify both `model_type=latency_optimized` and `tag_handling_version=v2` will return an error.
-</Info>
+</Warning>
+
+## 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
+
+## Related Documentation
+
+For more information about XML and HTML tag handling:
+
+- [HTML Handling](/docs/xml-and-html-handling/html)
+- [XML Handling](/docs/xml-and-html-handling/xml)
+- [Structured XML Content](/docs/xml-and-html-handling/structured-content)
+
+## 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.