docs: pipeline-generated pages (?, Languages, Voice) - #415
docs: pipeline-generated pages (?, Languages, Voice)#415github-actions[bot] wants to merge 1 commit into
Conversation
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/check-feature-availability-for-a-language-pair.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
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| @@ -0,0 +1,216 @@ | |||
| --- | |||
| title: "Check feature availability for a language pair" | |||
There was a problem hiding this comment.
Frontmatter description could be more specific about the outcome
The description accurately describes the mechanism but doesn't tell the developer what they will be able to do after reading. It focuses on the endpoint rather than the developer's goal.
| title: "Check feature availability for a language pair" | |
| title: "Check feature availability for a language pair" | |
| description: "Learn how to query the v3/languages endpoints to determine which features — formality, glossaries, tag handling — are available for a specific source and target language pair." |
|
|
||
| return available | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Python example missing error handling for failed HTTP requests
The production-like fetch block (lines ~148-168) calls .json() directly on the response without checking for HTTP errors. If the API returns a 4xx or 5xx, .json() may succeed but return an error body, silently producing bad data. The guide is close to production-like in scope, so a minimal guard is appropriate.
Suggested fix: Add .raise_for_status() after each .get(...) call and before .json(), e.g.: resp = requests.get(..., headers=HEADERS); resp.raise_for_status(); languages = resp.json()
| headers=HEADERS, | ||
| ).json() | ||
|
|
||
| languages_by_code = {lang["lang"]: lang for lang in languages} |
There was a problem hiding this comment.
Step 4 is optional but numbered as a step
Labeling an optional step as 'Step 4' implies it is part of the required flow. Readers following the numbered steps may feel they must complete it.
Suggested fix: Rename the heading to '## Including beta languages (optional)' and remove it from the numbered step sequence, or add a clear note at the start of the section: 'This step is optional. Skip it if you only need stable languages.'
| target_code="de", | ||
| resource_name="translate_text", | ||
| ) | ||
| print(features) |
There was a problem hiding this comment.
Caching section lacks a concrete TTL recommendation
'Once daily' is mentioned but only as a suggestion alongside 'application startup.' A concrete default TTL would be more actionable for developers deciding how to implement caching.
Suggested fix: Add a specific recommended TTL, e.g.: 'Cache responses for up to 24 hours. If your application serves many users, refresh on startup and then on a fixed schedule rather than per-request.'
| { "name": "auto_detection", "needs_source_support": true } | ||
| ] | ||
| } | ||
| ] |
There was a problem hiding this comment.
check_pair_features docstring uses dict -> instead of arrow
The docstring says 'Returns a dict of feature -> status' using an ASCII arrow. This is a minor style inconsistency; Python docstrings conventionally use '->' for return type hints in signatures, but prose descriptions typically use plain English.
Suggested fix: Rewrite docstring line to: 'Returns a dict mapping feature name to status string for a given source/target pair and resource.'
| { | ||
| "status": "complete", | ||
| "download_url": "https://assets.deepl.com/collections/a74d88fb/assets/c3d4e5f6", | ||
| "signature": "eyJhbGciOiJIUzI1NiIs..." |
There was a problem hiding this comment.
Result ordering not guaranteed by spec — asserting it may be misleading
The doc states 'Results appear in the same order as the targets array in your create request.' If this is not guaranteed by the API contract (only by current implementation), developers relying on positional indexing could have fragile code. Consider adding a caveat or recommending keying on a stable field if one exists.
| "signature": "eyJhbGciOiJIUzI1NiIs..." | |
| "signature": "eyJhbGciOiJIUzI1NiIs...", | |
| "_note": "Results currently appear in the same order as the targets array, but use the result's language and type fields if available to confirm identity." |
|
|
||
| Fetch each completed result using its `download_url`: | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
Download step warns 'download each result only once' but does not explain recovery if download fails mid-stream
The warning that status transitions to downloaded after a single fetch, combined with a 1-hour expiry, is a real developer pitfall. The doc should advise saving to a temp file before processing, or clarify whether a partially-downloaded result can be retried.
| ```bash | |
| > **Note:** If a download fails partway through, retry immediately — the status transitions to `downloaded` only after a successful HTTP 200 response, not on a partial transfer. Save to a temp file and rename on success to avoid processing incomplete data. |
| UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.upload_url') | ||
| echo "Job ID: $JOB_ID" | ||
|
|
||
| # Step 2: Upload file |
There was a problem hiding this comment.
Shell script uses positional filename derived from URL, which may be opaque
The script names downloaded files by extracting the last path segment of the download URL (a UUID), producing filenames like result-c3d4e5f6. This is hard to map back to the target language/type. A comment explaining the limitation and suggesting a better naming strategy would help developers adapt the script.
Suggested fix: Add a comment above the FILENAME line: '# URL-based name is opaque; in production, track index alongside download URL to name files by language/type (e.g., translation-de.txt).'
| "status": "failed", | ||
| "error": { "message": "processing failed" } | ||
| } | ||
| ] |
There was a problem hiding this comment.
No mention of rate limits or recommended maximum polling frequency
The doc recommends starting at 5-second intervals and backing off to 30 seconds, but does not mention whether there is an enforced rate limit on the status endpoint. Developers may aggressively poll and hit errors. If a rate limit exists, document it; if not, a note that no hard limit exists but courteous polling is recommended would help.
Suggested fix: Add after the polling strategy sentence: 'The status endpoint does not enforce a strict rate limit, but polling more often than every 5 seconds is unlikely to reduce wait time and may be throttled in a future update.' Adjust if an actual limit exists.
| @@ -0,0 +1,239 @@ | |||
| --- | |||
| title: "Translate a Pre-Recorded Audio File" | |||
There was a problem hiding this comment.
Frontmatter description could be slightly more specific about the async pattern
The description is good and action-oriented, but 'async job workflow' is somewhat abstract. Mentioning the polling step would make it more precise and distinctive.
| title: "Translate a Pre-Recorded Audio File" | |
| title: "Translate a Pre-Recorded Audio File" | |
| description: "Submit a pre-recorded audio file to DeepL Voice, poll for completion, and download plain text, SRT, or audio results in one or more target languages." |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Summary
Generated documentation pages from the agentic docs pipeline (run
20260728-195522).Families: Languages, Voice, unknown
Model: claude-sonnet-4-6
Pages added/updated
docs/voice/translate-a-pre-recorded-audio-file.mdx— missing_group_coveragedocs/languages/check-feature-availability-for-a-language-pair.mdx— missing_group_coveragedocs/learning-how-tos/cookbook/google-sheets— expanded thin pageQuality checks
How to review
mint devto preview locallyGenerated by the agentic docs pipeline (
pipeline/generate.py)