@typeglot/cli

TypeGlot CLI - command-line interface for type-safe internationalization.

Installation

``bash
npm install -D @typeglot/cli


or use with npx (no installation required)


npx @typeglot/cli init
`

> Note: TypeGlot is a dev dependency only. The generated code has zero runtime dependencies — nothing from @typeglot/* is bundled into your production app.

What typeglot init Creates

Running typeglot init creates the following files:

`
your-project/
├── typeglot.config.json # Configuration file
├── locales/ # Translation source files
│ └── en.json # Source locale (committed to git)
└── src/generated/i18n/ # Generated TypeScript (gitignored)
├── index.ts # Main exports + locale types
├── messages.ts # Typed translation functions
├── en.ts # English messages as const
└── es.ts # Spanish messages as const (etc.)
`

$3

| File | Commit to Git? | Bundled in Production? | Description |
| ---------------------- | ----------------- | ---------------------- | ------------------------------ |
| typeglot.config.json | ✅ Yes | ❌ No | Configuration for the compiler |
| locales/*.json | ✅ Yes | ❌ No | Source translation files |
| src/generated/i18n/* | ❌ No (gitignore) | ✅ Yes | Generated TypeScript code |

$3

Only the generated TypeScript files are bundled in your production app. The generated code is:

- Self-contained — No imports from @typeglot/* packages
- Zero runtime dependencies — Pure TypeScript with no external libraries
- Tree-shakeable — Unused translations can be removed by bundlers

The JSON files are not bundled — they're compiled into TypeScript at build time.

$3

Add the generated output directory to your .gitignore:

`gitignore


TypeGlot generated files (regenerated on build)


src/generated/i18n/
`

The generated files should be regenerated by running typeglot build in your CI/CD pipeline or build process.

Usage

$3

`bash
typeglot init
`

The init command is smart and will:

- Detect existing locale files in common locations (locales/, src/locales/, src/i18n/, etc.)
- Detect monorepos (pnpm workspaces, npm/yarn workspaces) and let you choose which packages to initialize
- Ask which locale is your source if multiple locales are found

#### Monorepo Support

In a monorepo, you'll be prompted to choose:

`
🌐 Initializing TypeGlot...

📦 Detected monorepo with packages:

? Where would you like to initialize TypeGlot?
❯ Root (shared translations)
Specific packages

? Select packages to initialize:
◯ @myapp/frontend
◯ @myapp/backend
`

#### Existing Projects

If you already have translation files:

`
📂 Found existing locale files in src/locales/
Locales: en, es, de

? Use existing locales directory (src/locales/)? Yes
? Which locale is your source (primary) locale? en
`

$3

`bash
typeglot dev
`

Watches for changes and recompiles automatically. Also starts a local dashboard at http://localhost:3333.

$3

`bash
typeglot build
`

Compiles all JSON translation files to TypeScript. Run this in CI/CD before your main build.

$3

`bash
typeglot translate
`

Uses AI to translate missing keys to target locales.

Generated Code Example

Given this locales/en.json:

`json
{
"hello": "Hello",
"welcome": "Welcome, {name}!"
}
`

TypeGlot generates:

`typescript
// src/generated/i18n/messages.ts (auto-generated)
export function hello(): string {
return messages['hello'] ?? Hello;
}

export function welcome(params: { name: string }): string {
const template = messages['welcome'] ?? Welcome, {name}!;
return formatMessage(template, params);
}

export const m = { hello, welcome } as const;
`

Use in your code:

`typescript
import { m } from './generated/i18n';

m.hello(); // "Hello"
m.welcome({ name: 'Alice' }); // "Welcome, Alice!"
``

Features

- 🚀 Fast TypeScript compilation of translation files
- 🔄 Live reload in development mode
- 🤖 AI-powered translation with GitHub Copilot
- 📊 Translation dashboard UI
- ✅ Full type safety with autocomplete
- 📦 Monorepo support with interactive package selection
- 🔍 Auto-detection of existing locale files
- 🪶 Zero runtime dependencies in production

Documentation

For complete documentation, visit typeglot.ahlstrand.es

License

MIT