Skip to content

fix(i18n): strip code fences from translations, translate nav labels#42

Merged
01programs merged 6 commits intomainfrom
fix/i18n-code-fence-and-nav-labels
Mar 17, 2026
Merged

fix(i18n): strip code fences from translations, translate nav labels#42
01programs merged 6 commits intomainfrom
fix/i18n-code-fence-and-nav-labels

Conversation

@01programs
Copy link
Copy Markdown
Collaborator

@01programs 01programs commented Mar 17, 2026

Summary

Three critical fixes for translation quality:

1. MDX code fence wrapping (63% of files broken)

The LLM was wrapping translations in ```mdx code blocks, which broke Mintlify rendering.

Fixes:

  • Updated prompt to explicitly forbid code fences
  • Added post-processing to strip fences if they appear
  • Added validation that output starts with --- frontmatter

2. Navigation labels staying in English

Sidebar group/tab names (e.g., "Search", "Files", "Schedules") were not being translated.

Fixes:

  • Updated update-docs-config.ts to translate labels via OpenAI
  • Added translation cache to avoid redundant API calls

3. OpenAPI descriptions not translated (NEW)

API field descriptions (the gray text in API reference pages) come from OpenAPI spec files and were not being translated.

Fixes:

  • Added translate-openapi.ts: Programmatically extracts only translatable fields (description, summary, title) and batch translates them
  • Preserves all technical fields exactly (property names, types, enums, URLs)
  • Updated workflow: New translate-openapi job runs in parallel with MDX translation
  • Updated update-docs-config.ts: Adds language-specific OpenAPI paths to API tabs

Architecture

                    ┌──────────────────────────────────────┐
                    │              setup                    │
                    └────────────────┬─────────────────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
           ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
           │ translate-    │ │ translate-    │ │ translate-    │
           │ openapi       │ │ catchup (MDX) │ │ incremental   │
           └───────────────┘ └───────────────┘ └───────────────┘
                    │                │                │
                    └────────────────┴────────────────┘
                                     │
                    ┌────────────────▼─────────────────────┐
                    │              deploy                   │
                    └──────────────────────────────────────┘

Test plan

  • Merge PR
  • Trigger workflow manually (or wait for next push to main)
  • Verify MDX pages render correctly (no raw MDX code)
  • Verify sidebar labels are translated
  • Verify API field descriptions (gray text) are translated
  • Verify API property names, types stay in English

Frederic Schulz added 6 commits March 17, 2026 18:34
Two critical fixes for translation quality:

1. MDX code fence issue: LLM was wrapping translations in ```mdx blocks
   - Updated prompt to explicitly forbid code fences
   - Added post-processing to strip fences if they appear
   - Added validation that output starts with frontmatter

2. Navigation labels: Sidebar group/tab names were staying in English
   - Updated update-docs-config.ts to translate labels via OpenAI
   - Added translation cache to avoid redundant API calls

Both issues affected 63% of translated files (417/660).
Re-run workflow to regenerate all translations.
Translates OpenAPI specification files (descriptions, summaries, titles)
to all target languages while preserving technical fields.

Changes:
- Add translate-openapi.ts: Programmatically extracts translatable fields,
  batch translates them, preserves all technical fields exactly
- Update workflow: Add translate-openapi job (runs parallel to MDX translation)
- Update update-docs-config.ts: Add language-specific OpenAPI to API tabs

This ensures API field descriptions (the gray text) are translated
while property names, types, and technical values stay in English.
The explicit keepEnglish/brandTerms lists were unnecessary - GPT-4o
naturally recognizes technical terms and preserves them. The prompt
now provides structural guidance (what categories to preserve) rather
than brittle hardcoded lists.

Removed:
- glossary.json
- Glossary interface and loading code
- Explicit term lists in prompt

The prompt now describes WHAT to preserve (code blocks, inline code,
URLs, technical acronyms) rather than listing specific terms.
@01programs 01programs merged commit bfbf702 into main Mar 17, 2026
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