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:

npmbash npx glot init

pnpmbash pnpm exec glot init

yarnbash yarn glot init

bunbash bunx glot init

Or create .glotrc.json manually.

Quick Reference

Option	Type	Default	Description
primaryLocale	string	"en"	Primary locale for missing key detection
messagesRoot	string	"./messages"	Path to locale JSON files
sourceRoot	string	"./"	Source code root directory
includes	string[]	See below	Directories to scan for source files
ignores	string[]	[]	Paths or glob patterns to exclude
ignoreTestFiles	boolean	true	Skip test files automatically
ignoreTexts	string[]	[]	Text patterns to ignore
checkedAttributes	string[]	See below	JSX attributes to check
severities	object	{}	Per-rule severity overrides
extraTranslationCallees	string[]	[]	Additional bare call names to treat as translation usage
extraTranslationMemberCalls	object[]	[]	Additional constrained member-call patterns to treat as translation usage

Configuration Details

primaryLocale

primaryLocale

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

Type	Default
string	"en"

{
  "primaryLocale": "en"
}

messagesRoot

messagesRoot

Path to the directory containing your locale JSON files.

Type	Default
string	"./messages"

{
  "messagesRoot": "./messages"
}

Expected structure:

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

For backward compatibility, messagesDir is also accepted as an alias.

sourceRoot

sourceRoot

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

Type	Default
string	"./"

{
  "sourceRoot": "./src"
}

This is useful when your source code is in a subdirectory or when working in a monorepo.

includes

includes

Directories to scan for source files. Glot only checks .tsx, .jsx, .ts, .js, and supported .astro files in these directories.

Type	Default
string[]	See below

Default value:

{
  "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.

{
  "includes": ["src/app/[locale]", "src/components"]
}

Glob patterns (with * or ?):

Uses glob matching to find directories to scan.

{
  "includes": ["src/*", "packages/*/src"]
}

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

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.

{
  "ignores": ["src/components/ai-elements", "src/generated"]
}

Glob patterns (with * or ?):

Uses glob matching for more flexible patterns.

{
  "ignores": ["**/*.stories.tsx", "**/mocks/**"]
}

Mixed usage:

You can combine both directory paths and glob patterns:

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

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.

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

{
  "ignoreTestFiles": true
}

ignoreTexts

ignoreTexts

Specific text patterns to ignore. Case-sensitive.

Type	Default
string[]	[]

{
  "ignoreTexts": ["TODO", "FIXME", "Lorem ipsum"]
}

Useful for:

• Development placeholders
• Known patterns that don’t need translation
• Third-party component text

checkedAttributes

checkedAttributes

JSX attributes to check for hardcoded text. These attributes commonly contain user-facing strings that should be translated.

Type	Default
string[]	See below

Default value:

{
  "checkedAttributes": [
    "placeholder",
    "title",
    "alt",
    "aria-label",
    "aria-description",
    "aria-placeholder",
    "aria-roledescription",
    "aria-valuetext"
  ]
}

Setting this option overrides the defaults. Include all attributes you want checked.

severities

severities

Override the effective severity for specific rules.

Type	Default
object	{}

{
  "severities": {
    "untranslated": "warning",
    "unused": "error"
  }
}

Supported severity values are "error" and "warning".

Supported rule keys:

• hardcoded
• missing or missing-key
• replica-lag
• untranslated
• type-mismatch
• unused or unused-key
• orphan or orphan-key
• unresolved or unresolved-key

untranslated is an error by default when the key is used in source, and a warning when no source usage is found. If your project intentionally keeps some used values identical across locales, prefer targeted glot-disable-next-line untranslated comments. Use severities when you want a project-wide policy change.

parse-error cannot be configured. Parse errors always return exit code 2.

extraTranslationCallees

extraTranslationCallees

Additional bare callee names to treat as translation usage.

Type	Default
string[]	[]

{
  "extraTranslationCallees": ["tt", "$t"]
}

Use this for project-specific wrappers when the call itself is the translation API. Entries are matched by callee name, so keep the list narrow.

extraTranslationMemberCalls

extraTranslationMemberCalls

Additional constrained member-call patterns to treat as translation usage.

Type	Default
object[]	[]

Each entry supports these fields:

• property (required): member name such as translate
• objectName (optional): local object name such as intl
• importFrom (optional): restrict to a specific import source
• importName (optional): restrict to a specific imported binding such as default, *, or a named export

At least one of objectName or importFrom is required.

{
  "extraTranslationMemberCalls": [
    {
      "objectName": "intl",
      "property": "translate",
      "importFrom": "./intl",
      "importName": "default"
    }
  ]
}

This option is intentionally constrained. It is for known project APIs, not for treating every .t(...) call as a translation usage.

Full Example

A complete configuration file:

.glotrc.json

{
  "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"],
  "severities": {
    "unused": "error"
  },
  "extraTranslationCallees": ["tt"],
  "extraTranslationMemberCalls": [
    {
      "objectName": "intl",
      "property": "translate",
      "importFrom": "./intl",
      "importName": "default"
    }
  ]
}

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

Next.js App Router

{
  "primaryLocale": "en",
  "messagesRoot": "./messages",
  "includes": [
    "src/app/[locale]",
    "src/components"
  ]
}

Next.js Pages Router

{
  "primaryLocale": "en",
  "messagesRoot": "./locales",
  "includes": [
    "src/pages",
    "src/components"
  ]
}

Monorepo with Multiple Apps

{
  "primaryLocale": "en",
  "messagesRoot": "./packages/i18n/messages",
  "includes": [
    "apps/web/src/app/[locale]",
    "apps/web/src/components",
    "packages/ui/src"
  ]
}

Related

Init Command

Create configuration file

Directives

Inline suppression directives