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",
  "messagesDir": "./messages",
  "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:

• hardcoded - Untranslated text in JSX/TSX
• missing - Keys used but not defined in locale files
• orphan - Unused keys in locale files

npm

# Only hardcoded text
npx glot check hardcoded

# Only missing translation keys

npx glot check missing

# Only orphan (unused) keys

npx glot check orphan

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: Establish a Baseline

If your project already has many hardcoded strings, fixing them all at once isn’t practical. Use the baseline command to suppress existing warnings and start fresh.

Preview Changes (Dry Run)

First, see what comments would be inserted:

npm

npx glot baseline

Output:

Dry-run mode: showing comments that would be inserted

./src/components/Button.tsx:5
  Would add: // glot-disable-next-line
  Before: return <button>Submit</button>;

2 comments would be inserted. Run with --apply to insert.

Apply the Baseline

Insert the suppression comments:

npm

npx glot baseline --apply

This inserts // glot-disable-next-line comments above each hardcoded text:

export function Button() {
  // glot-disable-next-line
  return <button>Submit</button>;
}

Now you can:

1. Add glot to CI immediately - new hardcoded text will be caught
2. Gradually fix existing issues and remove the suppression comments over time

See Baseline Command for more options and details.

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 issues are found, making it perfect for CI pipelines:

npm .github/workflows/i18n.yml

name: i18n Check
on: [push, pull_request]

jobs:
check:
runs-on: ubuntu-latest
steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 - run: npm ci - run: npx glot check

Next Steps

Commands

Learn all available commands

Configuration

Customize glot for your project