From a3a6b7ea24311aa505afd425c0fb1ee2b71d19db Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Tue, 14 Apr 2026 16:48:26 -0400 Subject: [PATCH 1/5] docs: restructure IA around product lines (Phase 1) Reorganize ~95 documentation pages from topic-based sections (Getting Started, Best Practices, XML and HTML Handling, Resources) into product-line sections (Translate API, Admin API) with cross-cutting sections (Going to Production, Cookbooks, Changelog). Documentation tab changes: - Dissolve Best Practices, Learning & How-Tos, XML and HTML Handling, and Resources sections - Create Translate API section with subsections: Text Translation, Document Translation, Customizations, Structured Content, Languages - Create Admin API, Going to Production, Cookbooks, Changelog sections - Add Test with Postman to Developer Tools group - Add Enable Beta Languages to nav (was hidden) API Reference tab changes: - Replace single "API Reference" group with product-line top-level groups: Translate API, Write API, Voice API, Admin API - Rename "Translate Speech in Realtime" to "Voice API" - Add DEPRECATED tag to Monolingual Glossaries v2 group - Add BETA tag to v3 Languages group - Add service specification updates pages for Write and Voice APIs Also: - Add "API Pricing" and "Manage Keys" to navbar - Add 69 redirects from old URLs to new locations - Fix 11 broken internal links caused by page moves Co-Authored-By: Claude Opus 4.6 (1M context) --- api-reference/improve-text.mdx | 4 +- api-reference/translate.mdx | 2 +- api-reference/usage-and-quota.mdx | 4 +- docs.json | 442 ++++++++---------- .../control-costs.mdx} | 0 .../manage-api-keys.mdx} | 0 ...ap-and-release-notes.mdx => changelog.mdx} | 16 +- .../cookbook.mdx => cookbooks.mdx} | 0 .../automate-game-localization-godot.mdx} | 0 .../build-a-document-translator-java.mdx} | 0 .../build-a-translation-proxy-nodejs.mdx} | 2 +- .../build-a-usage-dashboard.mdx} | 0 .../translate-google-sheets.mdx} | 0 .../use-deepl-with-llm-agents-mcp.mdx} | 0 docs/getting-started/about.mdx | 2 +- docs/getting-started/auth.mdx | 2 +- docs/getting-started/intro.mdx | 2 +- .../error-handling.mdx | 2 +- .../pre-production-checklist.mdx | 4 +- .../solve-cors-errors.mdx} | 0 .../usage-limits.mdx | 0 .../breaking-changes-change-notices.mdx | 2 +- .../write-effective-instructions.mdx} | 0 .../glossaries/set-up-a-glossary.mdx} | 0 .../use-translation-memories.mdx} | 0 .../handle-errors-and-large-files.mdx} | 0 .../languages}/enable-beta-languages.mdx | 0 .../languages}/language-release-process.mdx | 0 .../languages}/supported-languages.mdx | 0 .../customize-xml-outline-detection.mdx} | 0 .../handle-html-content.mdx} | 0 .../handle-xml-content.mdx} | 0 .../how-tag-handling-works.mdx} | 0 .../text-translation/detect-languages.mdx} | 0 .../translate-between-variants.mdx} | 0 .../text-translation/translate-text.mdx} | 0 .../use-context-for-better-results.mdx} | 0 .../use-placeholder-tags.mdx} | 0 38 files changed, 225 insertions(+), 259 deletions(-) rename docs/{best-practices/cost-control.mdx => admin-api/control-costs.mdx} (100%) rename docs/{getting-started/managing-api-keys.mdx => admin-api/manage-api-keys.mdx} (100%) rename docs/{resources/roadmap-and-release-notes.mdx => changelog.mdx} (94%) rename docs/{learning-how-tos/cookbook.mdx => cookbooks.mdx} (100%) rename docs/{learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot.mdx => cookbooks/automate-game-localization-godot.mdx} (100%) rename docs/{learning-how-tos/cookbook/java-document-translator.mdx => cookbooks/build-a-document-translator-java.mdx} (100%) rename docs/{learning-how-tos/cookbook/nodejs-proxy.mdx => cookbooks/build-a-translation-proxy-nodejs.mdx} (93%) rename docs/{learning-how-tos/cookbook/usage-analytics-dashboard.mdx => cookbooks/build-a-usage-dashboard.mdx} (100%) rename docs/{learning-how-tos/cookbook/google-sheets.mdx => cookbooks/translate-google-sheets.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications.mdx => cookbooks/use-deepl-with-llm-agents-mcp.mdx} (100%) rename docs/{best-practices => going-to-production}/error-handling.mdx (86%) rename docs/{best-practices => going-to-production}/pre-production-checklist.mdx (93%) rename docs/{best-practices/cors-requests.mdx => going-to-production/solve-cors-errors.mdx} (100%) rename docs/{resources => going-to-production}/usage-limits.mdx (100%) rename docs/{best-practices/custom-instructions.mdx => translate-api/customizations/custom-instructions/write-effective-instructions.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/glossaries-in-the-real-world.mdx => translate-api/customizations/glossaries/set-up-a-glossary.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/how-to-use-translation-memories.mdx => translate-api/customizations/translation-memories/use-translation-memories.mdx} (100%) rename docs/{best-practices/document-translations.mdx => translate-api/document-translation/handle-errors-and-large-files.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides => translate-api/languages}/enable-beta-languages.mdx (100%) rename docs/{resources => translate-api/languages}/language-release-process.mdx (100%) rename docs/{getting-started => translate-api/languages}/supported-languages.mdx (100%) rename docs/{xml-and-html-handling/customized-xml-outline-detection.mdx => translate-api/structured-content/customize-xml-outline-detection.mdx} (100%) rename docs/{xml-and-html-handling/html.mdx => translate-api/structured-content/handle-html-content.mdx} (100%) rename docs/{xml-and-html-handling/structured-content.mdx => translate-api/structured-content/handle-xml-content.mdx} (100%) rename docs/{xml-and-html-handling/tag-handling-v2.mdx => translate-api/structured-content/how-tag-handling-works.mdx} (100%) rename docs/{best-practices/language-detection.mdx => translate-api/text-translation/detect-languages.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/translating-between-variants.mdx => translate-api/text-translation/translate-between-variants.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/translation-beginners-guide.mdx => translate-api/text-translation/translate-text.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/how-to-use-context-parameter.mdx => translate-api/text-translation/use-context-for-better-results.mdx} (100%) rename docs/{learning-how-tos/examples-and-guides/placeholder-tags.mdx => translate-api/text-translation/use-placeholder-tags.mdx} (100%) diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx index 0b9898c7..fc03654f 100644 --- a/api-reference/improve-text.mdx +++ b/api-reference/improve-text.mdx @@ -163,7 +163,7 @@ The `/write/rephrase` endpoint returns a JSON object with Improvements under the #### Does Cost Control factor in Write API usage? -Yes. If you set a [Cost Control limit](/docs/best-practices/cost-control), it will be enforced against a *sum of Translate API + Write API characters*. At this time, it is not possible to set separate Translate API and Write API cost control limits. +Yes. If you set a [Cost Control limit](/docs/admin-api/control-costs), it will be enforced against a *sum of Translate API + Write API characters*. At this time, it is not possible to set separate Translate API and Write API cost control limits. #### Does the /usage endpoint response include Write API characters? @@ -175,4 +175,4 @@ Yes! The Write API is accessed using the same API keys in [the API Keys tab](htt #### Can I see DeepL Write API usage in my reporting? -We've added a new column to the [API key-level usage report](/docs/getting-started/managing-api-keys#get-api-key-level-usage) that breaks out text improvement characters separately. The character counts in the [Usage tab](https://www.deepl.com/your-account/usage) of your API account are a sum of both Translate *and* Write characters; these are not yet broken out separately. +We've added a new column to the [API key-level usage report](/docs/admin-api/manage-api-keys#get-api-key-level-usage) that breaks out text improvement characters separately. The character counts in the [Usage tab](https://www.deepl.com/your-account/usage) of your API account are a sum of both Translate *and* Write characters; these are not yet broken out separately. diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 8b7e9f45..3b570e5a 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -295,7 +295,7 @@ error. The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages. - Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/best-practices/custom-instructions). + Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/translate-api/customizations/custom-instructions/write-effective-instructions). diff --git a/api-reference/usage-and-quota.mdx b/api-reference/usage-and-quota.mdx index f7c3dbb1..98048879 100644 --- a/api-reference/usage-and-quota.mdx +++ b/api-reference/usage-and-quota.mdx @@ -9,11 +9,11 @@ Retrieve usage information **within the current billing period** together with t * Text and document translation characters consumed in the current billing period in total _and_ for the API key used to make the request * Text improvement (`/write`) characters consumed in the current billing period in total _and_ for the API key used to make the request * Total characters consumed in the current billing period by the API key used to make the request -* The key-level character limit for the API key used to make the request, if applicable (if a [key-level usage limit](../docs/getting-started/managing-api-keys#set-api-key-level-usage-limits) is set, it will be reflected in the `api_key_character_limit` field in the response; `1000000000000` will be returned if no key-level limit is set) +* The key-level character limit for the API key used to make the request, if applicable (if a [key-level usage limit](/docs/admin-api/manage-api-keys#set-api-key-level-usage-limits) is set, it will be reflected in the `api_key_character_limit` field in the response; `1000000000000` will be returned if no key-level limit is set) * The current billing period start timestamp * The current billing period end timestamp * Total characters consumed in the current billing period -* Subscription-level character limit that applies to the current billing period (if [Cost Control](../docs/best-practices/cost-control.md) is set, it will be reflected in the `character_limit` field in the response; `1000000000000` will be returned if no limit is set) +* Subscription-level character limit that applies to the current billing period (if [Cost Control](/docs/admin-api/control-costs) is set, it will be reflected in the `character_limit` field in the response; `1000000000000` will be returned if no limit is set) An example request and response is shown below. diff --git a/docs.json b/docs.json index a3f9567a..d85d9a4c 100644 --- a/docs.json +++ b/docs.json @@ -38,92 +38,113 @@ "group": "Getting Started", "pages": [ "docs/getting-started/intro", - "docs/getting-started/about", + "docs/getting-started/your-first-api-request", "docs/getting-started/auth", - "docs/getting-started/regional-endpoints", { "group": "Developer Tools", "pages": [ "docs/getting-started/client-libraries", "docs/getting-started/deepl-cli", - "docs/getting-started/deepl-mcp-server" + "docs/getting-started/deepl-mcp-server", + "docs/getting-started/test-your-api-requests-with-postman" ] }, - "docs/getting-started/managing-api-keys", - "docs/getting-started/your-first-api-request", - "docs/getting-started/test-your-api-requests-with-postman", - "docs/getting-started/supported-languages" + "docs/getting-started/regional-endpoints" ] }, { - "group": "Learning & How Tos", + "group": "Translate API", "pages": [ { - "group": "Cookbook", + "group": "Text Translation", "pages": [ - "docs/learning-how-tos/cookbook", - "docs/learning-how-tos/cookbook/google-sheets", - "docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot", - "docs/learning-how-tos/cookbook/java-document-translator", - "docs/learning-how-tos/cookbook/usage-analytics-dashboard", - "docs/learning-how-tos/cookbook/nodejs-proxy" + "docs/translate-api/text-translation/translate-text", + "docs/translate-api/text-translation/use-context-for-better-results", + "docs/translate-api/text-translation/translate-between-variants", + "docs/translate-api/text-translation/use-placeholder-tags", + "docs/translate-api/text-translation/detect-languages" ] }, { - "group": "Guides", + "group": "Document Translation", "pages": [ - "docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api", - "docs/learning-how-tos/examples-and-guides/translation-beginners-guide", - "docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter", - "docs/learning-how-tos/examples-and-guides/translating-between-variants", - "docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world", - "docs/learning-how-tos/examples-and-guides/placeholder-tags", - "docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications", - "docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories" + "docs/translate-api/document-translation/handle-errors-and-large-files" + ] + }, + { + "group": "Customizations", + "pages": [ + { + "group": "Glossaries", + "pages": [ + "docs/translate-api/customizations/glossaries/set-up-a-glossary" + ] + }, + { + "group": "Custom instructions", + "pages": [ + "docs/translate-api/customizations/custom-instructions/write-effective-instructions" + ] + }, + { + "group": "Translation memories", + "pages": [ + "docs/translate-api/customizations/translation-memories/use-translation-memories" + ] + } + ] + }, + { + "group": "Structured Content", + "pages": [ + "docs/translate-api/structured-content/handle-xml-content", + "docs/translate-api/structured-content/handle-html-content", + "docs/translate-api/structured-content/customize-xml-outline-detection", + "docs/translate-api/structured-content/how-tag-handling-works" + ] + }, + { + "group": "Languages", + "pages": [ + "docs/translate-api/languages/supported-languages", + "docs/translate-api/languages/enable-beta-languages", + "docs/translate-api/languages/language-release-process" ] } ] }, { - "group": "Best Practices", + "group": "Admin API", "pages": [ - "docs/best-practices/error-handling", - "docs/best-practices/cors-requests", - "docs/best-practices/document-translations", - "docs/best-practices/language-detection", - "docs/best-practices/cost-control", - "docs/best-practices/pre-production-checklist", - "docs/best-practices/custom-instructions" + "docs/admin-api/manage-api-keys", + "docs/admin-api/control-costs" ] }, { - "group": "XML and HTML handling", + "group": "Going to Production", "pages": [ - "docs/xml-and-html-handling/xml", - "docs/xml-and-html-handling/structured-content", - "docs/xml-and-html-handling/customized-xml-outline-detection", - "docs/xml-and-html-handling/html", - "docs/xml-and-html-handling/tag-handling-v2" + "docs/going-to-production/pre-production-checklist", + "docs/going-to-production/error-handling", + "docs/going-to-production/solve-cors-errors", + "docs/going-to-production/usage-limits" ] }, { - "group": "Resources", + "group": "Cookbooks", "pages": [ - "docs/resources/roadmap-and-release-notes", - "docs/resources/usage-limits", - "docs/resources/deepl-developer-community", - { - "group": "Breaking changes (change notices)", - "pages": [ - "docs/resources/breaking-changes-change-notices", - "docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites", - "docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key", - "docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods" - ] - }, - "docs/resources/language-release-process", - "docs/resources/alpha-and-beta-features", - "docs/resources/open-api-spec" + "docs/cookbooks", + "docs/cookbooks/automate-game-localization-godot", + "docs/cookbooks/build-a-translation-proxy-nodejs", + "docs/cookbooks/build-a-document-translator-java", + "docs/cookbooks/build-a-usage-dashboard", + "docs/cookbooks/use-deepl-with-llm-agents-mcp", + "docs/cookbooks/translate-google-sheets" + ] + }, + { + "group": "Changelog", + "pages": [ + "docs/changelog" ] } ] @@ -132,17 +153,17 @@ "tab": "API Reference", "groups": [ { - "group": "API Reference", + "group": "Translate API", "pages": [ { - "group": "Translate text", + "group": "Translate Text", "pages": [ "api-reference/translate", "api-reference/translate/request-translation" ] }, { - "group": "Translate documents", + "group": "Translate Documents", "pages": [ "api-reference/document", "api-reference/document/upload-and-translate-a-document", @@ -150,13 +171,6 @@ "api-reference/document/download-translated-document" ] }, - { - "group": "Improve text", - "pages": [ - "api-reference/improve-text", - "api-reference/improve-text/request-text-improvement" - ] - }, { "group": "Glossaries", "pages": [ @@ -171,7 +185,8 @@ "api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id", "api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries", { - "group": "Manage Monolingual Glossaries", + "group": "Monolingual Glossaries v2", + "tag": "DEPRECATED", "pages": [ "api-reference/glossaries", "api-reference/glossaries/v2-vs-v3-endpoints", @@ -185,13 +200,7 @@ ] }, { - "group": "Translation memory", - "pages": [ - "api-reference/translation-memory/list-translation-memories" - ] - }, - { - "group": "Style rules", + "group": "Style Rules", "pages": [ "api-reference/style-rules", "api-reference/style-rules/list-all-style-rules", @@ -207,19 +216,19 @@ ] }, { - "group": "Retrieve usage and quota", + "group": "Translation Memory", "pages": [ - "api-reference/usage-and-quota", - "api-reference/usage-and-quota/check-usage-and-limits" + "api-reference/translation-memory/list-translation-memories" ] }, { - "group": "Retrieve languages", + "group": "Languages", "pages": [ "api-reference/languages", "api-reference/languages/retrieve-supported-languages", { - "group": "Retrieve supported languages by product (v3) [BETA]", + "group": "Retrieve supported languages by product (v3)", + "tag": "BETA", "pages": [ "api-reference/languages/retrieve-supported-languages-by-product", "api-reference/languages/language-feature-use-cases", @@ -231,31 +240,52 @@ ] } ] + } + ] + }, + { + "group": "Write API", + "pages": [ + "api-reference/improve-text", + "api-reference/improve-text/request-text-improvement", + "api-reference/improve-text/deepl-write-api-service-specification-updates" + ] + }, + { + "group": "Voice API", + "pages": [ + "api-reference/voice", + "api-reference/voice/request-session", + "api-reference/voice/websocket-streaming", + "api-reference/voice/reconnect-session", + "api-reference/voice/deepl-voice-api-service-specification-updates" + ] + }, + { + "group": "Admin API", + "pages": [ + { + "group": "Usage & Quota", + "pages": [ + "api-reference/usage-and-quota", + "api-reference/usage-and-quota/check-usage-and-limits" + ] }, + "api-reference/admin-api", + "api-reference/admin-api/managing-admin-keys", { - "group": "Admin API", + "group": "Managing developer keys", "pages": [ - "api-reference/admin-api", - "api-reference/admin-api/managing-admin-keys", "api-reference/admin-api/managing-developer-keys", "api-reference/admin-api/managing-developer-keys/create-key", "api-reference/admin-api/managing-developer-keys/get-keys", "api-reference/admin-api/managing-developer-keys/deactivate-key", "api-reference/admin-api/managing-developer-keys/rename-key", - "api-reference/admin-api/managing-developer-keys/set-usage-limits", - "api-reference/admin-api/organization-usage-analytics", - "api-reference/admin-api/get-usage-analytics" + "api-reference/admin-api/managing-developer-keys/set-usage-limits" ] }, - { - "group": "Translate Speech in Realtime", - "pages": [ - "api-reference/voice", - "api-reference/voice/request-session", - "api-reference/voice/websocket-streaming", - "api-reference/voice/reconnect-session" - ] - } + "api-reference/admin-api/organization-usage-analytics", + "api-reference/admin-api/get-usage-analytics" ] } ] @@ -269,8 +299,12 @@ "navbar": { "links": [ { - "label": "DeepL Web Translator", - "href": "https://www.deepl.com/translator" + "label": "API Pricing", + "href": "https://www.deepl.com/pro-api#api-pricing" + }, + { + "label": "Manage Keys", + "href": "https://www.deepl.com/your-account/keys" }, { "label": "Contact Us", @@ -305,150 +339,82 @@ } }, "redirects": [ - { - "source": "/docs/api-reference/improve-text/openapi-spec-for-text-improvement", - "destination": "/api-reference/improve-text/request-text-improvement" - }, - { - "source": "/docs/api-reference/languages/openapi-spec-for-retrieving-languages", - "destination": "/api-reference/languages/retrieve-supported-languages" - }, - { - "source": "/docs/api-reference/translate/openapi-spec-for-text-translation", - "destination": "/api-reference/translate/request-translation" - }, - { - "source": "/docs/api-reference/document/openapi-spec-for-document-translation", - "destination": "/api-reference/document/upload-and-translate-a-document" - }, - { - "source": "/docs/api-reference/glossaries/openapi-spec-for-glossary-management", - "destination": "/api-reference/multilingual-glossaries/create-a-glossary" - }, - { - "source": "/docs/api-reference/glossaries/glossaries/openapi-spec-for-glossary-management", - "destination": "/api-reference/glossaries/create-a-glossary" - }, - { - "source": "/docs/api-reference/usage-and-quota/openapi-spec-for-retrieving-usage-and-quota", - "destination": "/api-reference/usage-and-quota/check-usage-and-limits" - }, - { - "source": "/docs/api-reference/glossaries/glossaries", - "destination": "/api-reference/glossaries" - }, - { - "source": "/docs/api-reference", - "destination": "/api-reference" - }, - { - "source": "/docs/api-reference/:page*", - "destination": "/api-reference/:page*" - }, - { - "source": "/multiple-api-keys", - "destination": "/docs/multiple-api-keys" - }, - { - "source": "/docs/examples/cookbook", - "destination": "/docs/learning-how-tos/cookbook" - }, - { - "source": "/docs/examples/cookbook/:page*", - "destination": "/docs/learning-how-tos/cookbook/:page*" - }, - { - "source": "/docs/learning-how-tos/examples-and-guides/deepl-api-101", - "destination": "/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api" - }, - { - "source": "/docs/learning-how-tos/examples-and-guides/deepl-api-101/first-things-to-try-with-the-deepl-api", - "destination": "/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api" - }, - { - "source": "/docs/resources/examples-and-guides/deepl-api-101", - "destination": "/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api" - }, - { - "source": "/docs/resources/examples-and-guides/deepl-api-101/first-things-to-try-with-the-deepl-api", - "destination": "/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api" - }, - { - "source": "/docs/resources/examples-and-guides", - "destination": "/docs/learning-how-tos/examples-and-guides" - }, - { - "source": "/docs/resources/examples-and-guides/:page*", - "destination": "/docs/learning-how-tos/examples-and-guides/:page*" - }, - { - "source": "/docs/getting-started/readme", - "destination": "/docs" - }, - { - "source": "/docs/learning-how-tos/guides/:page*", - "destination": "/docs/learning-how-tos/examples-and-guides/:page*" - }, - { - "source": "/docs/examples/cookbook/placeholder-tags", - "destination": "/docs/learning-how-tos/examples-and-guides/placeholder-tags" - }, - { - "source": "/docs/resources/supported-languages", - "destination": "/docs/getting-started/supported-languages" - }, - { - "source": "/docs/resources/breaking-changes-change-notices/february-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key", - "destination": "/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key" - }, - { - "source": "/deepl-api-docs", - "destination": "/docs" - }, - { - "source": "/docs/getting-started/pre-production-checklist", - "destination": "/docs/best-practices/pre-production-checklist" - }, - { - "source": "/docs/getting-started/alpha-and-beta-features", - "destination": "/docs/resources/alpha-and-beta-features" - }, - { - "source": "/docs/resources/release-notes", - "destination": "/docs/resources/roadmap-and-release-notes" - }, - { - "source": "/api-reference/client-libraries", - "destination": "/docs/getting-started/client-libraries" - }, - { - "source": "/docs/cli", - "destination": "/docs/getting-started/deepl-cli" - }, - { - "source": "/docs/resources/release-notes/rss.xml", - "destination": "/docs/resources/roadmap-and-release-notes/rss.xml" - }, - { - "source": "/api-reference/voice/request-stream", - "destination": "/api-reference/voice/request-session" - }, - { - "source": "/api-reference/voice/reconnect-stream", - "destination": "/api-reference/voice/reconnect-session" - }, - { - "source": "/api-reference/translation-memory", - "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories" - }, - { - "source": "/docs/best-practices/working-with-context", - "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter" - }, - { - "source": "/docs/learning-how-tos/cookbook/context-parameter-examples", - "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter" - } + {"source": "/docs/api-reference/improve-text/openapi-spec-for-text-improvement", "destination": "/api-reference/improve-text/request-text-improvement"}, + {"source": "/docs/api-reference/languages/openapi-spec-for-retrieving-languages", "destination": "/api-reference/languages/retrieve-supported-languages"}, + {"source": "/docs/api-reference/translate/openapi-spec-for-text-translation", "destination": "/api-reference/translate/request-translation"}, + {"source": "/docs/api-reference/document/openapi-spec-for-document-translation", "destination": "/api-reference/document/upload-and-translate-a-document"}, + {"source": "/docs/api-reference/glossaries/openapi-spec-for-glossary-management", "destination": "/api-reference/multilingual-glossaries/create-a-glossary"}, + {"source": "/docs/api-reference/glossaries/glossaries/openapi-spec-for-glossary-management", "destination": "/api-reference/glossaries/create-a-glossary"}, + {"source": "/docs/api-reference/usage-and-quota/openapi-spec-for-retrieving-usage-and-quota", "destination": "/api-reference/usage-and-quota/check-usage-and-limits"}, + {"source": "/docs/api-reference/glossaries/glossaries", "destination": "/api-reference/glossaries"}, + {"source": "/docs/api-reference", "destination": "/api-reference"}, + {"source": "/docs/api-reference/:page*", "destination": "/api-reference/:page*"}, + {"source": "/multiple-api-keys", "destination": "/docs/multiple-api-keys"}, + {"source": "/deepl-api-docs", "destination": "/docs"}, + {"source": "/docs/getting-started/readme", "destination": "/docs"}, + {"source": "/api-reference/client-libraries", "destination": "/docs/getting-started/client-libraries"}, + {"source": "/docs/cli", "destination": "/docs/getting-started/deepl-cli"}, + {"source": "/api-reference/voice/request-stream", "destination": "/api-reference/voice/request-session"}, + {"source": "/api-reference/voice/reconnect-stream", "destination": "/api-reference/voice/reconnect-session"}, + {"source": "/docs/resources/breaking-changes-change-notices/february-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key", "destination": "/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key"}, + + {"source": "/docs/getting-started/supported-languages", "destination": "/docs/translate-api/languages/supported-languages"}, + {"source": "/docs/resources/supported-languages", "destination": "/docs/translate-api/languages/supported-languages"}, + {"source": "/docs/getting-started/managing-api-keys", "destination": "/docs/admin-api/manage-api-keys"}, + + {"source": "/docs/best-practices/cors-requests", "destination": "/docs/going-to-production/solve-cors-errors"}, + {"source": "/docs/best-practices/cost-control", "destination": "/docs/admin-api/control-costs"}, + {"source": "/docs/best-practices/custom-instructions", "destination": "/docs/translate-api/customizations/custom-instructions/write-effective-instructions"}, + {"source": "/docs/best-practices/document-translations", "destination": "/docs/translate-api/document-translation/handle-errors-and-large-files"}, + {"source": "/docs/best-practices/error-handling", "destination": "/docs/going-to-production/error-handling"}, + {"source": "/docs/best-practices/language-detection", "destination": "/docs/translate-api/text-translation/detect-languages"}, + {"source": "/docs/best-practices/pre-production-checklist", "destination": "/docs/going-to-production/pre-production-checklist"}, + {"source": "/docs/getting-started/pre-production-checklist", "destination": "/docs/going-to-production/pre-production-checklist"}, + {"source": "/docs/best-practices/working-with-context", "destination": "/docs/translate-api/text-translation/use-context-for-better-results"}, + + {"source": "/docs/learning-how-tos/examples-and-guides/translation-beginners-guide", "destination": "/docs/translate-api/text-translation/translate-text"}, + {"source": "/docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications", "destination": "/docs/cookbooks/use-deepl-with-llm-agents-mcp"}, + {"source": "/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world", "destination": "/docs/translate-api/customizations/glossaries/set-up-a-glossary"}, + {"source": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter", "destination": "/docs/translate-api/text-translation/use-context-for-better-results"}, + {"source": "/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories", "destination": "/docs/translate-api/customizations/translation-memories/use-translation-memories"}, + {"source": "/docs/learning-how-tos/examples-and-guides/placeholder-tags", "destination": "/docs/translate-api/text-translation/use-placeholder-tags"}, + {"source": "/docs/learning-how-tos/examples-and-guides/translating-between-variants", "destination": "/docs/translate-api/text-translation/translate-between-variants"}, + {"source": "/docs/learning-how-tos/examples-and-guides/enable-beta-languages", "destination": "/docs/translate-api/languages/enable-beta-languages"}, + {"source": "/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api", "destination": "/docs/getting-started/your-first-api-request"}, + {"source": "/docs/learning-how-tos/examples-and-guides/deepl-api-101", "destination": "/docs/getting-started/your-first-api-request"}, + {"source": "/docs/learning-how-tos/examples-and-guides/deepl-api-101/first-things-to-try-with-the-deepl-api", "destination": "/docs/getting-started/your-first-api-request"}, + {"source": "/docs/resources/examples-and-guides/deepl-api-101", "destination": "/docs/getting-started/your-first-api-request"}, + {"source": "/docs/resources/examples-and-guides/deepl-api-101/first-things-to-try-with-the-deepl-api", "destination": "/docs/getting-started/your-first-api-request"}, + {"source": "/docs/resources/examples-and-guides", "destination": "/docs/translate-api/text-translation/translate-text"}, + {"source": "/docs/resources/examples-and-guides/:page*", "destination": "/docs/translate-api/text-translation/translate-text"}, + {"source": "/docs/learning-how-tos/guides/:page*", "destination": "/docs/translate-api/text-translation/translate-text"}, + {"source": "/docs/examples/cookbook/placeholder-tags", "destination": "/docs/translate-api/text-translation/use-placeholder-tags"}, + + {"source": "/docs/learning-how-tos/cookbook", "destination": "/docs/cookbooks"}, + {"source": "/docs/learning-how-tos/cookbook/google-sheets", "destination": "/docs/cookbooks/translate-google-sheets"}, + {"source": "/docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot", "destination": "/docs/cookbooks/automate-game-localization-godot"}, + {"source": "/docs/learning-how-tos/cookbook/java-document-translator", "destination": "/docs/cookbooks/build-a-document-translator-java"}, + {"source": "/docs/learning-how-tos/cookbook/usage-analytics-dashboard", "destination": "/docs/cookbooks/build-a-usage-dashboard"}, + {"source": "/docs/learning-how-tos/cookbook/nodejs-proxy", "destination": "/docs/cookbooks/build-a-translation-proxy-nodejs"}, + {"source": "/docs/learning-how-tos/cookbook/context-parameter-examples", "destination": "/docs/translate-api/text-translation/use-context-for-better-results"}, + {"source": "/docs/examples/cookbook", "destination": "/docs/cookbooks"}, + {"source": "/docs/examples/cookbook/:page*", "destination": "/docs/cookbooks"}, + + {"source": "/docs/xml-and-html-handling/xml", "destination": "/docs/translate-api/structured-content/handle-xml-content"}, + {"source": "/docs/xml-and-html-handling/structured-content", "destination": "/docs/translate-api/structured-content/handle-xml-content"}, + {"source": "/docs/xml-and-html-handling/customized-xml-outline-detection", "destination": "/docs/translate-api/structured-content/customize-xml-outline-detection"}, + {"source": "/docs/xml-and-html-handling/html", "destination": "/docs/translate-api/structured-content/handle-html-content"}, + {"source": "/docs/xml-and-html-handling/tag-handling-v2", "destination": "/docs/translate-api/structured-content/how-tag-handling-works"}, + + {"source": "/docs/resources/roadmap-and-release-notes", "destination": "/docs/changelog"}, + {"source": "/docs/resources/release-notes", "destination": "/docs/changelog"}, + {"source": "/docs/resources/release-notes/rss.xml", "destination": "/docs/changelog/rss.xml"}, + {"source": "/docs/resources/usage-limits", "destination": "/docs/going-to-production/usage-limits"}, + {"source": "/docs/resources/language-release-process", "destination": "/docs/translate-api/languages/language-release-process"}, + {"source": "/docs/resources/open-api-spec", "destination": "/docs/getting-started/client-libraries"}, + {"source": "/docs/getting-started/alpha-and-beta-features", "destination": "/docs/resources/alpha-and-beta-features"}, + + {"source": "/api-reference/translation-memory", "destination": "/docs/translate-api/customizations/translation-memories/use-translation-memories"} ], "integrations": { "cookies": { diff --git a/docs/best-practices/cost-control.mdx b/docs/admin-api/control-costs.mdx similarity index 100% rename from docs/best-practices/cost-control.mdx rename to docs/admin-api/control-costs.mdx diff --git a/docs/getting-started/managing-api-keys.mdx b/docs/admin-api/manage-api-keys.mdx similarity index 100% rename from docs/getting-started/managing-api-keys.mdx rename to docs/admin-api/manage-api-keys.mdx diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/changelog.mdx similarity index 94% rename from docs/resources/roadmap-and-release-notes.mdx rename to docs/changelog.mdx index 4411a0b7..f9795cf7 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/changelog.mdx @@ -56,7 +56,7 @@ Use the `DeepL-Auth-Key` header instead. - Note that these languages only work with `quality_optimized` model or when no model is specified, and are not compatible with `latency_optimized` requests. - The `enable_beta_languages` parameter is maintained for backward compatibility but has no effect. -See [here](../getting-started/supported-languages) for the complete language list. +See [here](/docs/translate-api/languages/supported-languages) for the complete language list. @@ -64,10 +64,10 @@ See [here](../getting-started/supported-languages) for the complete language lis - Added API reference for the Voice API - Add contextual menu in the to make it easier to copy any API documentation page as context for AI tools - Add support for style rules in the API to programmatically get your created style rules and translate with them. -- Overhauled the tag-handling algorithm that backs translation of XML and HTML in the DeepL API. To enable it and benefit from all the improvements, set the `tag_handling_version` parameter to `v2` in the text translation API. See [here](../xml-and-html-handling/tag-handling-v2) for more information. +- Overhauled the tag-handling algorithm that backs translation of XML and HTML in the DeepL API. To enable it and benefit from all the improvements, set the `tag_handling_version` parameter to `v2` in the text translation API. See [here](/docs/translate-api/structured-content/how-tag-handling-works) for more information. - Added new usage analytics endpoint in the Admin API, including key-level reporting. See [here](/api-reference/admin-api/get-usage-analytics) for more details - Enabled support for multiple admins in an API subscription -- Added support for 75 new languages, initially through the `enable_beta_languages` parameter, for text and document translation. Beta languages are not billed during the beta phase and do not yet support glossaries or formality. See [here](../getting-started/supported-languages#beta-languages) for more information +- Added support for 75 new languages, initially through the `enable_beta_languages` parameter, for text and document translation. Beta languages are not billed during the beta phase and do not yet support glossaries or formality. See [here](/docs/translate-api/languages/supported-languages#beta-languages) for more information - Added HE, TH and VI to the languages endpoint, since they are now also available in document translation - Added 6 additional beta languages, for text and document translation. See the previous note about 75 new languages. - Added a new parameter to the text translation API to allow custom instructions, making it possible to customize the translation behavior (e.g. ["Use a friendly, diplomatic tone"]) @@ -75,18 +75,18 @@ See [here](../getting-started/supported-languages) for the complete language lis ## Q3 2025 - Creation of an admin API, making it possible to manage API keys programmatically. See [here](/api-reference/admin-api) for more information -- Added support for new language: ES-419 (Latin American Spanish). For this release, this language will be available for the API in next-gen models only. See [here](../getting-started/supported-languages) for more information. +- Added support for new language: ES-419 (Latin American Spanish). For this release, this language will be available for the API in next-gen models only. See [here](/docs/translate-api/languages/supported-languages) for more information. - Refreshed our API documentation and added new try-it explorers to support interacting with our APIs. See [here](/api-reference) to try it out! ## Q2 2025 -- Added support for new language: TH (Thai). For this release, this language will only support text translation. See [here](../getting-started/supported-languages) for more information. -- Added support for new languages: HE (Hebrew) and VI (Vietnamese). For this release, these languages will be available for Pro v2 API in next-gen models only. See [here](../getting-started/supported-languages) for more information. +- Added support for new language: TH (Thai). For this release, this language will only support text translation. See [here](/docs/translate-api/languages/supported-languages) for more information. +- Added support for new languages: HE (Hebrew) and VI (Vietnamese). For this release, these languages will be available for Pro v2 API in next-gen models only. See [here](/docs/translate-api/languages/supported-languages) for more information. - Added improvements to API glossaries, including the ability to edit glossaries and create multilingual glossaries. Learn more [here](/api-reference/multilingual-glossaries/). - Improvements to the `/usage` endpoint for Pro API customers ([API reference](/api-reference/usage-and-quota/)) -- Improvements to key-level usage reporting, making it possible to pull reports with a custom date range and to group data by calendar day. Learn more [here](../getting-started/managing-api-keys#get-api-key-level-usage). +- Improvements to key-level usage reporting, making it possible to pull reports with a custom date range and to group data by calendar day. Learn more [here](/docs/admin-api/manage-api-keys#get-api-key-level-usage). ## Q1 2025 -- Added support for API key-level usage limits, making it possible to set a character limit at the API key-level. Learn more [here](../getting-started/managing-api-keys#set-api-key-level-usage-limits). +- Added support for API key-level usage limits, making it possible to set a character limit at the API key-level. Learn more [here](/docs/admin-api/manage-api-keys#set-api-key-level-usage-limits). - DeepL API for Write is generally available to Pro API customers, making it possible to improve texts in (at the time of release) 6 different languages. Learn more and get started [here](/api-reference/improve-text/). diff --git a/docs/learning-how-tos/cookbook.mdx b/docs/cookbooks.mdx similarity index 100% rename from docs/learning-how-tos/cookbook.mdx rename to docs/cookbooks.mdx diff --git a/docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot.mdx b/docs/cookbooks/automate-game-localization-godot.mdx similarity index 100% rename from docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot.mdx rename to docs/cookbooks/automate-game-localization-godot.mdx diff --git a/docs/learning-how-tos/cookbook/java-document-translator.mdx b/docs/cookbooks/build-a-document-translator-java.mdx similarity index 100% rename from docs/learning-how-tos/cookbook/java-document-translator.mdx rename to docs/cookbooks/build-a-document-translator-java.mdx diff --git a/docs/learning-how-tos/cookbook/nodejs-proxy.mdx b/docs/cookbooks/build-a-translation-proxy-nodejs.mdx similarity index 93% rename from docs/learning-how-tos/cookbook/nodejs-proxy.mdx rename to docs/cookbooks/build-a-translation-proxy-nodejs.mdx index 00c1912c..4a98b3ec 100644 --- a/docs/learning-how-tos/cookbook/nodejs-proxy.mdx +++ b/docs/cookbooks/build-a-translation-proxy-nodejs.mdx @@ -12,7 +12,7 @@ These proxies are intended for prototyping and frontend testing. For production The DeepL API does not permit calls from client-side JavaScript - that is, from JavaScript running in a browser. This policy exists to keep your API key safe. When you place a call from your website directly to the DeepL API, that call needs to include your API key. Anyone using your website could look at the network calls or your code itself, find your API key, and use it themselves. -For this and other security considerations, DeepL [does not enable the CORS headers](/docs/best-practices/cors-requests) you would need to call the API from a webpage hosted on your origin. The industry-standard approach is to call APIs like DeepL’s from a back-end service. DeepL enforces this best practice to keep your credentials secure. +For this and other security considerations, DeepL [does not enable the CORS headers](/docs/going-to-production/solve-cors-errors) you would need to call the API from a webpage hosted on your origin. The industry-standard approach is to call APIs like DeepL’s from a back-end service. DeepL enforces this best practice to keep your credentials secure. ## When to use a quick proxy diff --git a/docs/learning-how-tos/cookbook/usage-analytics-dashboard.mdx b/docs/cookbooks/build-a-usage-dashboard.mdx similarity index 100% rename from docs/learning-how-tos/cookbook/usage-analytics-dashboard.mdx rename to docs/cookbooks/build-a-usage-dashboard.mdx diff --git a/docs/learning-how-tos/cookbook/google-sheets.mdx b/docs/cookbooks/translate-google-sheets.mdx similarity index 100% rename from docs/learning-how-tos/cookbook/google-sheets.mdx rename to docs/cookbooks/translate-google-sheets.mdx diff --git a/docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications.mdx b/docs/cookbooks/use-deepl-with-llm-agents-mcp.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications.mdx rename to docs/cookbooks/use-deepl-with-llm-agents-mcp.mdx diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx index a0f039fa..3c3e293c 100644 --- a/docs/getting-started/about.mdx +++ b/docs/getting-started/about.mdx @@ -5,7 +5,7 @@ mode: "wide" --- - For information about API updates and improvements, please refer to our [release notes](/docs/resources/release-notes). + For information about API updates and improvements, please refer to our [release notes](/docs/changelog). The DeepL API provides programmatic access to DeepL’s language AI technology, making it possible to bring high quality translation capabilities directly to your websites and applications. diff --git a/docs/getting-started/auth.mdx b/docs/getting-started/auth.mdx index b953d57b..d279ffef 100644 --- a/docs/getting-started/auth.mdx +++ b/docs/getting-started/auth.mdx @@ -32,7 +32,7 @@ Keep your API key secure at all times. Do not use it in client-side code. If your authentication key becomes compromised, you also deactivate it and create a new key in [the "API Keys" tab](https://www.deepl.com/your-account/keys). -Learn more about managing your DeepL API keys [here](/docs/getting-started/managing-api-keys). +Learn more about managing your DeepL API keys [here](/docs/admin-api/manage-api-keys). The authentication key is provided by setting the *Authorization* HTTP header to `DeepL-Auth-Key [yourAuthKey]`. diff --git a/docs/getting-started/intro.mdx b/docs/getting-started/intro.mdx index 4e048fcc..a540cc6a 100644 --- a/docs/getting-started/intro.mdx +++ b/docs/getting-started/intro.mdx @@ -262,7 +262,7 @@ New user? Follow these quick steps to get started with the DeepL API. Status Page - + Release Notes diff --git a/docs/best-practices/error-handling.mdx b/docs/going-to-production/error-handling.mdx similarity index 86% rename from docs/best-practices/error-handling.mdx rename to docs/going-to-production/error-handling.mdx index 86e40192..52e25332 100644 --- a/docs/best-practices/error-handling.mdx +++ b/docs/going-to-production/error-handling.mdx @@ -8,7 +8,7 @@ Errors are indicated by [standard HTTP status codes](https://developer.mozilla.o * **HTTP 429: too many requests.** This is an error that you might receive when sending many API requests in a short period of time. Your application should be configured to resend the requests after some delay. Specifically, we recommend implementing retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries). -* **HTTP 456: quota exceeded** **If you're a Free API user**, you'll receive this error when the monthly 500,000 character limit of your subscription has been reached. You can consider [upgrading your subscription](https://www.deepl.com/pro) if you need more character volume. **If you're a Pro API user**, you'll receive this error when your [Cost Control](/docs/best-practices/cost-control) limit has been reached, and you can increase or remove your Cost Control limit if you need to continue translating. You can also use the [usage endpoint](/api-reference/usage-and-quota) to find out your currently used and available quota. +* **HTTP 456: quota exceeded** **If you're a Free API user**, you'll receive this error when the monthly 500,000 character limit of your subscription has been reached. You can consider [upgrading your subscription](https://www.deepl.com/pro) if you need more character volume. **If you're a Pro API user**, you'll receive this error when your [Cost Control](/docs/admin-api/control-costs) limit has been reached, and you can increase or remove your Cost Control limit if you need to continue translating. You can also use the [usage endpoint](/api-reference/usage-and-quota) to find out your currently used and available quota. * **HTTP 500: internal server error** This is an error you'll receive if there are temporary errors in DeepL Services. Your application should be configured to resend the requests after some delay. Specifically, we recommend implementing retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries). diff --git a/docs/best-practices/pre-production-checklist.mdx b/docs/going-to-production/pre-production-checklist.mdx similarity index 93% rename from docs/best-practices/pre-production-checklist.mdx rename to docs/going-to-production/pre-production-checklist.mdx index 41b4e7ff..201a4c4d 100644 --- a/docs/best-practices/pre-production-checklist.mdx +++ b/docs/going-to-production/pre-production-checklist.mdx @@ -11,6 +11,6 @@ As you prepare to open your DeepL-powered application up to the world, these tip 3. **Use the correct content type:** For text translation (the `/translate` endpoint), use form-encoded (`Content-Type: application/x-www-form-urlencoded`) or JSON-encoded (`Content-Type: application/json`) request bodies. * Uploading a file for document translation requires an HTTP POST request with `Content-Type: multipart/form-data`; this content type should not be used for text translation. 4. **No query parameters:** Please do not make API requests using query parameters. The examples throughout the API reference include properly formed HTTP POST requests. For security reasons, be especially sure not to send your authentication key via query parameters. -5. **CORS requests:** It's not possible to send requests to the DeepL API from the browser, as requests to third-party APIs from front-end applications would expose your credentials on the web. [You can learn more here](/docs/best-practices/cors-requests). -6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate#request-body-descriptions). [Learn more about working with context here](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter). +5. **CORS requests:** It's not possible to send requests to the DeepL API from the browser, as requests to third-party APIs from front-end applications would expose your credentials on the web. [You can learn more here](/docs/going-to-production/solve-cors-errors). +6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate#request-body-descriptions). [Learn more about working with context here](/docs/translate-api/text-translation/use-context-for-better-results). 7. **Cache results from translation requests:** Storing API responses lets apps serve content faster and avoids extra costs from repeated requests for unchanged content. diff --git a/docs/best-practices/cors-requests.mdx b/docs/going-to-production/solve-cors-errors.mdx similarity index 100% rename from docs/best-practices/cors-requests.mdx rename to docs/going-to-production/solve-cors-errors.mdx diff --git a/docs/resources/usage-limits.mdx b/docs/going-to-production/usage-limits.mdx similarity index 100% rename from docs/resources/usage-limits.mdx rename to docs/going-to-production/usage-limits.mdx diff --git a/docs/resources/breaking-changes-change-notices.mdx b/docs/resources/breaking-changes-change-notices.mdx index 917cd2cb..75987307 100644 --- a/docs/resources/breaking-changes-change-notices.mdx +++ b/docs/resources/breaking-changes-change-notices.mdx @@ -6,7 +6,7 @@ mode: "wide" In this section, we'll outline **planned deprecations and breaking changes** that might affect applications using the DeepL API. -To learn about new releases, please see the [Release notes](/docs/resources/release-notes) page. +To learn about new releases, please see the [Release notes](/docs/changelog) page. diff --git a/docs/best-practices/custom-instructions.mdx b/docs/translate-api/customizations/custom-instructions/write-effective-instructions.mdx similarity index 100% rename from docs/best-practices/custom-instructions.mdx rename to docs/translate-api/customizations/custom-instructions/write-effective-instructions.mdx diff --git a/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world.mdx b/docs/translate-api/customizations/glossaries/set-up-a-glossary.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world.mdx rename to docs/translate-api/customizations/glossaries/set-up-a-glossary.mdx diff --git a/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories.mdx b/docs/translate-api/customizations/translation-memories/use-translation-memories.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories.mdx rename to docs/translate-api/customizations/translation-memories/use-translation-memories.mdx diff --git a/docs/best-practices/document-translations.mdx b/docs/translate-api/document-translation/handle-errors-and-large-files.mdx similarity index 100% rename from docs/best-practices/document-translations.mdx rename to docs/translate-api/document-translation/handle-errors-and-large-files.mdx diff --git a/docs/learning-how-tos/examples-and-guides/enable-beta-languages.mdx b/docs/translate-api/languages/enable-beta-languages.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/enable-beta-languages.mdx rename to docs/translate-api/languages/enable-beta-languages.mdx diff --git a/docs/resources/language-release-process.mdx b/docs/translate-api/languages/language-release-process.mdx similarity index 100% rename from docs/resources/language-release-process.mdx rename to docs/translate-api/languages/language-release-process.mdx diff --git a/docs/getting-started/supported-languages.mdx b/docs/translate-api/languages/supported-languages.mdx similarity index 100% rename from docs/getting-started/supported-languages.mdx rename to docs/translate-api/languages/supported-languages.mdx diff --git a/docs/xml-and-html-handling/customized-xml-outline-detection.mdx b/docs/translate-api/structured-content/customize-xml-outline-detection.mdx similarity index 100% rename from docs/xml-and-html-handling/customized-xml-outline-detection.mdx rename to docs/translate-api/structured-content/customize-xml-outline-detection.mdx diff --git a/docs/xml-and-html-handling/html.mdx b/docs/translate-api/structured-content/handle-html-content.mdx similarity index 100% rename from docs/xml-and-html-handling/html.mdx rename to docs/translate-api/structured-content/handle-html-content.mdx diff --git a/docs/xml-and-html-handling/structured-content.mdx b/docs/translate-api/structured-content/handle-xml-content.mdx similarity index 100% rename from docs/xml-and-html-handling/structured-content.mdx rename to docs/translate-api/structured-content/handle-xml-content.mdx diff --git a/docs/xml-and-html-handling/tag-handling-v2.mdx b/docs/translate-api/structured-content/how-tag-handling-works.mdx similarity index 100% rename from docs/xml-and-html-handling/tag-handling-v2.mdx rename to docs/translate-api/structured-content/how-tag-handling-works.mdx diff --git a/docs/best-practices/language-detection.mdx b/docs/translate-api/text-translation/detect-languages.mdx similarity index 100% rename from docs/best-practices/language-detection.mdx rename to docs/translate-api/text-translation/detect-languages.mdx diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/translate-api/text-translation/translate-between-variants.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx rename to docs/translate-api/text-translation/translate-between-variants.mdx diff --git a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx b/docs/translate-api/text-translation/translate-text.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx rename to docs/translate-api/text-translation/translate-text.mdx diff --git a/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter.mdx b/docs/translate-api/text-translation/use-context-for-better-results.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter.mdx rename to docs/translate-api/text-translation/use-context-for-better-results.mdx diff --git a/docs/learning-how-tos/examples-and-guides/placeholder-tags.mdx b/docs/translate-api/text-translation/use-placeholder-tags.mdx similarity index 100% rename from docs/learning-how-tos/examples-and-guides/placeholder-tags.mdx rename to docs/translate-api/text-translation/use-placeholder-tags.mdx From de249a1babfefc036bd347157047d439d54b23e8 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Tue, 14 Apr 2026 17:17:29 -0400 Subject: [PATCH 2/5] docs: adjust IA based on review feedback - Move Languages from Translate API to Getting Started (docs tab) and Admin API (API Reference tab) - Move Admin API overview to first position in API Reference listing - Remove service specification update pages from Write and Voice API sidebar nav - Rename "Monolingual Glossaries v2" to "Glossaries v2" - Nest GET usage analytics under Organization usage analytics group - Move Changelog from standalone section to page under Getting Started - Rename page title from "Roadmap and release notes" to "Changelog" Co-Authored-By: Claude Opus 4.6 (1M context) --- docs.json | 84 ++++++++++++++++++++++------------------------ docs/changelog.mdx | 2 +- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/docs.json b/docs.json index d85d9a4c..682a15ff 100644 --- a/docs.json +++ b/docs.json @@ -49,7 +49,16 @@ "docs/getting-started/test-your-api-requests-with-postman" ] }, - "docs/getting-started/regional-endpoints" + "docs/getting-started/regional-endpoints", + { + "group": "Languages", + "pages": [ + "docs/translate-api/languages/supported-languages", + "docs/translate-api/languages/enable-beta-languages", + "docs/translate-api/languages/language-release-process" + ] + }, + "docs/changelog" ] }, { @@ -102,14 +111,6 @@ "docs/translate-api/structured-content/customize-xml-outline-detection", "docs/translate-api/structured-content/how-tag-handling-works" ] - }, - { - "group": "Languages", - "pages": [ - "docs/translate-api/languages/supported-languages", - "docs/translate-api/languages/enable-beta-languages", - "docs/translate-api/languages/language-release-process" - ] } ] }, @@ -140,12 +141,6 @@ "docs/cookbooks/use-deepl-with-llm-agents-mcp", "docs/cookbooks/translate-google-sheets" ] - }, - { - "group": "Changelog", - "pages": [ - "docs/changelog" - ] } ] }, @@ -185,7 +180,7 @@ "api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id", "api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries", { - "group": "Monolingual Glossaries v2", + "group": "Glossaries v2", "tag": "DEPRECATED", "pages": [ "api-reference/glossaries", @@ -220,26 +215,6 @@ "pages": [ "api-reference/translation-memory/list-translation-memories" ] - }, - { - "group": "Languages", - "pages": [ - "api-reference/languages", - "api-reference/languages/retrieve-supported-languages", - { - "group": "Retrieve supported languages by product (v3)", - "tag": "BETA", - "pages": [ - "api-reference/languages/retrieve-supported-languages-by-product", - "api-reference/languages/language-feature-use-cases", - "api-reference/languages/retrieve-languages-by-product", - "api-reference/languages/retrieve-products", - "api-reference/languages/retrieve-language-pair-exceptions", - "api-reference/languages/migrate-from-v2-languages", - "api-reference/languages/v3-languages-changelog" - ] - } - ] } ] }, @@ -247,8 +222,7 @@ "group": "Write API", "pages": [ "api-reference/improve-text", - "api-reference/improve-text/request-text-improvement", - "api-reference/improve-text/deepl-write-api-service-specification-updates" + "api-reference/improve-text/request-text-improvement" ] }, { @@ -257,13 +231,13 @@ "api-reference/voice", "api-reference/voice/request-session", "api-reference/voice/websocket-streaming", - "api-reference/voice/reconnect-session", - "api-reference/voice/deepl-voice-api-service-specification-updates" + "api-reference/voice/reconnect-session" ] }, { "group": "Admin API", "pages": [ + "api-reference/admin-api", { "group": "Usage & Quota", "pages": [ @@ -271,7 +245,6 @@ "api-reference/usage-and-quota/check-usage-and-limits" ] }, - "api-reference/admin-api", "api-reference/admin-api/managing-admin-keys", { "group": "Managing developer keys", @@ -284,8 +257,33 @@ "api-reference/admin-api/managing-developer-keys/set-usage-limits" ] }, - "api-reference/admin-api/organization-usage-analytics", - "api-reference/admin-api/get-usage-analytics" + { + "group": "Organization usage analytics", + "pages": [ + "api-reference/admin-api/organization-usage-analytics", + "api-reference/admin-api/get-usage-analytics" + ] + }, + { + "group": "Languages", + "pages": [ + "api-reference/languages", + "api-reference/languages/retrieve-supported-languages", + { + "group": "Retrieve supported languages by product (v3)", + "tag": "BETA", + "pages": [ + "api-reference/languages/retrieve-supported-languages-by-product", + "api-reference/languages/language-feature-use-cases", + "api-reference/languages/retrieve-languages-by-product", + "api-reference/languages/retrieve-products", + "api-reference/languages/retrieve-language-pair-exceptions", + "api-reference/languages/migrate-from-v2-languages", + "api-reference/languages/v3-languages-changelog" + ] + } + ] + } ] } ] diff --git a/docs/changelog.mdx b/docs/changelog.mdx index f9795cf7..545db7fb 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -1,5 +1,5 @@ --- -title: "Roadmap and release notes" +title: "Changelog" description: "The latest features and improvements in the DeepL API, plus what's coming next" rss: true --- From 2d26da80d6db8a29ef09fa75889c8da621d3bddf Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Tue, 14 Apr 2026 17:28:19 -0400 Subject: [PATCH 3/5] docs: restore hidden pages and reorganize sections Previously hidden pages are now visible in the nav: - XML page: added to renamed "XML & HTML" group (was "Structured Content") - Developer Community: moved to Developer Tools group - OpenAPI spec: moved to Developer Tools group - Alpha and beta features: moved to new "Updates" group - Breaking changes: moved to "Updates" group, renamed from "Breaking changes (Change Notices)" to "Breaking changes" - Changelog, alpha/beta, and breaking changes grouped under "Updates" in Getting Started Also: - Remove DeepL 101 reference from intro page (page stays hidden for Phase 2 merge) - Update stale cookbook/guides links on intro page - Fix internal links in breaking changes overview page Co-Authored-By: Claude Opus 4.6 (1M context) --- docs.json | 33 +++++++++++++++---- .../alpha-and-beta-features.mdx | 0 .../breaking-changes.mdx} | 8 ++--- ...-deprecation-of-insecure-cipher-suites.mdx | 0 ...slate-and-authenticating-with-auth_key.mdx | 0 ...025-deprecation-of-legacy-auth-methods.mdx | 0 .../deepl-developer-community.mdx | 0 docs/getting-started/intro.mdx | 6 ++-- .../open-api-spec.mdx | 0 .../structured-content}/xml.mdx | 0 10 files changed, 33 insertions(+), 14 deletions(-) rename docs/{resources => getting-started}/alpha-and-beta-features.mdx (100%) rename docs/{resources/breaking-changes-change-notices.mdx => getting-started/breaking-changes.mdx} (51%) rename docs/{resources/breaking-changes-change-notices => getting-started/breaking-changes}/july-2024-deprecation-of-insecure-cipher-suites.mdx (100%) rename docs/{resources/breaking-changes-change-notices => getting-started/breaking-changes}/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx (100%) rename docs/{resources/breaking-changes-change-notices => getting-started/breaking-changes}/november-2025-deprecation-of-legacy-auth-methods.mdx (100%) rename docs/{resources => getting-started}/deepl-developer-community.mdx (100%) rename docs/{resources => getting-started}/open-api-spec.mdx (100%) rename docs/{xml-and-html-handling => translate-api/structured-content}/xml.mdx (100%) diff --git a/docs.json b/docs.json index 682a15ff..85a4c77e 100644 --- a/docs.json +++ b/docs.json @@ -46,7 +46,9 @@ "docs/getting-started/client-libraries", "docs/getting-started/deepl-cli", "docs/getting-started/deepl-mcp-server", - "docs/getting-started/test-your-api-requests-with-postman" + "docs/getting-started/test-your-api-requests-with-postman", + "docs/getting-started/deepl-developer-community", + "docs/getting-started/open-api-spec" ] }, "docs/getting-started/regional-endpoints", @@ -58,7 +60,22 @@ "docs/translate-api/languages/language-release-process" ] }, - "docs/changelog" + { + "group": "Updates", + "pages": [ + "docs/changelog", + "docs/getting-started/alpha-and-beta-features", + { + "group": "Breaking changes", + "pages": [ + "docs/getting-started/breaking-changes", + "docs/getting-started/breaking-changes/july-2024-deprecation-of-insecure-cipher-suites", + "docs/getting-started/breaking-changes/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key", + "docs/getting-started/breaking-changes/november-2025-deprecation-of-legacy-auth-methods" + ] + } + ] + } ] }, { @@ -104,8 +121,9 @@ ] }, { - "group": "Structured Content", + "group": "XML & HTML", "pages": [ + "docs/translate-api/structured-content/xml", "docs/translate-api/structured-content/handle-xml-content", "docs/translate-api/structured-content/handle-html-content", "docs/translate-api/structured-content/customize-xml-outline-detection", @@ -398,7 +416,7 @@ {"source": "/docs/examples/cookbook", "destination": "/docs/cookbooks"}, {"source": "/docs/examples/cookbook/:page*", "destination": "/docs/cookbooks"}, - {"source": "/docs/xml-and-html-handling/xml", "destination": "/docs/translate-api/structured-content/handle-xml-content"}, + {"source": "/docs/xml-and-html-handling/xml", "destination": "/docs/translate-api/structured-content/xml"}, {"source": "/docs/xml-and-html-handling/structured-content", "destination": "/docs/translate-api/structured-content/handle-xml-content"}, {"source": "/docs/xml-and-html-handling/customized-xml-outline-detection", "destination": "/docs/translate-api/structured-content/customize-xml-outline-detection"}, {"source": "/docs/xml-and-html-handling/html", "destination": "/docs/translate-api/structured-content/handle-html-content"}, @@ -409,8 +427,11 @@ {"source": "/docs/resources/release-notes/rss.xml", "destination": "/docs/changelog/rss.xml"}, {"source": "/docs/resources/usage-limits", "destination": "/docs/going-to-production/usage-limits"}, {"source": "/docs/resources/language-release-process", "destination": "/docs/translate-api/languages/language-release-process"}, - {"source": "/docs/resources/open-api-spec", "destination": "/docs/getting-started/client-libraries"}, - {"source": "/docs/getting-started/alpha-and-beta-features", "destination": "/docs/resources/alpha-and-beta-features"}, + {"source": "/docs/resources/open-api-spec", "destination": "/docs/getting-started/open-api-spec"}, + {"source": "/docs/resources/deepl-developer-community", "destination": "/docs/getting-started/deepl-developer-community"}, + {"source": "/docs/resources/alpha-and-beta-features", "destination": "/docs/getting-started/alpha-and-beta-features"}, + {"source": "/docs/resources/breaking-changes-change-notices", "destination": "/docs/getting-started/breaking-changes"}, + {"source": "/docs/resources/breaking-changes-change-notices/:page*", "destination": "/docs/getting-started/breaking-changes/:page*"}, {"source": "/api-reference/translation-memory", "destination": "/docs/translate-api/customizations/translation-memories/use-translation-memories"} ], diff --git a/docs/resources/alpha-and-beta-features.mdx b/docs/getting-started/alpha-and-beta-features.mdx similarity index 100% rename from docs/resources/alpha-and-beta-features.mdx rename to docs/getting-started/alpha-and-beta-features.mdx diff --git a/docs/resources/breaking-changes-change-notices.mdx b/docs/getting-started/breaking-changes.mdx similarity index 51% rename from docs/resources/breaking-changes-change-notices.mdx rename to docs/getting-started/breaking-changes.mdx index 75987307..5c799adf 100644 --- a/docs/resources/breaking-changes-change-notices.mdx +++ b/docs/getting-started/breaking-changes.mdx @@ -1,5 +1,5 @@ --- -title: "Breaking changes (Change Notices)" +title: "Breaking changes" sidebarTitle: "Overview" mode: "wide" --- @@ -8,9 +8,9 @@ In this section, we'll outline **planned deprecations and breaking changes** tha To learn about new releases, please see the [Release notes](/docs/changelog) page. - + - + - + \ No newline at end of file diff --git a/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites.mdx b/docs/getting-started/breaking-changes/july-2024-deprecation-of-insecure-cipher-suites.mdx similarity index 100% rename from docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites.mdx rename to docs/getting-started/breaking-changes/july-2024-deprecation-of-insecure-cipher-suites.mdx diff --git a/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx b/docs/getting-started/breaking-changes/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx similarity index 100% rename from docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx rename to docs/getting-started/breaking-changes/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx diff --git a/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods.mdx b/docs/getting-started/breaking-changes/november-2025-deprecation-of-legacy-auth-methods.mdx similarity index 100% rename from docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods.mdx rename to docs/getting-started/breaking-changes/november-2025-deprecation-of-legacy-auth-methods.mdx diff --git a/docs/resources/deepl-developer-community.mdx b/docs/getting-started/deepl-developer-community.mdx similarity index 100% rename from docs/resources/deepl-developer-community.mdx rename to docs/getting-started/deepl-developer-community.mdx diff --git a/docs/getting-started/intro.mdx b/docs/getting-started/intro.mdx index a540cc6a..5ccf6c6a 100644 --- a/docs/getting-started/intro.mdx +++ b/docs/getting-started/intro.mdx @@ -239,16 +239,14 @@ New user? Follow these quick steps to get started with the DeepL API. - [Our official client libraries](/docs/getting-started/client-libraries) let you use the API with six popular programming languages - [Python](https://www.github.com/deeplcom/deepl-python), [JavaScript](https://www.github.com/deeplcom/deepl-node), [PHP](https://www.github.com/deeplcom/deepl-php), [.NET](https://www.github.com/deeplcom/deepl-dotnet), [Java](https://www.github.com/deeplcom/deepl-java), or [Ruby](https://www.github.com/deeplcom/deepl-rb). The DeepL community has [contributed client libraries](https://github.com/DeepLcom/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), and [Rust](https://github.com/Avimitin/deepl-rs). You may also wish to check out [these examples and guides](/docs/learning-how-tos/examples-and-guides). + [Our official client libraries](/docs/getting-started/client-libraries) let you use the API with six popular programming languages - [Python](https://www.github.com/deeplcom/deepl-python), [JavaScript](https://www.github.com/deeplcom/deepl-node), [PHP](https://www.github.com/deeplcom/deepl-php), [.NET](https://www.github.com/deeplcom/deepl-dotnet), [Java](https://www.github.com/deeplcom/deepl-java), or [Ruby](https://www.github.com/deeplcom/deepl-rb). The DeepL community has [contributed client libraries](https://github.com/DeepLcom/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), and [Rust](https://github.com/Avimitin/deepl-rs). You may also wish to check out [our cookbooks](/docs/cookbooks). ## Keep exploring - [Your first API request](/docs/getting-started/your-first-api-request) - With just a few lines of code, make your first request to the DeepL Translate or Write API -- [**DeepL 101**](/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api) - A quick guide to text and document translation, using Postman to play with the API, client libraries for your favorite programming language, and joining our developer community -- [Cookbook](/docs/learning-how-tos/cookbook) - Explore short tutorials, examples, projects, and use cases -- [Guides](/docs/learning-how-tos/examples-and-guides) - Discover in-depth explanations for API features and real-world applications +- [Cookbooks](/docs/cookbooks) - Explore short tutorials, examples, projects, and use cases ## Community and Support diff --git a/docs/resources/open-api-spec.mdx b/docs/getting-started/open-api-spec.mdx similarity index 100% rename from docs/resources/open-api-spec.mdx rename to docs/getting-started/open-api-spec.mdx diff --git a/docs/xml-and-html-handling/xml.mdx b/docs/translate-api/structured-content/xml.mdx similarity index 100% rename from docs/xml-and-html-handling/xml.mdx rename to docs/translate-api/structured-content/xml.mdx From f36a6eb812192d5f72ebd291e0e5061e4836db77 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Tue, 14 Apr 2026 17:58:40 -0400 Subject: [PATCH 4/5] docs: promote Languages and API Updates to top-level sections - Languages: break out from Getting Started into its own top-level section in the Documentation tab - API Updates: promote from nested group under Getting Started to top-level section containing Changelog, Alpha and beta features, and Breaking changes Documentation tab now has 7 top-level groups: Getting Started, Languages, Translate API, Admin API, Going to Production, Cookbooks, API Updates Co-Authored-By: Claude Opus 4.6 (1M context) --- docs.json | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs.json b/docs.json index 85a4c77e..9bd75ae7 100644 --- a/docs.json +++ b/docs.json @@ -51,31 +51,15 @@ "docs/getting-started/open-api-spec" ] }, - "docs/getting-started/regional-endpoints", - { - "group": "Languages", - "pages": [ - "docs/translate-api/languages/supported-languages", - "docs/translate-api/languages/enable-beta-languages", - "docs/translate-api/languages/language-release-process" - ] - }, - { - "group": "Updates", - "pages": [ - "docs/changelog", - "docs/getting-started/alpha-and-beta-features", - { - "group": "Breaking changes", - "pages": [ - "docs/getting-started/breaking-changes", - "docs/getting-started/breaking-changes/july-2024-deprecation-of-insecure-cipher-suites", - "docs/getting-started/breaking-changes/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key", - "docs/getting-started/breaking-changes/november-2025-deprecation-of-legacy-auth-methods" - ] - } - ] - } + "docs/getting-started/regional-endpoints" + ] + }, + { + "group": "Languages", + "pages": [ + "docs/translate-api/languages/supported-languages", + "docs/translate-api/languages/enable-beta-languages", + "docs/translate-api/languages/language-release-process" ] }, { @@ -159,6 +143,22 @@ "docs/cookbooks/use-deepl-with-llm-agents-mcp", "docs/cookbooks/translate-google-sheets" ] + }, + { + "group": "API Updates", + "pages": [ + "docs/changelog", + "docs/getting-started/alpha-and-beta-features", + { + "group": "Breaking changes", + "pages": [ + "docs/getting-started/breaking-changes", + "docs/getting-started/breaking-changes/july-2024-deprecation-of-insecure-cipher-suites", + "docs/getting-started/breaking-changes/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key", + "docs/getting-started/breaking-changes/november-2025-deprecation-of-legacy-auth-methods" + ] + } + ] } ] }, From b4a5676d579b5de2adc93cafc53a60587a7d6ba3 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Wed, 15 Apr 2026 17:30:23 -0400 Subject: [PATCH 5/5] docs: flatten single-page groups, move regional endpoints, rename pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move Regional endpoints from Getting Started to Going to Production - Flatten Customizations: remove Glossaries, Custom instructions, and Translation memories sub-groups (each had only one page) - Flatten Document Translation group (single page) to Translate API level - Rename "Client libraries" → "SDKs" - Rename "Test your API requests with Postman" → "Postman" - Add redirects from old nested paths to new flat paths - Fix internal link in api-reference/translate.mdx Co-Authored-By: Claude Opus 4.6 (1M context) --- api-reference/translate.mdx | 2 +- docs.json | 46 ++++++------------- docs/getting-started/client-libraries.mdx | 2 +- .../test-your-api-requests-with-postman.mdx | 2 +- .../{glossaries => }/set-up-a-glossary.mdx | 0 .../use-translation-memories.mdx | 0 .../write-effective-instructions.mdx | 0 .../handle-errors-and-large-files.mdx | 0 8 files changed, 18 insertions(+), 34 deletions(-) rename docs/translate-api/customizations/{glossaries => }/set-up-a-glossary.mdx (100%) rename docs/translate-api/customizations/{translation-memories => }/use-translation-memories.mdx (100%) rename docs/translate-api/customizations/{custom-instructions => }/write-effective-instructions.mdx (100%) rename docs/translate-api/{document-translation => }/handle-errors-and-large-files.mdx (100%) diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 3b570e5a..ef3020ec 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -295,7 +295,7 @@ error. The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages. - Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/translate-api/customizations/custom-instructions/write-effective-instructions). + Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/translate-api/customizations/write-effective-instructions). diff --git a/docs.json b/docs.json index 9bd75ae7..2c9f57fc 100644 --- a/docs.json +++ b/docs.json @@ -50,8 +50,7 @@ "docs/getting-started/deepl-developer-community", "docs/getting-started/open-api-spec" ] - }, - "docs/getting-started/regional-endpoints" + } ] }, { @@ -75,33 +74,13 @@ "docs/translate-api/text-translation/detect-languages" ] }, - { - "group": "Document Translation", - "pages": [ - "docs/translate-api/document-translation/handle-errors-and-large-files" - ] - }, + "docs/translate-api/handle-errors-and-large-files", { "group": "Customizations", "pages": [ - { - "group": "Glossaries", - "pages": [ - "docs/translate-api/customizations/glossaries/set-up-a-glossary" - ] - }, - { - "group": "Custom instructions", - "pages": [ - "docs/translate-api/customizations/custom-instructions/write-effective-instructions" - ] - }, - { - "group": "Translation memories", - "pages": [ - "docs/translate-api/customizations/translation-memories/use-translation-memories" - ] - } + "docs/translate-api/customizations/set-up-a-glossary", + "docs/translate-api/customizations/write-effective-instructions", + "docs/translate-api/customizations/use-translation-memories" ] }, { @@ -126,6 +105,7 @@ { "group": "Going to Production", "pages": [ + "docs/getting-started/regional-endpoints", "docs/going-to-production/pre-production-checklist", "docs/going-to-production/error-handling", "docs/going-to-production/solve-cors-errors", @@ -380,8 +360,10 @@ {"source": "/docs/best-practices/cors-requests", "destination": "/docs/going-to-production/solve-cors-errors"}, {"source": "/docs/best-practices/cost-control", "destination": "/docs/admin-api/control-costs"}, - {"source": "/docs/best-practices/custom-instructions", "destination": "/docs/translate-api/customizations/custom-instructions/write-effective-instructions"}, - {"source": "/docs/best-practices/document-translations", "destination": "/docs/translate-api/document-translation/handle-errors-and-large-files"}, + {"source": "/docs/best-practices/custom-instructions", "destination": "/docs/translate-api/customizations/write-effective-instructions"}, + {"source": "/docs/translate-api/customizations/custom-instructions/write-effective-instructions", "destination": "/docs/translate-api/customizations/write-effective-instructions"}, + {"source": "/docs/best-practices/document-translations", "destination": "/docs/translate-api/handle-errors-and-large-files"}, + {"source": "/docs/translate-api/document-translation/handle-errors-and-large-files", "destination": "/docs/translate-api/handle-errors-and-large-files"}, {"source": "/docs/best-practices/error-handling", "destination": "/docs/going-to-production/error-handling"}, {"source": "/docs/best-practices/language-detection", "destination": "/docs/translate-api/text-translation/detect-languages"}, {"source": "/docs/best-practices/pre-production-checklist", "destination": "/docs/going-to-production/pre-production-checklist"}, @@ -390,9 +372,11 @@ {"source": "/docs/learning-how-tos/examples-and-guides/translation-beginners-guide", "destination": "/docs/translate-api/text-translation/translate-text"}, {"source": "/docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications", "destination": "/docs/cookbooks/use-deepl-with-llm-agents-mcp"}, - {"source": "/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world", "destination": "/docs/translate-api/customizations/glossaries/set-up-a-glossary"}, + {"source": "/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world", "destination": "/docs/translate-api/customizations/set-up-a-glossary"}, + {"source": "/docs/translate-api/customizations/glossaries/set-up-a-glossary", "destination": "/docs/translate-api/customizations/set-up-a-glossary"}, {"source": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter", "destination": "/docs/translate-api/text-translation/use-context-for-better-results"}, - {"source": "/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories", "destination": "/docs/translate-api/customizations/translation-memories/use-translation-memories"}, + {"source": "/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories", "destination": "/docs/translate-api/customizations/use-translation-memories"}, + {"source": "/docs/translate-api/customizations/translation-memories/use-translation-memories", "destination": "/docs/translate-api/customizations/use-translation-memories"}, {"source": "/docs/learning-how-tos/examples-and-guides/placeholder-tags", "destination": "/docs/translate-api/text-translation/use-placeholder-tags"}, {"source": "/docs/learning-how-tos/examples-and-guides/translating-between-variants", "destination": "/docs/translate-api/text-translation/translate-between-variants"}, {"source": "/docs/learning-how-tos/examples-and-guides/enable-beta-languages", "destination": "/docs/translate-api/languages/enable-beta-languages"}, @@ -433,7 +417,7 @@ {"source": "/docs/resources/breaking-changes-change-notices", "destination": "/docs/getting-started/breaking-changes"}, {"source": "/docs/resources/breaking-changes-change-notices/:page*", "destination": "/docs/getting-started/breaking-changes/:page*"}, - {"source": "/api-reference/translation-memory", "destination": "/docs/translate-api/customizations/translation-memories/use-translation-memories"} + {"source": "/api-reference/translation-memory", "destination": "/docs/translate-api/customizations/use-translation-memories"} ], "integrations": { "cookies": { diff --git a/docs/getting-started/client-libraries.mdx b/docs/getting-started/client-libraries.mdx index 9f299dff..332176fe 100644 --- a/docs/getting-started/client-libraries.mdx +++ b/docs/getting-started/client-libraries.mdx @@ -1,5 +1,5 @@ --- -title: "Client libraries" +title: "SDKs" public: true mode: "wide" --- diff --git a/docs/getting-started/test-your-api-requests-with-postman.mdx b/docs/getting-started/test-your-api-requests-with-postman.mdx index e818fa7f..dd32f1e5 100644 --- a/docs/getting-started/test-your-api-requests-with-postman.mdx +++ b/docs/getting-started/test-your-api-requests-with-postman.mdx @@ -1,5 +1,5 @@ --- -title: "Test your API requests with Postman" +title: "Postman" description: "Use our official Postman collection to get familiar with and test the DeepL API." mode: "wide" public: true diff --git a/docs/translate-api/customizations/glossaries/set-up-a-glossary.mdx b/docs/translate-api/customizations/set-up-a-glossary.mdx similarity index 100% rename from docs/translate-api/customizations/glossaries/set-up-a-glossary.mdx rename to docs/translate-api/customizations/set-up-a-glossary.mdx diff --git a/docs/translate-api/customizations/translation-memories/use-translation-memories.mdx b/docs/translate-api/customizations/use-translation-memories.mdx similarity index 100% rename from docs/translate-api/customizations/translation-memories/use-translation-memories.mdx rename to docs/translate-api/customizations/use-translation-memories.mdx diff --git a/docs/translate-api/customizations/custom-instructions/write-effective-instructions.mdx b/docs/translate-api/customizations/write-effective-instructions.mdx similarity index 100% rename from docs/translate-api/customizations/custom-instructions/write-effective-instructions.mdx rename to docs/translate-api/customizations/write-effective-instructions.mdx diff --git a/docs/translate-api/document-translation/handle-errors-and-large-files.mdx b/docs/translate-api/handle-errors-and-large-files.mdx similarity index 100% rename from docs/translate-api/document-translation/handle-errors-and-large-files.mdx rename to docs/translate-api/handle-errors-and-large-files.mdx