Quick Start

Get started with glot in 2 minutes

Get up and running with glot in just a few steps.

Installation

Glot is distributed as an npm package called glotctl. The CLI command is glot.

npm

npm install -D glotctl

Verify the installation:

npm

npx glot --version

Initialize Configuration

Create a .glotrc.json configuration file:

npm

npx glot init

This creates a default configuration:

{
  "primaryLocale": "en",
  "messagesRoot": "./messages",
  "sourceRoot": "./",
  "includes": [
    "src/app/[locale]",
    "src/components",
    "app/[locale]",
    "components"
  ],
  "ignores": [],
  "ignoreTestFiles": true,
  "ignoreTexts": [],
  "checkedAttributes": [
    "placeholder",
    "title",
    "alt",
    "aria-label",
    "aria-description",
    "aria-placeholder",
    "aria-roledescription",
    "aria-valuetext"
  ]
}

Adjust the includes paths to match your project structure. Glot will only scan these directories.

Run Your First Check

Check your project for all i18n issues:

npm

npx glot check

Or check for specific issue types:

Type	Description
hardcoded	Untranslated text in JSX/TSX
missing	Keys used but not defined in locale files
unused	Keys in primary locale not used in code
orphan	Keys in non-primary locales but not in primary
replica-lag	Keys in primary locale missing from other locales
untranslated	Values identical to primary locale
type-mismatch	Type conflicts between locales
unresolved	Dynamic keys that cannot be analyzed

npm

# Only hardcoded text
npx glot check hardcoded

# Only missing translation keys
npx glot check missing

# Multiple specific checks
npx glot check hardcoded missing unused

Understanding the Output

Glot displays issues in a familiar format:

error: "Submit"  hardcoded-text
  --> ./src/components/Button.tsx:5:22
  |
5 |     return <button>Submit</button>;
  |                    ^

error: "Enter your email"  hardcoded-text
  --> ./src/components/Form.tsx:12:28
   |
12 |     <input placeholder="Enter your email" />
   |                        ^

✘ 2 problems (2 errors, 0 warnings)

Each issue shows:

• The problematic text in quotes
• The issue type (e.g., hardcoded-text)
• File path and location
• Source code context with a pointer

Existing Projects

If your project already has many hardcoded strings, use the baseline command to suppress existing warnings and start fresh:

npx glot baseline --apply

This inserts // glot-disable-next-line comments above each hardcoded text, so you can add glot to CI immediately and gradually fix existing issues over time.

If your project uses dynamic translation keys like t(`items.${type}`), use glot fix to auto-insert glot-message-keys declarations.

Fixing Issues

Replace hardcoded text with translation function calls:

Before

export function Button() {
  return <button>Submit</button>;
}

Then add the key to your locale file:

messages/en.json

{
  "common": {
    "submit": "Submit"
  }
}

Add to package.json

For convenience, add glot commands to your package.json:

{
  "scripts": {
    "i18n:check": "glot check",
    "i18n:clean": "glot clean --apply"
  }
}

Using with CI

Glot returns exit code 1 when errors are found. Warnings return exit 0 by default, or exit 1 when you pass --error-on-warnings, making glot ideal for CI pipelines. Add a step to your workflow:

npx glot check

See Check Command — Severity for which check types are errors vs warnings, and Check Command — CI Examples for full GitHub Actions examples.

Next Steps

Commands

Learn all available commands

Configuration

Customize glot for your project