Skip to content

docs(document-translation): document Cat 1 file formats (IDML, XML, JSON, DITA, MIF)#387

Open
yoshiamakino wants to merge 1 commit into
DeepL:mainfrom
yoshiamakino:docs/cat1-format-support
Open

docs(document-translation): document Cat 1 file formats (IDML, XML, JSON, DITA, MIF)#387
yoshiamakino wants to merge 1 commit into
DeepL:mainfrom
yoshiamakino:docs/cat1-format-support

Conversation

@yoshiamakino

@yoshiamakino yoshiamakino commented Jul 7, 2026

Copy link
Copy Markdown

Summary

  • Add IDML, XML, JSON, DITA, and MIF to all supported-format listings (OpenAPI YAML/JSON, api-reference/document.mdx, docs/getting-started/about.mdx, Java cookbook).
  • Update XLIFF version wording everywhere to "versions 1.2, 2.0, and 2.1".
  • Update docs/resources/usage-limits.mdx: new rows for IDML (30 MB Pro), MIF (30 MB Pro), XML (10 MB), JSON (1 MB), DITA (5 MB); bump Word / PowerPoint / PDF from 30 MB → 100 MB on API Pro; rewrite XLIFF footnote.
  • Enrich docs/best-practices/document-translations.mdx:
    • Note the correct per-format size limits.
    • Add One source/target language pair per upload — behaviour is single-language-per-upload for most formats, with an XLIFF exception (per-segment) and a billing note that all content counts toward billed characters.
    • Add Same-language source and target are rejected (HTTP 400, incl. regional variants).
    • Add Format-specific gotchas covering XML (only text between tags; CDATA translated; ITS external rules 500), XLIFF (target overwrite; per-<file> lang ignored), DITA (.dita only; codeblock newline collapse), JSON (1 MB limit; embedded HTML/Markdown), IDML (font substitution; overset), and MIF (must be FrameMaker; UTF-8; MIF ≥ 8.00).

Test plan

  • Mintlify preview renders docs/best-practices/document-translations.mdx cleanly (headings, bullet spacing, code spans).
  • docs/resources/usage-limits.mdx table renders with correct new rows and 100 MB values for Word / PowerPoint / PDF (API Pro).
  • /api-reference/document shows the expanded format list in both the top listing and the file parameter description.
  • Auto-generated /api-reference/document/upload-and-translate-a-document picks up the OpenAPI updates.
  • docs/getting-started/about.mdx one-liner still reads cleanly.
  • Java cookbook snippet still parses.

…SON, DITA, MIF)

Add Cat 1 formats to all supported-format listings, update XLIFF version
wording to include 1.2/2.0/2.1, bump Word/PowerPoint/PDF API Pro size
cap to 100 MB, and add a Format-specific gotchas section to the
document-translation best-practices page.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant