CLI Tools

Command-line utilities for managing, validating, and auto-translating your i18n files.

Installation

Add the CLI as a dev dependency to use the short npx ats command — just like npx ng with Angular CLI.

npm install -D @angular-translation-service/cli

Then run any command with npx ats <command>, pnpx ats <command>, or bunx ats <command>. Install globally with npm install -g to use the bare ats command everywhere.

`ats generate`

Generates TypeScript interfaces from your JSON translation files, providing compile-time type safety for translation keys.

npx @angular-translation-service/cli generate \
  -i src/i18n/en \
  -o src/app/i18n.generated.ts

Option	Default	Description
`-i, --input <dir>`	`src/assets/i18n/en`	Source directory containing JSON namespace files
`-o, --output <file>`	`src/app/i18n.generated.ts`	Output TypeScript file path
`--check`	—	CI mode: exits with code 1 if types are out of sync

Generated Output

// Auto-generated by angular-translation-service CLI
export const I18N_NAMESPACES = ['common', 'settings'] as const;

export interface I18nTypes {
  common: {
    title: string;
    nav: {
      home: string;
      about: string;
    };
  };
}

export type TranslationKey =
  | 'common:title'
  | 'common:nav.home'
  | 'common:nav.about';

`ats check`

Scans your source code (.ts and .html files) for translation key usage and cross-references with JSON files to detect missing and unused keys.

npx @angular-translation-service/cli check \
  --i18n src/i18n/en \
  --src src

Option	Default	Description
`--i18n <dir>`	`src/i18n/en`	JSON namespace directory (default language)
`--src <dir>`	`src`	Source directory to scan for key usage
`--namespace <ns>`	—	Limit checking to a specific namespace

Detected Patterns

translate('ns:key') — signal-based translation calls
instant('ns:key') — synchronous translation calls
select('ns') — marks entire namespace as used
'ns:key' | translate — Angular pipe usage in templates

`ats validate`

Compares translation files across all languages to find structural inconsistencies: missing keys, extra keys, and empty values.

npx @angular-translation-service/cli validate -i src/i18n

Option	Default	Description
`-i, --input <dir>`	`src/assets/i18n`	Root i18n directory containing language subdirectories

Example Output

🔍 Validating translations...
   Reference: en
   Targets:   pt-BR, es

📦 pt-BR/settings.json
   ❌ Missing: 2 keys
      - notifications.email
      - notifications.push
   📭 Empty: 1 values
      - theme.label

✅ All translations are structurally valid across 3 languages.

`ats clean`

Removes orphaned keys from target language files — keys that exist in a translation but no longer exist in the default language.

# Preview what would be removed
npx @angular-translation-service/cli clean -i src/i18n --dry-run

# Actually remove the orphans
npx @angular-translation-service/cli clean -i src/i18n

Option	Default	Description
`-i, --input <dir>`	`src/assets/i18n`	Root i18n directory
`--dry-run`	—	Show what would be removed without modifying files

`ats translate`

Uses a local LLM (via Ollama) to automatically translate missing keys from the default language to a target language. Supports batch translation with per-key fallback.

npx @angular-translation-service/cli translate \
  --locale pt-BR \
  --model gemma3:12b

Option	Default	Description
`--locale <locale>`	`pt-BR`	Target language code
`--namespace <ns>`	—	Limit to a specific namespace
`--model <model>`	`gemma3:12b`	Ollama model to use
`--host <host>`	`127.0.0.1:11434`	Ollama server address
`--auto-accept`	—	Skip interactive confirmation, accept all translations

Features

Batch translation (35 entries per LLM call for optimal context)
Automatic per-key fallback when batch parsing fails
Preserves interpolation placeholders ({{name}}, {count})
Handles code-fenced JSON responses from the LLM

`ats editor`

Launches a full-featured translation editor web UI in your browser. Includes a side-by-side key editor, LLM-powered auto-translation via Ollama, per-key source code usage tracking, progress bars, and add/delete key support.

npx @angular-translation-service/cli editor

Option	Default	Description
`-i, --input <dir>`	auto-detected	i18n source directory (auto-discovers from angular.json or convention)
`-s, --src <dir>`	`src`	Source code directory for scanning key usage
`-p, --port <port>`	`4500`	Port to serve the editor on

Features

Source and target language picker with side-by-side editing
Real-time LLM translation via Ollama with SSE streaming
Per-key source code usage badges (shows where each key is referenced)
Translation progress tracking per language and namespace
Add, delete, and search keys across all namespaces
Structural validation directly in the UI
Auto-discovery of i18n directory from angular.json or common conventions

`ats mcp`

Starts a STDIO-based Model Context Protocol (MCP) server that exposes all translation editor capabilities as tools for AI agents. Compatible with Claude Code, Cursor, Windsurf, Gemini CLI, and any MCP-compatible client.

npx @angular-translation-service/cli mcp \
  --provider ollama \
  --model gemma3:12b

Option	Default	Description
`--provider <name>`	`ollama`	LLM provider for translation
`--model <model>`	`gemma3:12b`	LLM model name
`--host <host>`	`localhost:11434`	Ollama server address
`--base-url <url>`	`https://api.openai.com`	OpenAI-compatible base URL
`--api-key <key>`	—	API key for cloud providers
`-i, --input <dir>`	auto-detected	i18n source directory (auto-discovered from angular.json)
`-s, --src <dir>`	`src`	Source code directory for scanning

Available Tools (16)

Introspection — get_config, get_progress, validate, scan_hardcoded
Translation CRUD — get_translations, set_translations, add_key, update_key, delete_key, list_missing
LLM Translation — translate_keys, translate_missing, translate_stale, llm_status
Source Code — get_usage, get_scan_context

IDE Configuration

Add the following to your MCP config file (mcp_config.json, .cursor/mcp.json, claude_desktop_config.json, etc.):

// mcp_config.json / .cursor/mcp.json
{
  "mcpServers": {
    "ats": {
      "command": "npx",
      "args": [
        "@angular-translation-service/cli",
        "mcp",
        "--provider", "ollama",
        "--model", "gemma3:12b"
      ]
    }
  }
}

Features

STDIO transport — works with any MCP-compatible AI agent or IDE
Auto-discovers i18n directory and project configuration
Multi-provider LLM support (Ollama, OpenAI, Gemini)
Batch translation with automatic batching and per-key fallback
Template scanning for hardcoded strings with scored candidates

CI Integration

Add translation checks to your CI pipeline to catch issues early.

# .github/workflows/i18n.yml
name: i18n Checks
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 @angular-translation-service/cli generate --check
      - run: npx @angular-translation-service/cli validate -i src/i18n
      - run: npx @angular-translation-service/cli check --i18n src/i18n/en --src src