docs: pipeline-generated pages (?, Languages, Voice) - #435
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/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
|
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}
| { | ||
| "lang": "en", | ||
| "name": "English", | ||
| "status": "stable", |
There was a problem hiding this comment.
Warning box exceeds recommended 1-2 sentence length
The Warning callout on BCP 47 language codes runs to four sentences. CLAUDE.md specifies callout boxes should be 1-2 sentences; longer content should be regular prose.
Suggested fix: Trim to: 'Language codes follow BCP 47 and can include region, script, and variant subtags (e.g. zh-Hans, pt-BR). Treat them as opaque identifiers — do not hardcode assumptions about their format. See Language codes and the release process for details.' Then move the BCP 47 library recommendation into the preceding paragraph as a sentence.
| --- | ||
|
|
||
| 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. | ||
|
|
There was a problem hiding this comment.
Intro paragraph covers endpoint behavior well but could hint at the two-endpoint structure earlier
The page covers both GET /v3/languages and GET /v3/languages/resources but the opening paragraph only mentions one endpoint. A reader skimming in 30 seconds may not realize both are covered.
Suggested fix: Add a second sentence to the intro: 'A companion endpoint, GET /v3/languages/resources, describes which side of a language pair (source or target) each feature requires.'
| [ | ||
| { | ||
| "name": "translate_text", | ||
| "features": [ |
There was a problem hiding this comment.
Caching section repeats the 'infrequently' rationale already stated in code comments
The prose in '## Caching the response' restates guidance that inline comments in the Python snippets already communicate ('Fetch once and cache — the language list changes infrequently'). Minor duplication.
Suggested fix: Remove the inline comments from the Python snippets (they now belong to the Caching section as prose) and keep the dedicated section. Or keep the comments and shorten the Caching section to one sentence plus the cross-reference link.
| 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). | ||
|
|
There was a problem hiding this comment.
Second curl example in beta section lacks response diff context
The curl request for include=beta is followed by a truncated response that overlaps heavily with the first response example. The only new information is the Latvian beta entry. The response block could be shortened or annotated to highlight what changed.
Suggested fix: Replace the full response block with a response that shows only the beta-specific entry (Latvian), preceded by a note like 'The response includes the same stable languages as before, plus any beta items. The additional entry looks like:'
| target = next((l for l in languages if l["lang"] == "de"), None) | ||
|
|
||
| supports_glossary = ( | ||
| source is not None |
There was a problem hiding this comment.
Link text in 'What to read next' could be more descriptive for the second item
'Using the Languages API' is slightly ambiguous as link text — it could describe this very page. CLAUDE.md requires descriptive link text.
Suggested fix: Rewrite to: 'See Language resource types and lookup patterns for the full v3 endpoint reference.'
| ```json | ||
| { | ||
| "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994", | ||
| "operation": "translate", |
There was a problem hiding this comment.
Tip for download window references upload time, not job completion
The Tip says 'You have 1 hour from the time the source file is uploaded to download all results.' It's worth confirming whether the window starts at upload time or at job completion time. If it starts at completion, the current wording is misleading for long-running jobs.
Suggested fix: Verify the timer start point against the API spec, then update the Tip to say either 'from the time the source file is uploaded' or 'from when each result reaches complete status', whichever is accurate.
| <Warning> | ||
| 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. | ||
| </Warning> | ||
|
|
There was a problem hiding this comment.
No guidance on polling backoff strategy
The guide recommends a 10-30 second polling interval but doesn't mention exponential backoff or warn against hammering the endpoint. Developers building production clients may hit rate limits without this guidance.
Suggested fix: Add one sentence after the polling interval recommendation: 'Avoid polling more frequently than every 10 seconds; use exponential backoff if you receive 429 responses.'
| "updated_at": "2026-10-01T04:03:03.333Z" | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
'There is no per-job limit on the number of targets' may be inaccurate
The sentence 'There is no per-job limit on the number of targets' is a strong claim. If a limit exists or is added later, this will silently mislead developers. The Reference link is already there for limits.
Suggested fix: If no target limit exists, soften to: 'See the Reference for any per-job target limits and concurrent job limits.' If a limit does exist, state it here.
|
|
||
| </Step> | ||
|
|
||
| <Step> |
There was a problem hiding this comment.
Step 3 shows a partial status response without explaining it is partial
The second JSON block in the Poll step shows only the 'results' array (one complete, one failed), not the full response. A reader following the example may not realize this is a trimmed excerpt.
Suggested fix: Add a brief label before the second code block, such as 'When processing completes, the response includes download URLs (abbreviated for clarity):'
Summary
Generated documentation pages from the agentic docs pipeline (run
20260911-145233).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/retrieve-supported-languages-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)