docs: pipeline-generated pages (?, Languages, Voice) - #428
docs: pipeline-generated pages (?, Languages, Voice)#428github-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/query-language-and-feature-availability-dynamically.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
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| ```json | ||
| // Example response (truncated) | ||
| [ |
There was a problem hiding this comment.
Response code block uses comment syntax instead of label
The JSON response block uses a // Example response (truncated) comment inside the JSON, which is not valid JSON and could confuse readers or tooling. The Step 3 response block (line 107) has the same pattern. Use the Mintlify code block title attribute instead, e.g. ```json Example response (truncated).
| [ | |
| [ |
|
|
||
| ```text Example output | ||
| Source languages: ['ar', 'bg', 'cs', 'da', 'de', 'el', 'en', ...] | ||
| Target languages: ['ar', 'bg', 'cs', 'da', 'de', 'el', 'en-GB', 'en-US', ...] |
There was a problem hiding this comment.
Step 3 Python example lacks raise_for_status calls
The Step 2 Python example calls response.raise_for_status() for good practice, but the Step 3 example makes two HTTP calls (languages_response and resources_response) without calling .raise_for_status() on either. This inconsistency within the same doc could lead readers to omit error handling in production code.
Suggested fix: Add languages_response.raise_for_status() after line ~118 and resources_response.raise_for_status() after line ~125 in the Step 3 code block.
|
|
||
| ```text Example output | ||
| Source languages: ['ar', 'bg', 'cs', 'da', 'de', 'el', 'en', ...] | ||
| Target languages: ['ar', 'bg', 'cs', 'da', 'de', 'el', 'en-GB', 'en-US', ...] |
There was a problem hiding this comment.
No output shown for Step 3 Python example
Step 2 includes an example output block showing what the print statements produce. Step 3 ends with a print statement but shows no example output, making it harder for readers to verify they are on the right track. This is inconsistent with Step 2 and the Diataxis tutorial principle of showing visible results at each step.
| Target languages: ['ar', 'bg', 'cs', 'da', 'de', 'el', 'en-GB', 'en-US', ...] | |
| Target languages: ['ar', 'bg', 'cs', 'da', 'de', 'el', 'en-GB', 'en-US', ...] |
Glossary available for DE→EN-US: True
| translate_text_resource = next(r for r in resources if r["name"] == "translate_text") | ||
| translate_text_features = translate_text_resource["features"] | ||
|
|
||
|
|
There was a problem hiding this comment.
Caching section is missing a heading level anchor and could be a Step
The 'Caching the response' section is written as a numbered-step guide but is not labeled Step 5. The other sections use 'Step N:' headers. This inconsistency breaks the parallel structure of the guide. If caching is a recommended part of the workflow, label it Step 5; if it is supplementary, keep it as-is but note it is optional in the heading (e.g. 'Caching the response (recommended)').
| @@ -0,0 +1,246 @@ | |||
| --- | |||
| title: "Query language and feature availability dynamically" | |||
There was a problem hiding this comment.
Frontmatter description slightly exceeds recommended scanability but is acceptable
The description is 155 characters, action-oriented, and specific. No change required, but worth confirming it renders fully in search snippets and social previews.
| The Voice Translate Job API translates pre-recorded audio files asynchronously. You submit a file, poll a status endpoint until results are ready, then download them. This guide walks through the complete flow using a podcast episode as the example: one English MP3 in, German plain text and Spanish audio out. | ||
|
|
||
| For live audio that needs low-latency results, see the [real-time Voice API](/docs/voice/overview) instead. | ||
|
|
There was a problem hiding this comment.
Two Warning callouts on a single page
CLAUDE.md limits callout boxes to no more than 2 per page. This page has exactly 2 (alpha warning at line 10, upload key warning at line 57). That is at the limit; if any content is added later it will exceed it. More importantly, the alpha warning could be a Note instead of a Warning since it is informational rather than describing something that causes bugs. Consider demoting it to a to preserve the Warning slot for the genuinely destructive mistake (including the API key in the upload request).
Suggested fix: Change the first callout from to so the two Warning budget is not consumed by informational copy.
|
|
||
| ```bash | ||
| curl "https://api.deepl.com/v1/jobs/voice/translate/a74d88fb-ed2a-4943-a664-a4512398b994" \ | ||
| --header "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY" |
There was a problem hiding this comment.
Hardcoded content_type in Python create_job, not derived from the target list
The source file's content_type is hardcoded to 'audio/mpeg' in the create_job function. This is correct for the example file, but a reader copying this as a starting point for other formats will miss the need to change it. A brief inline comment explaining that this should match the actual file would help.
Suggested fix: Add a comment on the content_type line: "content_type": "audio/mpeg", # must match the actual file format
| "content_type": "audio/mpeg", | ||
| "content_length": 15728640 | ||
| }, | ||
| "parameters": { "source_language": "en" }, |
There was a problem hiding this comment.
poll_until_done does not use results from the job response
The function re-fetches the full job via GET and reads data['results'], but the 'downloaded' terminal state listed in the code may never actually be returned by the API mid-poll — it would be surfaced only if the result was already consumed. This is a minor accuracy concern; verify whether 'downloaded' is a realistic terminal state the polling loop will encounter, or remove it from the terminal set to avoid confusing readers.
Suggested fix: null
| "status": "failed", | ||
| "error": { "message": "processing failed" } | ||
| } | ||
| ] |
There was a problem hiding this comment.
No mention of the signature field returned with results
The completed job status example response (line ~135) shows a signature field alongside download_url, but the guide never explains what it is or whether it is needed for the download. Readers may wonder if they need to pass it in the download request. A single sentence clarifying that the signature is for verification only and the download URL is self-contained would close the gap.
| ] | |
| ] | |
| } |
The signature field can be used to verify result integrity but is not required to download the file.
|
|
||
| ## Step 2: Upload the source file | ||
|
|
||
| PUT the audio file directly to the `upload_url` from the previous response. You must complete the upload within 5 minutes of creating the job. |
There was a problem hiding this comment.
Python example omits os.path.getsize in favour of seek/tell; worth a comment
The file size is obtained with seek(0,2)/tell() rather than os.path.getsize(). This is correct and avoids a race condition, but looks non-idiomatic to many Python readers. A one-line comment explaining why would match CLAUDE.md's 'comment why not what' principle.
Suggested fix: Add comment above the seek/tell block: # Use seek/tell rather than os.path.getsize to avoid a race if the file changes
Summary
Generated documentation pages from the agentic docs pipeline (run
20260903-175940).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/query-language-and-feature-availability-dynamically.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)