Translate Markdown and MDX documents

A document is not a list of keys. Its text is scattered through code blocks, links and front matter that must come back exactly. KAERIS splits the file into protected pieces and prose, translates only the prose, and puts the pieces back.

Translate your file Check your files free

How a Markdown document is read

The document is cut into a skeleton of literal pieces and numbered text segments. Inside a segment, inline code, link targets, HTML and JSX tags are swapped for tokens like {0} before translation and restored after. A model that drops one trips the same detector as a dropped variable.

Source filegetting-started.md

---
title: Getting started
slug: getting-started
---

# Getting started

Install the package with `pip install kaeris`, then read the [CLI guide](/docs/cli).

```bash
kaeris translate en.json --langs de,ja
```

Run it once per release. It only translates new keys.

What to watch for in Markdown translations

Code is not prose
A translated code block still renders, and then fails for the reader who copies it. Fenced and indented code, inline code and MDX import/export lines are never translated.
Links
Link text is translated; the link target is not. A translated URL still looks like a link and then returns 404.
Front matter
Settings such as slug, date, layout and tags come back unchanged. Fields a reader sees, such as title and summary, are translated.
A known limit
Text inside a multi-line JSX component is preserved whole, not translated. The reader of this page is told so here rather than after a build.

A real run, before and after

A real run: our test document, German, 26 October 2026, cut to the start and one code block. The heading, bold text, the curl command and the token $TOKEN are as in the source; only the prose and the front-matter fields a reader sees changed.

Beforehelp-returns.md

---
title: Returns and refunds
summary: How to return a record, and when you will not get a refund.
---

# Returns and refunds

You can return an unopened record within **30 days** of delivery. We refund the full price, but not the shipping cost.

…
```bash
curl https://api.example.com/v1/returns/RT-1042 -H "Authorization: Bearer $TOKEN"
```

Afterde/help-returns.md

---
title: Rücksendungen und Erstattungen
summary: So senden Sie eine Schallplatte zurück und wann Sie keine Erstattung erhalten.
---

# Rücksendungen und Erstattungen

Sie können eine ungeöffnete Schallplatte innerhalb von **30 Tagen** nach Lieferung zurücksenden. Wir erstatten den vollen Preis, jedoch nicht die Versandkosten.

…
```bash
curl https://api.example.com/v1/returns/RT-1042 -H "Authorization: Bearer $TOKEN"
```

What KAERIS does with it

Skeleton and prose kept apart
Headings, tables, lists and fences keep their shape; only the prose inside is swapped.
One output per language
guide.md becomes de.md, ja.md and so on.
Each line translated back
--verify translates the result back and writes verify.json so you can read what each part now says.

Translate your file Check your files free

Run it in three steps

Install the CLI
Run pip install kaeris.
Translate the document
Run kaeris translate docs/guide.md --langs de,ja. A glob such as docs/*.md translates several files.
Read it back
Open verify.json from the --verify run to see what each translated part now says in your language.

pip install kaeris
kaeris translate docs/guide.md --langs de,ja --verify

Questions

Is code in my docs translated?

No. Fenced and indented code blocks, inline code, URLs, HTML and JSX tags come back byte for byte.

Does it translate MDX components?

Prose and the single-line parts around them, yes. Text inside a multi-line JSX component is preserved rather than translated, which is a limit of the format reader.

Is it free?

Yes, without an account: 10,000 characters per file and up to 8 languages per run. A free API key raises the file limit to 50,000 characters. Lifetime is $79 once, on your own OpenRouter key; monthly plans start at $19. Pricing

Can I run it from the terminal or in CI?

Yes. pip install kaeris, then kaeris translate docs/guide.md --langs de,ja. The GitHub Action runs the same translation in a pull request. CLI docs · GitHub Action

Keep going

CLI reference · Check reference · Translate in the browser · Free check · Convert formats · Pseudo-localization

Other formats: JSON · YAML · .po · ARB · XLIFF · .strings · .xcstrings · .properties · .resx · CSV · Fluent · Android XML