Markdown is easy to translate until you have two hundred pages of it. Then the words are fine and the problem is everything around them: the code that must not change, the links that must still point somewhere, and the next release that adds ten more pages.
This guide is for docs sites, READMEs, changelogs and blog folders written in Markdown or MDX.
Which option should you use?
| Good for | Where it stops | |
|---|---|---|
| AI Glot | A docs folder, several languages, a glossary that must hold, every release | Not needed for one short README paragraph |
| A translation management platform (Crowdin, Lokalise, Phrase) | A team with a continuous workflow, reviewers and a repository connection | You set up a project and connect your repository before the first page moves |
| DeepL | Documents it lists: Word, PowerPoint, Excel, PDF, HTML, text and others | Markdown is not on that list, so you paste text or convert the file first |
| ChatGPT, Claude or another assistant | One short page | You paste each page in and carry your glossary into every chat. Each page needs a check for changed code or links, and a long docs folder uses up your usage limit |
| A freelancer or an agency | The landing page and the pricing page | Slow, priced per word, and you still prepare the files |
Have a person read the page that sells the product. Run the reference docs through an engine, because that is where the volume is.
Why AI Glot fits a docs folder
- Content in, structure out of the way. Headings, paragraphs, list items and table cells are text. Code, link targets, HTML blocks and table separators pass through as written.
- Emphasis follows the words. Bold, italics and link text move with the words they belong to.
- One glossary for the whole docs site. Your product names and API terms read the same on every page, and on the next release.
- A plan before any spend. It lists what it found and what it will translate.
- A folder in one job. Put the files in a ZIP and the layout is rebuilt.
The path of one file
- 1UploadA .md or .mdx file, or a ZIPUp to 4 MB each
- 2Say what you needOne plain sentenceFree
- 3Read the planWhat it found, languages, costFree
- 4ApproveThe only step that spendsSpends credits
- 5DownloadTranslated MarkdownDrop it in
What changes in a page
Only the prose changes. The code, the link and the front matter keys do not.
---title: Install the CLItitle: Installer la CLIslug: install---Run `npm install -g tool` and read the [guide](/docs/setup).Lancez `npm install -g tool` et lisez le [guide](/docs/setup).What to check in MDX
Imports, component tags and expressions are left alone. That keeps the page building. The catch is text you hand to a component as a prop, for example a title passed to a card. It belongs to the component, not to the prose, so look at those few strings after.
Heading anchors. If your site builds an anchor from the heading text, a translated heading gets a new anchor. Links that point at a heading, such as the Install section, need a look.
How to do it, step by step
1. Try a file for free. The Markdown translator needs no account and takes files up to 2 MB and 5,000 words.
2. Upload the file or a ZIP of the folder in the app.
3. Say what you need in one sentence.
Translate this folder into French.
Translate the prose and the front matter title and description.
Leave every other front matter field as it is.The sentence decides what is translated across the whole folder. A rule about wording, such as “keep product names and API terms in English”, goes into the second box at approval, because it is applied to each paragraph as it is written.
4. Add a glossary for product names, API terms and the words you always say one way. How to build one.
5. Read the plan and choose a quality level.
Lite gives about three times more words per credit and is faster: right for a bulk refresh of the reference docs. Standard is for the landing page. One credit is one word in Standard.
6. Approve and download.
One docs folder, several languages
The numbers are an example. A Markdown file holds one language, so each language is its own translated copy of the folder.
Three ways to run it
From the command line suits a docs repository, because the same four steps run in a script or in CI whenever the English changes:
id=$(aiglot batches create docs.zip \
--instruction "Translate into French. Translate the prose and the front matter title and description." \
--json | jq -r '.data.id')
aiglot batches get "$id" --json | jq '.data.plan'
aiglot batches approve "$id" --quality lite \
--instructions "Keep product names and API terms in English."
aiglot batches download "$id" --output docs_fr.zipWith your AI agent: connect AI Glot as an MCP server. The agent can read your repository, propose the glossary terms it finds, run the job and put the files back in place.
In the app: upload, click, download. Good for a single page.
For an API integration, see the API documentation.
Check the result
Build the docs site in one translated language and open three pages: one with code, one with a table and one with a link to another page. Run your usual link checker, because that is where an anchor change shows up. Keep the English files until someone who reads the language has looked at the pages that matter.
Pricing lists what a larger volume costs, and a free account comes with credits to run a real folder.
The limits quoted here are the ones in force when this was written: 4 MB per Markdown file, 200 files and 20 MB per ZIP, and 2 MB and 5,000 words in the free tool. DeepL’s list comes from its own documentation. File names and page counts in the diagrams are examples. Your plan shows the real figures for your own files, and it is free to read.