@typeglot/cli

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

Installation

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.)

Files Explained

| 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 |

What Gets Bundled

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.

Recommended .gitignore

Add the generated output directory to your .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

Initialize a new project

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

Development mode with live compilation

typeglot dev

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

Build translations

typeglot build

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

Translate missing keys with AI

typeglot translate

Uses AI to translate missing keys to target locales.

Generated Code Example

Given this locales/en.json:

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

TypeGlot generates:

// 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:

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