Complete Command Reference
Interactive Ink console UI for humans, plus non-interactive --json mode for autonomous AI agents.
Automated Project Setup
Auto-detects framework, adds shallok to devDependencies, and copies pre-packaged AI skills into .agents/skills/.
Architecture & Language Scan
Analyzes project layout, source language, target catalogs, and existing translation files with structured JSON output for AI agents.
Catalog Initialization
Scaffolds localization.json, base catalogs, and framework routing/middleware files with non-interactive flags.
AST Code Transformation
Parses TSX/JSX, extracts user strings into canonical keys with SHA-256 hashes, and safely rewrites source files with t(...) calls.
Contextual Translation
Zero external API keys! Translates missing and stale keys with rich UI context preservation and placeholder validation.
Integrity & Token Validation
Verifies target catalogs have zero missing keys, zero stale source hashes, and valid ICU placeholders prior to production deployment.
Global CLI Flags & Agent Options
Every Shallok command supports these global flags for headless CI/CD runners and AI coding agents.
| Flag | Type | Description & Use Case |
|---|---|---|
| --json | boolean | Suppresses terminal animations and emits structured JSON stdout for AI coding agents to parse deterministically. |
| -y, --yes | boolean | Automatically confirms all interactive prompts (ideal for non-interactive agent execution and Docker builds). |
| --verbose | boolean | Prints verbose AST traversal logs, SHA-256 hash calculations per key, and diff traces. |
| --config <path> | string | Custom path to localization.json (defaults to project root). |
| -h, --help | boolean | Displays help message and command syntax options. |
Automate in GitHub Actions CI
Block pull requests if translation keys have missing variables, placeholder leaks, or un-translated hashes.
name: i18n Verification
on: [push, pull_request]
jobs:
validate-translations:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
- uses: actions/setup-node@v4
with:
node-version: 22
cache: 'pnpm'
- run: pnpm install --frozen-lockfile
# Fails CI if any translation catalog has stale source hashes or missing tokens
- run: npx shallok validate --ci