Repository navigation
docs: pipeline-generated pages (?, Languages, Voice) - #447
github-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-supported-languages-for-a-deepl-api-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}
| "usable_as_target": true, | ||
| "features": { | ||
| "formality": { "status": "stable" }, | ||
| "glossary": { "status": "stable" }, |
There was a problem hiding this comment.
Numbered steps imply strict sequence; steps 3-4 are independent filters
Steps 3 and 4 are presented as sequential but they are independent operations (filter source/target vs. check feature availability). A developer building only a language selector doesn't need step 4, and vice versa. The numbered step format implies a strict linear workflow, which may mislead readers.
Suggested fix: Restructure step 4 as a separate H2 section ('Check feature availability') rather than a numbered step in the same sequence, or add a brief note after step 2 clarifying that steps 3 and 4 are independent follow-ons the reader can use based on their needs.
| } | ||
| }, | ||
| { | ||
| "lang": "en-US", |
There was a problem hiding this comment.
Python examples use different API key placeholder styles
The curl examples use [yourAuthKey] (line 40, 130, 143) while the Python examples use "YOUR_API_KEY" (lines 83, 96). Placeholder styles should be consistent across all examples in the same document.
Suggested fix: Standardize to one placeholder style throughout. Using YOUR_API_KEY (no brackets) in both curl and Python examples is idiomatic and consistent: change [yourAuthKey] in curl examples to YOUR_API_KEY.
|
|
||
| _, targets = get_languages("YOUR_API_KEY", "translate_text") | ||
| print(supports_formality("de", targets)) # True | ||
| print(supports_formality("en-US", targets)) # False |
There was a problem hiding this comment.
Step 5 contains two separate curl examples without explanation of when to combine parameters
The two curl examples in step 5 show include=beta alone and then include=beta&include=external together, but don't explain that include is a repeatable parameter or why the second example uses both. A reader may not realize they can combine these independently.
Suggested fix: Add one sentence before or between the two examples explaining that include is a repeatable query parameter and can be combined, e.g. 'You can combine multiple include values by repeating the parameter.'
| <Info> | ||
| `GET /v3/languages` replaces the deprecated `GET /v2/languages` endpoint. If you're currently using `/v2/languages`, see the [migration guide](/docs/languages/migrating-from-v2-languages). | ||
| </Info> | ||
|
|
There was a problem hiding this comment.
Info box references a migration guide that may not exist yet
The <Info> block links to /docs/languages/migrating-from-v2-languages. If this page doesn't exist, the link will be broken. The Next steps section also links to it.
Suggested fix: Verify the migration guide exists before publishing. If it doesn't exist yet, remove the link or replace with a placeholder note and file a ticket to create the page.
|
|
||
| - A DeepL API key. Get one from [your account page](https://www.deepl.com/your-account/keys). | ||
| - If you're on the Free plan, replace `https://api.deepl.com` with `https://api-free.deepl.com` in all examples. | ||
|
|
There was a problem hiding this comment.
Prerequisites block mixes account setup with request configuration
The Prerequisites section contains two items: getting an API key (one-time account setup) and swapping the base URL for Free plan users (a per-request concern). Mixing these could cause Free plan users to miss the URL swap if they already have an API key.
Suggested fix: Move the Free plan base URL note into a <Note> or <Tip> callout placed just before the first curl example, keeping prerequisites focused on what you need before you start (the API key only).
| After your file is uploaded, DeepL begins processing. Check the job status by polling the status endpoint with your `job_id`. | ||
|
|
||
| ```bash | ||
| curl https://api.deepl.com/v1/jobs/voice/translate/a74d88fb-ed2a-4943-a664-a4512398b994 \ |
There was a problem hiding this comment.
Status lifecycle mention could link to reference for completeness
The status transition sequence ('pending → uploaded → processing → complete') is described inline but there is no link to the API reference for the full list of terminal states or error codes. Developers debugging failures will want more detail.
Suggested fix: Add a parenthetical link after the status lifecycle description: 'See the Get Job Status reference for all possible status values and error codes.'
|
|
||
| Save the `job_id` — you'll need it to poll for status. The `upload_url` is a pre-signed URL; save that too. | ||
|
|
||
| <Warning> |
There was a problem hiding this comment.
Step 2 upload request omits the Signature header if required
The create-job response includes a signature field alongside the upload_url, but the Step 2 curl example does not use it. If the signature must be passed as a header or query parameter during upload, the example is incomplete and non-runnable. If it is not needed for upload (only for download), the guide should explicitly say what the signature is for.
|
|
||
| ```json | ||
| { | ||
| "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994", |
There was a problem hiding this comment.
No guidance on what to do if the upload window expires
The Warning notes that the 5-minute upload window can expire but only says 'you'll need to create a new one.' Adding one sentence on what state the original job will be in (and whether it can be queried) would help developers clean up correctly.
Suggested fix: Append to the Warning: 'The expired job's status will reflect the abandonment; you can discard the original job_id.'
| ## The four-step workflow | ||
|
|
||
| Translating a file always follows the same four steps: | ||
|
|
There was a problem hiding this comment.
API Free plan base URL note is repeated context, not progressive
The note about api-free.deepl.com is mentioned here but likely appears in other docs in the same section. If there is a shared prerequisites or getting-started page that covers this, a link there would be cleaner than repeating it inline.
| Poll every 5–10 seconds with exponential backoff until all results reach a terminal status (`complete`, `failed`, or `downloaded`). For files close to the 3-hour or 1 GB limit, allow up to 30 minutes of polling before treating the job as stalled. | ||
|
|
||
| When a target completes, its result entry gains a `download_url` and `signature`: | ||
|
|
There was a problem hiding this comment.
Handling partial failures section is brief and could be more actionable
The 'Handling partial failures' section is only two sentences and doesn't show an example of the error structure or give guidance on which error messages are retryable vs. permanent.
Suggested fix: Expand with one concrete example: show an error object with a realistic message, and note whether any error types indicate a retryable condition (e.g., transient vs. permanent failures). Alternatively, link to the reference for the error schema.
Summary
Generated documentation pages from the agentic docs pipeline (run
20260922-112908).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-supported-languages-for-a-deepl-api-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)