# gt: General Translation CLI tool: MDX and Markdown
URL: https://generaltranslation.com/en-US/docs/cli/reference/formats/mdx-md-files.mdx
---

title: MDX and Markdown
description: Translate MDX and Markdown files with the General Translation CLI. API reference for the MDX and Markdown file formats.

---

The CLI translates MDX (`mdx`) and Markdown (`md`) files. All syntax and formatting in the source files is preserved in the translated files.

## Configuration [#config]

Add an `mdx` or `md` entry under `files` with an `include` array of glob patterns. Use the `[locale]` placeholder so the CLI can find source files and save translations to the right path.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}
```

This translates every MDX file under `content/docs/en` and saves the results to `content/docs/ja`. Use the `md` key instead for Markdown files. See the [configuration reference](/docs/cli/reference/config#files) for all file keys.

## Update static data exports [#data-exports]

When an updated MDX file contains static data exports, General Translation reuses matching strings from earlier translations and translates only new or changed strings. Reuse applies to exported variables whose values contain only literals, arrays, and plain objects. Exports with spreads, identifiers, function calls, template literals, or JSX use the standard translation path.

Force retranslation and Glossary retranslation skip this incremental reuse.

## Rename translated files [#transform]

The `transform` key remaps output file names. In the example above, `*.[locale].mdx` changes the translated extension to `.ja.mdx`. Use this when your docs framework expects a locale in the file name rather than in the directory path.

## Localize links and assets [#localize]

Several experimental [`gt translate`](/docs/cli/reference/commands/translate#experimental) flags apply specifically to `md` and `mdx` output:

- `--experimental-localize-static-urls` — localizes URLs in translated files.
- `--experimental-localize-static-imports` — localizes static imports in translated files.
- `--experimental-localize-relative-assets` — rewrites relative image asset URLs in translated files.
- `--experimental-hide-default-locale` — hides the default locale from localized paths.