# General Translation Knowledge Base: How do I translate a Mintlify docs site? URL: https://generaltranslation.com/en-GB/kb/translate-mintlify-docs.mdx Docs index: https://generaltranslation.com/llms.txt Description: Write a translated copy of every page in a folder per language and add each language to the docs.json navigation. General Translation's AI agent, Locadex, opens a pull request that adds the translated pages and per-language navigation, then translates later changes. Category: Workflow Tools Last updated: 2026-10-21 Authors: Kevin Liu, Kevin Wu Published: 2026-10-21 Translating a Mintlify docs site means writing a copy of every page in a folder per language and listing each language in the `languages` array of the `docs.json` navigation. Pages mix prose with code blocks, MDX components, frontmatter and links, so the prose and the `title` and `description` fields need translating, code and components must stay intact, and internal links must point to pages in the reader's language. Every edit to a source page then leaves its translations out of date until someone redoes them. ## Video The video is narrated in English, with English captions. [How do I translate a Mintlify docs site?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-translate-mintlify-docs.mp4) (47 secs) General Translation lets you choose languages, and Locadex opens a translation pull request. Authorize the General Translation app on GitHub, choose your docs repository in the Dashboard, create an automation from the Generate translations and push template for Mintlify, run its setup with your languages, and merge the pull request that adds a navigation entry per language and the translated pages. ## Ways to translate a Mintlify site | Approach | What it does well | What it leaves to you | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Mintlify's `languages` navigation, translated by hand | Builds a language switcher and a page tree per language from `docs.json` | Writing every translated page into its language folder, writing a full navigation per language, and tracking which translations each source edit has made stale | | Google Translate | Translates a page you paste in, with no set-up | It translates each passage in isolation; separating prose from code and components, and writing the folders and the navigation, are up to you | | A script on an AI API (OpenAI API, Claude API) | Can be told to translate prose and leave code blocks and components alone | A script that protects MDX syntax, keeps product terms consistent across pages, writes the folders and navigation, and reruns when pages change | | General Translation (Locadex) | Opens a pull request with the translated pages, per-language navigation and localised links, then translates each change on the trigger you choose | Reviewing and merging the set-up pull request, then reviewing later pull requests or turning on **Auto-merge** | Use Mintlify's navigation with hand translation when translators cover a few pages that rarely change; use Google Translate or a one-off AI API script for a single pass over a small, stable site. Use General Translation when the docs change with every release and each language has to keep pace. ## Translate Mintlify docs with Locadex General Translation translates Mintlify docs with Locadex, its AI agent, which requires a Starter or Enterprise plan. 1. In the Dashboard, connect GitHub under **Project > Integrations > Catalog**. 2. Under **Project > Automations**, create an automation from **Generate translations and push** with **Mintlify** as the framework. 3. Click **Run setup** and choose your languages. 4. Review and merge the pull request that Locadex opens. The pull request adds a `gt.config.json`, a `docs.json` navigation entry per language, and the translated pages, in which code and components keep their structure and links to translated pages stay in the reader's language. The **Run setup** dialogue for Mintlify has a **Hide default locale in URL paths** toggle, which is on by default: source pages keep their current paths, and each translated language gets its own locale folder, such as `/es/...`. If you turn the toggle off, the source pages also move into a locale folder (English pages move to `/en/...`), which changes their URLs. ## Keep translations current After that, Locadex runs when a pull request changes (the default) or when a commit is pushed. Each run applies the project's assigned Context Groups (Glossary and Custom Prompts), which your app can share, so product names match in both. The [Mintlify Quickstart](/docs/integrations/mintlify/quickstart) has the full steps. ## Related questions - [What does the Locadex agent do?](https://generaltranslation.com/en-GB/kb/what-is-locadex.mdx): Locadex is General Translation's AI agent which internationalises your code and translates your content in your GitHub repository. Its automations run when a pull request is opened, when a commit is pushed, or when you start one, and every change arrives as a pull request. - [How do I translate content in Sanity?](https://generaltranslation.com/en-GB/kb/translate-sanity-content.mdx): Store each language as its own document or as a value per locale in each field, then translate the source into every target locale. General Translation's gt-sanity plugin adds a Translate action to Sanity Studio and, by default, imports each translation as a draft you review and publish. - [How do I translate content in Storyblok?](https://generaltranslation.com/en-GB/kb/translate-storyblok-content.mdx): In Storyblok, add your target languages to the space and give each translatable field a value per language. General Translation's Storyblok integration fills those values from the Dashboard with Sync and apply, as drafts you review and publish in Storyblok. - [How do I review and edit translations?](https://generaltranslation.com/en-GB/kb/review-translations.mdx): Compare each translation with its source and the other locales, and fix anything that doesn't read right. With General Translation, you edit translations on the Dashboard's Translations page and track review with labels and comments, and the next translation run by Locadex, its AI agent, brings the edits into a pull request. ## Previous and next questions - Previous question: [How do I review and edit translations?](https://generaltranslation.com/en-GB/kb/review-translations.mdx) - Next question: [How do I translate a Node.js app?](https://generaltranslation.com/en-GB/kb/translate-node-app.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/en-GB/kb/sitemap.md) for every article.