From 30b2446fb5534747cea1e3920942953c8900cbc8 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
<41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 11 Sep 2026 15:06:46 +0000
Subject: [PATCH] docs: add generated pages from pipeline run 20260911-145233
Generated 3 pages for: Languages, Voice, unknown
- docs/voice/translate-a-pre-recorded-audio-file.mdx: No guide (tutorial or how-to) covers the 'Translate Audio Files' endpoints
- docs/languages/retrieve-supported-languages-for-a-resource.mdx: No guide (tutorial or how-to) covers the 'Languages' endpoints
- docs/learning-how-tos/cookbook/google-sheets: docs/learning-how-tos/cookbook/google-sheets has under 100 words
---
docs.json | 6 +-
...eve-supported-languages-for-a-resource.mdx | 187 ++++++++++++++++
.../translate-a-pre-recorded-audio-file.mdx | 199 ++++++++++++++++++
3 files changed, 391 insertions(+), 1 deletion(-)
create mode 100644 docs/languages/retrieve-supported-languages-for-a-resource.mdx
create mode 100644 docs/voice/translate-a-pre-recorded-audio-file.mdx
diff --git a/docs.json b/docs.json
index b4873789..9f57f81c 100644
--- a/docs.json
+++ b/docs.json
@@ -110,6 +110,9 @@
"docs/resources/privacy"
]
}
+ ],
+ "pages": [
+ "docs/languages/retrieve-supported-languages-for-a-resource"
]
},
{
@@ -157,7 +160,8 @@
"docs/voice/understanding-voice-sessions",
"docs/voice/message-encoding",
"docs/voice/supported-voice-languages",
- "docs/voice/voice-api-requirements"
+ "docs/voice/voice-api-requirements",
+ "docs/voice/translate-a-pre-recorded-audio-file"
]
},
{
diff --git a/docs/languages/retrieve-supported-languages-for-a-resource.mdx b/docs/languages/retrieve-supported-languages-for-a-resource.mdx
new file mode 100644
index 00000000..67fe2e0c
--- /dev/null
+++ b/docs/languages/retrieve-supported-languages-for-a-resource.mdx
@@ -0,0 +1,187 @@
+---
+title: "Retrieve supported languages for a resource"
+description: "Query the Languages API to get the languages and features available for any DeepL resource, so your integration never relies on a hardcoded list."
+covers: [Languages]
+---
+
+The [`GET /v3/languages`](/api-reference/languages/retrieve-languages-by-resource) endpoint returns the languages supported by a specific DeepL resource, along with which features (formality, glossary, tag handling, and others) each language supports. Use it to populate language dropdowns, validate user input, and toggle feature availability in your integration.
+
+
+For new integrations, use `/v3/languages`. The `/v2/languages` endpoint remains available.
+
+
+You'll need a DeepL API key. Find yours at [deepl.com/your-account/keys](https://www.deepl.com/your-account/keys).
+
+## Fetch languages for a resource
+
+The `resource` parameter is required. It tells the API which DeepL product you're building for, so you get back the right set of languages and features.
+
+Set `resource` to the value that matches your use case — see the [API reference](/api-reference/languages/retrieve-languages-by-resource) for all valid values. This example uses `translate_text` for text translation:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json title="Example response (truncated)"
+[
+ {
+ "lang": "de",
+ "name": "German",
+ "status": "stable",
+ "usable_as_source": true,
+ "usable_as_target": true,
+ "features": {
+ "formality": { "status": "stable" },
+ "glossary": { "status": "stable" },
+ "tag_handling": { "status": "stable" }
+ }
+ },
+ {
+ "lang": "en",
+ "name": "English",
+ "status": "stable",
+ "usable_as_source": true,
+ "usable_as_target": false,
+ "features": {
+ "glossary": { "status": "stable" },
+ "tag_handling": { "status": "stable" }
+ }
+ },
+ {
+ "lang": "en-US",
+ "name": "English (American)",
+ "status": "stable",
+ "usable_as_source": false,
+ "usable_as_target": true,
+ "features": {
+ "glossary": { "status": "stable" },
+ "tag_handling": { "status": "stable" }
+ }
+ }
+]
+```
+
+The response is an array of language objects. See the [API reference](/api-reference/languages/retrieve-languages-by-resource) for the full field list.
+
+
+Do not hardcode assumptions about language code format. Codes follow BCP 47 and can include region, script, and variant subtags of varying length (e.g. `zh-Hans`, `pt-BR`). Treat them as opaque identifiers and use a BCP 47-compliant library if you need to parse them. See [Language codes and the release process](/docs/resources/language-release-process) for details.
+
+
+## Filter for valid source and target languages
+
+A language can be usable as a source, a target, both, or neither. Filter on `usable_as_source` and `usable_as_target` depending on what you need. For example, in Python:
+
+```python
+import requests
+
+# Fetch once and cache — the language list changes infrequently
+resp = requests.get(
+ "https://api.deepl.com/v3/languages",
+ params={"resource": "translate_text"},
+ headers={"Authorization": "DeepL-Auth-Key [yourAuthKey]"},
+)
+resp.raise_for_status()
+languages = resp.json()
+
+# --- Filter by direction ---
+source_languages = [l for l in languages if l["usable_as_source"]]
+target_languages = [l for l in languages if l["usable_as_target"]]
+
+# --- Check feature availability ---
+target = next((l for l in languages if l["lang"] == "de"), None)
+supports_formality = target is not None and "formality" in target["features"]
+```
+
+Note that `en` (generic English) is usable only as a source, while `en-US` and `en-GB` are usable only as targets. Your language selector for the target field should show the regional variants, not the base code.
+
+## Check feature availability for a language
+
+The `features` object on each language tells you which optional capabilities are available. A feature key is present in `features` only when that language supports it.
+
+To check whether a language supports formality, check for the `formality` key in its `features` object (as shown in the Python example above).
+
+Use this pattern to gate UI elements. If `formality` is absent from the target language's `features`, don't offer a formality option in your UI.
+
+Feature `status` values follow the same progression as language `status`: `stable`, `beta`, or `early_access`. By default, the endpoint returns only stable languages and features. To include beta items in the response, add `include=beta` to your query:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text&include=beta' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json title="Example response (truncated)"
+[
+ {
+ "lang": "de",
+ "name": "German",
+ "status": "stable",
+ "usable_as_source": true,
+ "usable_as_target": true,
+ "features": {
+ "formality": { "status": "stable" },
+ "glossary": { "status": "stable" },
+ "tag_handling": { "status": "stable" }
+ }
+ },
+ {
+ "lang": "lv",
+ "name": "Latvian",
+ "status": "beta",
+ "usable_as_source": true,
+ "usable_as_target": true,
+ "features": {
+ "tag_handling": { "status": "beta" }
+ }
+ }
+]
+```
+
+## Determine which language side a feature requires
+
+Some features require the source language to support them, others require the target, and some require both. To look this up programmatically, call [`GET /v3/languages/resources`](/api-reference/languages/retrieve-language-resources):
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/resources' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json title="Example response (truncated)"
+[
+ {
+ "name": "translate_text",
+ "features": [
+ { "name": "formality", "needs_target_support": true },
+ { "name": "glossary", "needs_source_support": true, "needs_target_support": true },
+ { "name": "tag_handling", "needs_source_support": true, "needs_target_support": true },
+ { "name": "auto_detection", "needs_source_support": true }
+ ]
+ }
+]
+```
+
+For the `translate_text` resource, glossary requires both the source and target language to support it. To check whether a specific language pair can use a glossary, use the `languages` list fetched in the example above:
+
+```python
+# Reuse the languages list fetched above — do not fetch again
+source = next((l for l in languages if l["lang"] == "en"), None)
+target = next((l for l in languages if l["lang"] == "de"), None)
+
+supports_glossary = (
+ source is not None
+ and target is not None
+ and "glossary" in source["features"]
+ and "glossary" in target["features"]
+)
+```
+
+## Caching the response
+
+The language list changes infrequently, only when DeepL adds or updates language support. Cache the response and refresh it on a schedule (daily is sufficient for most integrations) rather than calling the endpoint on every user request.
+
+When DeepL adds a new language, it goes through a staged release. See [Language codes and the release process](/docs/resources/language-release-process) for what to expect and how to write code that handles new codes gracefully.
+
+## What to read next
+
+- [Supported languages](/docs/getting-started/supported-languages) lists every language the DeepL API supports, with feature availability at a glance
+- [Using the Languages API](/docs/languages/using-the-languages-api) covers the full v3 endpoint reference and lookup patterns
\ No newline at end of file
diff --git a/docs/voice/translate-a-pre-recorded-audio-file.mdx b/docs/voice/translate-a-pre-recorded-audio-file.mdx
new file mode 100644
index 00000000..00198b87
--- /dev/null
+++ b/docs/voice/translate-a-pre-recorded-audio-file.mdx
@@ -0,0 +1,199 @@
+---
+title: "Translate a Pre-Recorded Audio File"
+description: "Submit a pre-recorded audio file to the DeepL Voice API and download translated text or audio output using the async job workflow."
+covers: [Translate Audio Files]
+---
+
+In this guide you'll translate a pre-recorded audio file by creating an async job, uploading the source file, polling until the job completes, and downloading each result. The workflow produces any combination of plain text transcripts, SRT subtitles, and translated speech audio from a single source file.
+
+For live audio streams, see the [Real-Time Voice Quickstart](/docs/voice/real-time-voice-quickstart).
+
+
+ **Closed alpha.** This API may change without notice and is only available to select DeepL customers. See [alpha and beta features](/docs/resources/alpha-and-beta-features) for details. To request access, contact your customer success manager.
+
+
+## Prerequisites
+
+- A DeepL API account with Voice Translate Job API access
+- An audio file in a [supported source format](/api-reference/jobs-voice-translate/reference#supported-source-audio-formats)
+- `curl` and a shell, or any HTTP client
+
+## The four-step workflow
+
+Translating a file is always four steps: create a job, upload the file, poll for completion, and download each result. Each step is described below using the same example: a 15 MB English MP3 (`podcast-episode-42.mp3`) translated into German plain text and Spanish audio.
+
+
+
+
+
+### Create a job
+
+Send a POST request to `/v1/jobs/voice/translate` with the source file metadata and your list of target outputs.
+
+```bash
+curl -X POST https://api.deepl.com/v1/jobs/voice/translate \
+ -H "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "source_file": {
+ "name": "podcast-episode-42.mp3",
+ "content_type": "audio/mpeg",
+ "content_length": 15728640
+ },
+ "parameters": {
+ "source_language": "en"
+ },
+ "targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" }
+ ]
+ }'
+```
+
+A `201` response returns three fields you'll need immediately:
+
+```json
+{
+ "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "upload_url": "https://assets.deepl.com/collections/a74d88fb-ed2a-4943-a664-a4512398b994/assets/b1c2d3e4-f5a6-7890-abcd-ef1234567890",
+ "signature": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+Save all three. The `upload_url` is where you'll PUT the file in the next step. The `signature` authorizes that upload. The `job_id` is how you check status and correlate results.
+
+
+ You have 5 minutes from job creation to complete the upload. If you miss the window, create a new job.
+
+
+
+
+
+
+### Upload the source file
+
+PUT your audio file directly to the `upload_url` from the previous response. Include the `signature` as a query parameter and set `Content-Type` to match the `content_type` you declared when creating the job.
+
+```bash
+curl -X PUT \
+ "https://assets.deepl.com/collections/a74d88fb-ed2a-4943-a664-a4512398b994/assets/b1c2d3e4-f5a6-7890-abcd-ef1234567890?signature=eyJhbGciOiJIUzI1NiIs..." \
+ -H "Content-Type: audio/mpeg" \
+ --data-binary @podcast-episode-42.mp3
+```
+
+A `200` response with no body confirms the upload succeeded. Processing begins immediately.
+
+
+ The `content_length` you declare when creating the job must exactly match the size of the file you upload. A mismatch causes the upload to be rejected.
+
+
+
+
+
+
+### Poll for status
+
+GET `/v1/jobs/voice/translate/{job_id}` to check progress. Results for each target are returned in the same order as the `targets` array in your create request.
+
+```bash
+curl https://api.deepl.com/v1/jobs/voice/translate/a74d88fb-ed2a-4943-a664-a4512398b994 \
+ -H "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY"
+```
+
+While processing is underway, each result has `"status": "processing"`:
+
+```json
+{
+ "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "operation": "translate",
+ "product": "voice",
+ "source_file": {
+ "name": "podcast-episode-42.mp3",
+ "content_type": "audio/mpeg",
+ "content_length": 15728640
+ },
+ "parameters": { "source_language": "en" },
+ "targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" }
+ ],
+ "results": [
+ { "status": "processing" },
+ { "status": "processing" }
+ ],
+ "created_at": "2026-10-01T01:03:03.444Z",
+ "updated_at": "2026-10-01T04:03:03.333Z"
+}
+```
+
+When a target finishes, its result entry gains `"status": "complete"` and a `download_url` plus a `signature` for that result:
+
+```json
+{
+ "results": [
+ {
+ "status": "complete",
+ "download_url": "https://assets.deepl.com/collections/a74d88fb/assets/c3d4e5f6",
+ "signature": "eyJhbGciOiJIUzI1NiIs..."
+ },
+ {
+ "status": "failed",
+ "error": { "message": "processing failed" }
+ }
+ ]
+}
+```
+
+Poll until every result is in a terminal state (`complete`, `failed`, or `downloaded`). A reasonable polling interval is 10-30 seconds for short files; longer files may take several minutes. Check the `updated_at` timestamp to detect whether the job has made progress since your last poll.
+
+Each target is processed independently. A failure on one target does not affect the others — download whichever results are `complete`.
+
+
+
+
+
+### Download results
+
+For each `complete` result, GET the `download_url` with the result's `signature` as a query parameter:
+
+```bash
+curl \
+ "https://assets.deepl.com/collections/a74d88fb/assets/c3d4e5f6?signature=eyJhbGciOiJIUzI1NiIs..." \
+ -o translation-de.txt
+```
+
+Repeat for each completed result. Save files with the appropriate extension for the output type (`text/plain` → `.txt`, `application/x-subrip` → `.srt`, audio types → the container format you requested).
+
+
+ Download results promptly. You have 1 hour from the time the source file is uploaded to download all results. Once all targets are downloaded, the job is deleted and returns `404`. For full limits, see the [Reference](/api-reference/jobs-voice-translate/reference#limits).
+
+
+
+
+
+
+## Handling partial failures
+
+Targets fail independently. Always check each result's `status` before downloading. If a target fails, the `error.message` field describes the problem. You cannot retry a failed target — create a new job for any targets that need to be re-processed.
+
+## Requesting multiple output types
+
+A single job can produce text, subtitles, and audio from the same source file. Add entries to the `targets` array:
+
+```json
+"targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "de", "type": "application/x-subrip" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" },
+ { "language": "fr", "type": "text/plain" }
+]
+```
+
+There is no per-job limit on the number of targets; see the [Reference](/api-reference/jobs-voice-translate/reference#limits) for concurrent job limits.
+
+## Next steps
+
+- [API Reference: Create Job](/api-reference/jobs-voice-translate/create-voice-translate-job) — full request and response schemas
+- [API Reference: Get Job Status](/api-reference/jobs-voice-translate/get-voice-translate-job-status) — status field definitions
+- [Reference: supported formats, languages, and limits](/api-reference/jobs-voice-translate/reference)
+- For live audio, see the [Real-Time Voice Quickstart](/docs/voice/real-time-voice-quickstart)
\ No newline at end of file