fix(i18n): strip code fences from translations, translate nav labels#42
Merged
01programs merged 6 commits intomainfrom Mar 17, 2026
Merged
fix(i18n): strip code fences from translations, translate nav labels#4201programs merged 6 commits intomainfrom
01programs merged 6 commits intomainfrom
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three critical fixes for translation quality:
1. MDX code fence wrapping (63% of files broken)
The LLM was wrapping translations in
```mdxcode blocks, which broke Mintlify rendering.Fixes:
---frontmatter2. Navigation labels staying in English
Sidebar group/tab names (e.g., "Search", "Files", "Schedules") were not being translated.
Fixes:
update-docs-config.tsto translate labels via OpenAI3. 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:
translate-openapi.ts: Programmatically extracts only translatable fields (description, summary, title) and batch translates themtranslate-openapijob runs in parallel with MDX translationupdate-docs-config.ts: Adds language-specific OpenAPI paths to API tabsArchitecture
Test plan