# General Translation Integrations: Configuration
URL: https://generaltranslation.com/en-US/docs/integrations/mintlify/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Review the gt.config.json generated for a Mintlify project. Reference for the Mintlify integration configuration.

General Translation generates a `gt.config.json` for your Mintlify project during setup — you do not write it by hand. This page documents what that file contains so you can review or fine-tune it after the setup pull request lands.

The configuration is a standard General Translation CLI config. Each shared key is documented once in the [CLI configuration reference](/docs/cli/reference/config); this page covers only the Mintlify-specific choices and the two modes the integration generates.

## Modes [#modes]

Setup started from **Project > Automations** defaults to hide-default-locale mode, where source pages keep their original paths. Turning off **Hide default locale in URL paths** during setup generates show-default-locale mode, where every language uses a locale-prefixed path. Both modes translate `docs.json` and every `.mdx`/`.md` page; they differ in how files are laid out and how the source locale is served.

| Key | Description | Hide default locale | Show default locale |
| --- | --- | --- | --- |
| [`files.mdx.include`](#files) | Glob patterns for the pages to translate. | `./**/*.mdx`, `./**/*.md` (translated in place) | `./[locale]/**/*.mdx`, `./snippets/[locale]/**/*.mdx`, and the `.md` equivalents |
| [`files.mdx.transform`](#files) | Rewrites source paths into locale folders. | `{ match: "^(snippets/)?(.*)$", replace: "$1{locale}/$2" }` | *(none)* |
| [`options.jsonSchema`](#options) | Preset used to localize `docs.json`. | `mintlify-hide-default` | `mintlify` |
| [`options.docsHideDefaultLocaleImport`](#options) | Hide the default locale in imports. | `true` | *(omitted)* |
| [`options.experimentalHideDefaultLocale`](#options) | Serve the default locale without a locale prefix. | `true` | *(omitted)* |
| [`options.experimentalClearLocaleDirs`](#options) | Clear generated locale directories before writing translations. | `true` | `true` |

## Files [#files]

The `files` block tells the General Translation CLI what to translate. For a Mintlify project it always includes `docs.json` and the docs pages.

- `files.json.include` — always `['./docs.json']`. The `docs.json` navigation and labels are localized with the preset in `options.jsonSchema`.
- `files.mdx.include` — the `.mdx` and `.md` pages to translate. In hide-default-locale mode this is the whole tree (`./**/*.mdx`, `./**/*.md`) and files are moved into locale folders by the transform; in show-default-locale mode it targets existing per-locale folders.
- `files.mdx.transform` — in hide-default-locale mode, rewrites each source path into a `{locale}/` folder (keeping a leading `snippets/` prefix in place). Show-default-locale mode omits the transform because content already lives in locale folders.
- `files.mdx.exclude` — the locale folders themselves plus common repository files that should never be translated (see [Supported content](/docs/integrations/mintlify/reference/supported-content#excluded)).

When the repository contains OpenAPI 3.x specifications in JSON or YAML, Locadex adds each source specification to `files.json` or `files.yaml`. It also adds a transform that writes the translated specification to the matching locale directory.

(See the [CLI configuration reference](/docs/cli/reference/config) for the full semantics of `files`, `include`, `exclude`, and `transform`, and the [MDX and Markdown format page](/docs/cli/reference/formats/mdx-md-files) and [JSON format page](/docs/cli/reference/formats/json-files) for per-format behavior).

## Options [#options]

The `options` block configures Mintlify-specific behavior. These keys are set for every Mintlify project unless noted as mode-specific or conditional.

- `mintlify.inferTitleFromFilename` — `true`. Derives a page title from its filename when a page has no explicit title.
- [`mintlify.localizeRedirects`](#localized-redirects) — optional and `false` by default. Setup-generated configs omit it. When enabled, adds localized copies of redirects for source pages renamed or removed during the current [`gt translate`](/docs/cli/reference/commands/translate) run.
- `mintlify.openapi.files` — paths to detected OpenAPI 3.x specifications *(when present)*. Registers the translated specifications with Mintlify.
- `jsonSchema` — maps `./docs.json` to a preset that knows how to localize Mintlify navigation: `mintlify-hide-default` when the default locale is hidden, otherwise `mintlify`. Detected JSON OpenAPI specifications use the `openapi` preset.
- `yamlSchema` — maps detected YAML OpenAPI specifications to the `openapi` preset *(when present)*.
- [`docsUrlPattern`](/docs/cli/reference/config#docs-url-pattern) — `/[locale]` in generated configs. The pattern used when localizing documentation URLs. It also accepts an array for sites that serve docs from several URL prefixes.
- `docsImportPattern` — `/snippets/[locale]`. The pattern used when localizing snippet imports.
- `experimentalLocalizeStaticImports` — `true`. Localizes static import paths (such as snippets).
- `experimentalLocalizeStaticUrls` — `{ "skipUntranslatedPages": true }`. Localizes internal static URLs so links and navigation entries stay within the reader's language, but keeps them on the source URL when the target page has no translation. An empty navigation root, or one ending in `/`, refers to that folder's `index.md` or `index.mdx`.
- `experimentalLocalizeRelativeAssets` — `true`. Localizes relative asset references.
- `experimentalClearLocaleDirs` — `true`. Clears generated locale directories before writing translations so removed source pages do not leave stale translated pages behind.
- `experimentalAddHeaderAnchorIds` — `'mintlify'`. Writes Mintlify-native `{#id}` syntax on every translated heading, using the source heading's ID so in-page links keep the same target across languages. Headings nested deeply in JSX are moved to the margin because Mintlify only recognizes this syntax with up to three leading spaces.
- `docsHideDefaultLocaleImport` — `true` *(hide-default-locale mode only)*. Hides the default locale in generated imports.
- `experimentalHideDefaultLocale` — `true` *(hide-default-locale mode only)*. Serves the default locale without a locale prefix.

### Localized redirects

**Type** `boolean` · **Optional** · **Default** `false`

Set `options.mintlify.localizeRedirects` to `true` to add per-locale copies of source-locale redirect entries whose source page was renamed or removed during the same [`gt translate`](/docs/cli/reference/commands/translate) run. The CLI leaves the original redirect unchanged, preserves its anchor and `permanent` value, and skips a locale when the destination page has no translation. It also skips redirects whose source or destination is already locale-prefixed, so locale segments are not added twice.

This option requires [`options.docsUrlPattern`](/docs/cli/reference/config#docs-url-pattern) to place the locale in each URL. For multiple docs roots, pass an array such as `["/docs/[locale]", "/ai/docs/[locale]"]`; each redirect uses the longest matching prefix. `options.experimentalHideDefaultLocale` controls whether the source locale keeps an unprefixed path. If `docsUrlPattern` is missing, the CLI warns and adds no redirects.

### Version history

| Version | Changes |
| --- | --- |
| `2.26.3` | Added arrays of URL patterns and longest-prefix matching. |
| `2.26.2` | Stopped adding a second locale segment to redirects that are already localized. |

## Example [#example]

The following example shows a project configured to hide the source locale (English source, Spanish and French targets):

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "files": {
    "json": {
      "include": ["./docs.json"]
    },
    "mdx": {
      "include": ["./**/*.mdx", "./**/*.md"],
      "transform": {
        "match": "^(snippets/)?(.*)$",
        "replace": "$1{locale}/$2"
      },
      "exclude": [
        "./[locales]/**/*.mdx",
        "./snippets/[locales]/**/*.mdx",
        "./[locales]/**/*.md",
        "./snippets/[locales]/**/*.md"
      ]
    }
  },
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "options": {
    "mintlify": {
      "inferTitleFromFilename": true,
      "localizeRedirects": true
    },
    "jsonSchema": { "./docs.json": { "preset": "mintlify-hide-default" } },
    "docsUrlPattern": "/[locale]",
    "docsImportPattern": "/snippets/[locale]",
    "experimentalLocalizeStaticImports": true,
    "experimentalLocalizeStaticUrls": {
      "skipUntranslatedPages": true
    },
    "experimentalLocalizeRelativeAssets": true,
    "experimentalClearLocaleDirs": true,
    "docsHideDefaultLocaleImport": true,
    "experimentalHideDefaultLocale": true,
    "experimentalAddHeaderAnchorIds": "mintlify"
  }
}
```

*Note: after setup, the CLI resolves the `[locales]` exclude placeholder to your actual target locales. Review the generated `gt.config.json` and adjust the excluded files if your repository keeps translatable content in one of the excluded paths.*

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.