# General Translation Integrations: Configuration
URL: https://generaltranslation.com/en-GB/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** generates show-default-locale mode, where every language uses a locale-prefixed path. Existing projects may use hide-default-locale mode, where source pages keep their original paths. Both modes translate `docs.json` and every `.mdx`/`.md` page; they differ in how files are organised 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 localise `docs.json`.                             | `mintlify-hide-default`                                     | `mintlify`                                                                       |
| [`options.docsHideDefaultLocaleImport`](#options)   | Hides the default locale in imports.                             | `true`                                                      | *(omitted)*                                                                      |
| [`options.experimentalHideDefaultLocale`](#options) | Serves the default locale without a locale prefix.               | `true`                                                      | *(omitted)*                                                                      |
| [`options.experimentalClearLocaleDirs`](#options)   | Clears 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 localised 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 behaviour).

## Options [#options]

The `options` block configures Mintlify-specific behaviour. 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 localised 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 localise 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` — `/[locale]`. The pattern used when localising documentation URLs.
* `docsImportPattern` — `/snippets/[locale]`. The pattern used when localising snippet imports.
* `experimentalLocalizeStaticImports` — `true`. Localises static import paths (such as snippets).
* `experimentalLocalizeStaticUrls` — `{ "skipUntranslatedPages": true }`. Localises internal static URLs so links stay within the reader's language, but keeps a link on its source URL when the target page has no translation.
* `experimentalLocalizeRelativeAssets` — `true`. Localises relative asset references.
* `experimentalClearLocaleDirs` — `true`. Clears generated locale directories before writing translations so that 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 recognises 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.

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

This option requires `options.docsUrlPattern` to place the locale in each URL. `options.experimentalHideDefaultLocale` controls whether the source locale keeps an unprefixed path. If `docsUrlPattern` is missing, the CLI issues a warning and adds no redirects.

## Example [#example]

The following example shows an existing 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 those excluded paths.*

## Sitemap

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