docs: pipeline-generated pages (?, Languages, Voice) - #430
docs: pipeline-generated pages (?, Languages, Voice)#430github-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-which-languages-and-features-are-supported-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
|
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}
| { "name": "auto_detection", "needs_source_support": true } | ||
| ] | ||
| } | ||
| ] |
There was a problem hiding this comment.
Step 4 curl examples missing sample responses
The three curl examples in Step 4 (filter by target, filter by formality, include beta) show requests but no sample responses or sample jq output. Per CLAUDE.md, API requests should be paired with sample responses. The jq examples especially would benefit from showing what the filtered output looks like.
Suggested fix: After each curl+jq command, add a short example response block showing 2-3 items from the filtered output, e.g. [{"lang": "de", "name": "German"}, {"lang": "fr", "name": "French"}]. For the include=beta example, show a response entry with status: "beta".
| The `resource` query parameter is required. It tells the API which DeepL product you're querying language support for: | ||
|
|
||
| | **Value** | **Use when building against...** | | ||
| |---|---| |
There was a problem hiding this comment.
Table alignment: left-align header row
The resource table uses bold in the header cells (**Value**, **Use when building against...**) but CLAUDE.md says to use bold headers — that's fine — however the alignment specifiers |---|---| produce default (left) alignment, which is correct for text columns. No action needed on alignment itself, but the separator row |---|---| could be |:---|:---| to make the left-alignment explicit and consistent with any tooling that reads the markdown.
| |---|---| | |
| |:---|:---| |
| `GET /v3/languages` replaces the deprecated `GET /v2/languages` endpoint. If you're currently using v2, see the [migration guide](/docs/languages/migrating-from-v2-languages). | ||
| </Info> | ||
|
|
||
| ## Before you start |
There was a problem hiding this comment.
Info box migration guide link may not exist yet
The Info box references /docs/languages/migrating-from-v2-languages. If this page doesn't exist yet, it will produce a broken link. Verify the target page exists before publishing.
| ## Before you start | |
| ## Before you start |
| --header "Authorization: DeepL-Auth-Key $DEEPL_API_KEY" \ | ||
| | jq '[.[] | select(.usable_as_target == true and .features.formality != null) | {lang, name}]' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
"What to do with this data" section heading is informal
The heading "What to do with this data" is slightly informal and inconsistent with the imperative/action style used elsewhere (Steps 1-4, Next steps). A more direct heading would better fit the guide's tone.
Suggested fix: Rename to "Common patterns" or "Apply the response data" to match the task-oriented voice used throughout.
| ] | ||
| }' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Tip about api-free.deepl.com placed in Step 1 interrupts the curl response example flow
The Tip about the Free API URL appears between the response JSON and the guidance about saving the job_id and upload_url. This breaks the reader's flow at a point where they should be processing the response. It would be less disruptive at the top of the page or in the Prerequisites.
Suggested fix: Move the Tip to the Prerequisites section, after the API key bullet, where it fits naturally as a setup consideration.
| { "status": "processing" }, | ||
| { "status": "processing" } | ||
| ], | ||
| "created_at": "2026-10-01T01:03:03.444Z", |
There was a problem hiding this comment.
extensions dict in download_results is fragile and not extensible
The extensions dictionary maps full content-type strings (including codec params) to file extensions. A developer who requests a different audio format (e.g. 'audio/mpeg') will get 'bin' as the extension. This is a teaching example but the pattern being taught is brittle.
Suggested fix: Add a comment explaining the limitation: '# Extend this map for other output types you request' and optionally show how to parse the base media type from the content_type string using .split(';')[0] as a fallback.
| The response contains the job ID and a pre-signed upload URL: | ||
|
|
||
| ```json | ||
| { |
There was a problem hiding this comment.
Step 2 curl example hardcodes the upload URL instead of referencing the variable from Step 1
The curl command in Step 2 uses a literal upload URL. Following the guide, a developer might not realize this is the upload_url value from Step 1's response. The connection between steps is clear in prose but not reinforced in the code.
Suggested fix: Add a one-line comment above the curl command: '# Use the upload_url from the Step 1 response' to make the connection explicit without adding prose.
| ## Upload the source file | ||
|
|
||
| PUT your audio file directly to the `upload_url` from the previous step. This is a direct upload to object storage, not to the DeepL API, so no authorization header is needed. | ||
|
|
There was a problem hiding this comment.
No guidance on retry or backoff strategy for polling
Step 3 says 'Poll every 10-30 seconds' but gives no guidance on when to give up or how to handle transient HTTP errors during polling. The Python script has no timeout or max-retry logic. For a podcast episode, processing could take minutes.
Suggested fix: Add a sentence in the Step 3 prose noting a reasonable timeout (e.g. 'For a 15 MB file, expect 2-5 minutes of processing time') and add a max_attempts parameter to poll_until_done in the script with a clear error when exceeded.
Summary
Generated documentation pages from the agentic docs pipeline (run
20260908-082715).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-which-languages-and-features-are-supported-for-a-resource.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)