MD & MDX

Use @better-translate/md when your docs, blog posts, or content pages live in localized .md or .mdx files.

This package does not replace the core translator. It reads the locale rules from the translator you already created.

1. Install the packages

npm install @better-translate/core @better-translate/md

2. Create the translator

Create src/i18n.ts:

1import { configureTranslations } from "@better-translate/core";23const en = {4  docs: {5    title: "Docs",6  },7} as const;89const es = {10  docs: {11    title: "Documentacion",12  },13} as const;1415export const translator = await configureTranslations({16  availableLocales: ["en", "es"] as const,17  defaultLocale: "en",18  fallbackLocale: "en",19  messages: { en, es },20});

3. Create the content folders

Put one folder per locale under the same root:

txt

1content/docs/2  en/3    getting-started.mdx4  es/5    getting-started.mdx

4. Create the markdown helpers

Create src/docs.ts:

1import { createMarkdownHelpers } from "@better-translate/md";23import { translator } from "./i18n";45export const docs = createMarkdownHelpers(translator, {6  rootDir: "./content/docs",7});

5. Read one document

1import { docs } from "./docs";23const englishDoc = await docs.getDocument("getting-started", {4  locale: "en",5});67const spanishDoc = await docs.getDocument("getting-started", {8  locale: "es",9});

6. Compile it when you need output

1const compiled = await docs.compileDocument("getting-started", {2  locale: "en",3});45compiled.kind; // "md" or "mdx"6compiled.path;7compiled.usedFallback;

When to use the server helpers

If your app already resolves the request locale on the server, use @better-translate/md/server so markdown loading follows the same request locale automatically.

Generate localized markdown automatically

Use the CLI's markdown.rootDir option to have the generator translate your markdown files: CLI guide

Examples

md-nextjs-example

2. Create the translator

Create src/i18n.ts:

1import { configureTranslations } from "@better-translate/core";23const en = {4  docs: {5    title: "Docs",6  },7} as const;89const es = {10  docs: {11    title: "Documentacion",12  },13} as const;1415export const translator = await configureTranslations({16  availableLocales: ["en", "es"] as const,17  defaultLocale: "en",18  fallbackLocale: "en",19  messages: { en, es },20});