> ## Documentation Index
> Fetch the complete documentation index at: https://glotctl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete .glotrc.json configuration reference

Glot is configured using a `.glotrc.json` file in your project root.

## Creating Configuration

Run the init command to create a default configuration:

<Tabs syncKey="pkg">
  <Tab title="npm">`bash npx glot init `</Tab>
  <Tab title="pnpm">`bash pnpm exec glot init `</Tab>
  <Tab title="yarn">`bash yarn glot init `</Tab>
  <Tab title="bun">`bash bunx glot init `</Tab>
</Tabs>

Or create `.glotrc.json` manually.

## Quick Reference

| Option                                  | Type       | Default                         | Description                              |
| --------------------------------------- | ---------- | ------------------------------- | ---------------------------------------- |
| [primaryLocale](#primarylocale)         | `string`   | `"en"`                          | Primary locale for missing key detection |
| [messagesRoot](#messagesroot)           | `string`   | `"./messages"`                  | Path to locale JSON files                |
| [sourceRoot](#sourceroot)               | `string`   | `"./"`                          | Source code root directory               |
| [includes](#includes)                   | `string[]` | [See below](#includes)          | Directories to scan for TSX/JSX          |
| [ignores](#ignores)                     | `string[]` | `[]`                            | Paths or glob patterns to exclude        |
| [ignoreTestFiles](#ignoretestfiles)     | `boolean`  | `true`                          | Skip test files automatically            |
| [ignoreTexts](#ignoretexts)             | `string[]` | `[]`                            | Text patterns to ignore                  |
| [checkedAttributes](#checkedattributes) | `string[]` | [See below](#checkedattributes) | JSX attributes to check                  |

## Configuration Details

<Accordion title="primaryLocale" defaultOpen>
  ### primaryLocale

  The primary locale for your application. Missing key detection uses this locale as the source of truth.

  | Type     | Default |
  | -------- | ------- |
  | `string` | `"en"`  |

  ```json theme={null}
  {
    "primaryLocale": "en"
  }
  ```
</Accordion>

<Accordion title="messagesRoot">
  ### messagesRoot

  Path to the directory containing your locale JSON files.

  | Type     | Default        |
  | -------- | -------------- |
  | `string` | `"./messages"` |

  ```json theme={null}
  {
    "messagesRoot": "./messages"
  }
  ```

  Expected structure:

  ```
  messages/
  ├── en.json
  ├── es.json
  ├── fr.json
  └── ...
  ```

  <Note>
    For backward compatibility, `messagesDir` is also accepted as an alias.
  </Note>
</Accordion>

<Accordion title="sourceRoot">
  ### sourceRoot

  The root directory for source code scanning. Paths in `includes` are relative to this directory.

  | Type     | Default |
  | -------- | ------- |
  | `string` | `"./"`  |

  ```json theme={null}
  {
    "sourceRoot": "./src"
  }
  ```

  This is useful when your source code is in a subdirectory or when working in a monorepo.
</Accordion>

<Accordion title="includes">
  ### includes

  Directories to scan for TSX/JSX files. Glot only checks files in these directories.

  | Type       | Default   |
  | ---------- | --------- |
  | `string[]` | See below |

  Default value:

  ```json theme={null}
  {
    "includes": [
      "src/app/[locale]",
      "src/components",
      "app/[locale]",
      "components"
    ]
  }
  ```

  Glot supports two types of include patterns:

  **Directory paths** (without `*` or `?`):

  Scans all files within the specified directory.

  ```json theme={null}
  {
    "includes": ["src/app/[locale]", "src/components"]
  }
  ```

  **Glob patterns** (with `*` or `?`):

  Uses glob matching to find directories to scan.

  ```json theme={null}
  {
    "includes": ["src/*", "packages/*/src"]
  }
  ```

  <Note>
    Paths can include Next.js dynamic route syntax like `[locale]`. This is
    treated as a literal folder name, not a glob pattern.
  </Note>
</Accordion>

<Accordion title="ignores">
  ### ignores

  Paths or glob patterns to exclude from scanning.

  | Type       | Default |
  | ---------- | ------- |
  | `string[]` | `[]`    |

  Glot supports two types of ignore patterns:

  **Directory paths** (without `*` or `?`):

  Excludes the entire directory and all files within it. This works the same way as `includes`.

  ```json theme={null}
  {
    "ignores": ["src/components/ai-elements", "src/generated"]
  }
  ```

  **Glob patterns** (with `*` or `?`):

  Uses glob matching for more flexible patterns.

  ```json theme={null}
  {
    "ignores": ["**/*.stories.tsx", "**/mocks/**"]
  }
  ```

  **Mixed usage:**

  You can combine both directory paths and glob patterns:

  ```json theme={null}
  {
    "ignores": [
      "src/components/ai-elements",
      "src/generated",
      "**/*.stories.tsx",
      "**/node_modules/**"
    ]
  }
  ```

  <Note>
    Directory paths like `src/components/ai-elements` will exclude all files under
    that directory. Paths can include Next.js dynamic route syntax like
    `app/[locale]/admin` - the `[locale]` is treated as a literal folder name.
  </Note>
</Accordion>

<Accordion title="ignoreTestFiles">
  ### ignoreTestFiles

  Skip test files automatically.

  | Type      | Default |
  | --------- | ------- |
  | `boolean` | `true`  |

  When enabled, glot ignores:

  * `*.test.tsx`, `*.test.ts`, `*.test.jsx`, `*.test.js`
  * `*.spec.tsx`, `*.spec.ts`, `*.spec.jsx`, `*.spec.js`
  * Files in `__tests__/` directories

  ```json theme={null}
  {
    "ignoreTestFiles": true
  }
  ```
</Accordion>

<Accordion title="ignoreTexts">
  ### ignoreTexts

  Specific text patterns to ignore. Case-sensitive.

  | Type       | Default |
  | ---------- | ------- |
  | `string[]` | `[]`    |

  ```json theme={null}
  {
    "ignoreTexts": ["TODO", "FIXME", "Lorem ipsum"]
  }
  ```

  Useful for:

  * Development placeholders
  * Known patterns that don't need translation
  * Third-party component text
</Accordion>

<Accordion title="checkedAttributes">
  ### checkedAttributes

  JSX attributes to check for [hardcoded text](/detection/hardcoded-text). These attributes commonly contain user-facing strings that should be translated.

  | Type       | Default   |
  | ---------- | --------- |
  | `string[]` | See below |

  Default value:

  ```json theme={null}
  {
    "checkedAttributes": [
      "placeholder",
      "title",
      "alt",
      "aria-label",
      "aria-description",
      "aria-placeholder",
      "aria-roledescription",
      "aria-valuetext"
    ]
  }
  ```

  <Warning>
    Setting this option **overrides** the defaults. Include all attributes you
    want checked.
  </Warning>
</Accordion>

## Full Example

A complete configuration file:

```json .glotrc.json theme={null}
{
  "primaryLocale": "en",
  "messagesRoot": "./locales",
  "sourceRoot": "./",
  "includes": ["src/app/[locale]", "src/components", "src/features"],
  "ignores": ["**/node_modules/**", "**/*.stories.tsx", "**/mocks/**"],
  "ignoreTestFiles": true,
  "ignoreTexts": ["TODO", "FIXME", "N/A"],
  "checkedAttributes": ["placeholder", "title", "alt", "aria-label"]
}
```

## Configuration Resolution

Glot searches for `.glotrc.json` starting from the specified path (or current directory) and traversing upward:

1. Check current directory for `.glotrc.json`
2. If not found, check parent directory
3. Continue until:
   * A `.glotrc.json` is found
   * A `.git` directory is encountered (project root)
   * Filesystem root is reached

If no configuration is found, glot uses all default values.

## Validation

Glot validates your configuration on startup:

* Paths in `includes` are checked for existence
* Glob patterns in `ignores` are validated
* Invalid configuration shows clear error messages

```
Error: Invalid configuration in .glotrc.json
  - includes[0]: Directory "src/pages" does not exist
  - ignores[2]: Invalid glob pattern "***"
```

## Common Configurations

<Accordion title="Next.js App Router">
  ```json theme={null}
  {
    "primaryLocale": "en",
    "messagesRoot": "./messages",
    "includes": [
      "src/app/[locale]",
      "src/components"
    ]
  }
  ```
</Accordion>

<Accordion title="Next.js Pages Router">
  ```json theme={null}
  {
    "primaryLocale": "en",
    "messagesRoot": "./locales",
    "includes": [
      "src/pages",
      "src/components"
    ]
  }
  ```
</Accordion>

<Accordion title="Monorepo with Multiple Apps">
  ```json theme={null}
  {
    "primaryLocale": "en",
    "messagesRoot": "./packages/i18n/messages",
    "includes": [
      "apps/web/src/app/[locale]",
      "apps/web/src/components",
      "packages/ui/src"
    ]
  }
  ```
</Accordion>

## Related

<CardGroup cols={2}>
  <Card title="Init Command" icon="terminal" href="/commands/init">
    Create configuration file
  </Card>

  <Card title="Directives" icon="code" href="/directives">
    Inline suppression directives
  </Card>
</CardGroup>