# 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.

## Overview [#overview]

| Topic | Description |
| --- | --- |
| [Configuration](#config) | Select source files and translated output paths. |
| [Static data exports](#data-exports) | Reuse unchanged strings in eligible exports. |
| [Translated file names](#transform) | Remap output file names with `transform`. |
| [Links and assets](#localize) | Localize URLs, imports, and relative assets. |

## 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 when every exported variable in the chunk contains only static string, number, bigint, boolean, or `null` literals, arrays, and plain objects. TypeScript assertion wrappers are supported.

Exports with spreads, identifiers, function calls, template literals, JSX, or computed object keys use the standard translation path. Running [`gt translate --force`](/docs/cli/reference/commands/translate) or applying Glossary translations also skips 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.