Skip to content
HammertailPublic

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

catlex

CLI to validate next-intl-style translation JSON files against a base locale, and scan JSX/TSX/Vue SFCs for hardcoded user-visible strings.

Catch missing keys before they hit production, optionally fail on keys that exist only in a locale file, (alpha) flag UI copy that never entered the message files, and (alpha) propose or review translations (optionally scoped to git changes with --since).

Install

Linux / macOS

curl -fsSL https://github.com/Hammertail/catlex/releases/latest/download/install.sh | bash

latest is convenient for humans. For CI and other production runners, pin a version:

curl -fsSL https://github.com/Hammertail/catlex/releases/download/v0.0.1/install.sh | CATLEX_VERSION=0.0.1 bash

The installer detects OS and architecture (linux/darwin, x64/arm64), verifies the binary against the release SHA256SUMS (the install fails if it is missing or does not match), and installs to ~/.local/bin/catlex.

The installer adds a marked # >>> catlex PATH >>> block to the startup file of your login shell ($SHELL):

  • Bash on Linux: ~/.bashrc.
  • Bash on macOS: the login file Bash reads, which is the first existing file among ~/.bash_profile, ~/.bash_login and ~/.profile. If none exists, it creates ~/.bash_profile.
  • Zsh: ${ZDOTDIR:-~}/.zshrc.
  • fish: ~/.config/fish/conf.d/catlex.fish.

It also adds the block to the Bash and Zsh startup files and the fish config directory you already have, so a terminal that runs a different shell (for example Bash in VS Code while your login shell is Zsh) also finds catlex. The block only adds the directory when it is missing from PATH, so it never creates duplicate entries.

Reinstalling updates the existing block in place and leaves the file untouched when nothing changed. If the file has a start marker without the matching # <<< catlex PATH <<< line, the installer leaves the file as it is and asks you to fix it. For any other shell, or when a startup file cannot be updated, the installer prints manual instructions and the binary's full path.

The installer runs in a child process (curl ... | bash), so it cannot change the PATH of the terminal you ran it from. Open a new terminal or terminal tab, or run the export PATH=... command it prints.

Set CATLEX_NO_MODIFY_PATH=1 to skip startup-file changes. They are also skipped when CI is set; in GitHub Actions, append the directory to $GITHUB_PATH instead (see docs/ci.md).

Windows (x64)

irm https://github.com/Hammertail/catlex/releases/latest/download/install.ps1 | iex

Pin a version (recommended for CI):

$env:CATLEX_VERSION='0.0.1'; irm https://github.com/Hammertail/catlex/releases/download/v0.0.1/install.ps1 | iex

The binary is installed to %LOCALAPPDATA%\catlex\bin\catlex.exe. The installer verifies the download against the release SHA256SUMS and fails if it is missing or does not match.

If the install directory is missing from your user PATH, the installer appends it. It only edits the user PATH stored in the registry, leaves the system PATH alone, and keeps existing entries such as %USERPROFILE%\... as they are. A relative CATLEX_INSTALL_DIR is stored as an absolute path. Reinstalling never adds the entry twice. With irm ... | iex, catlex works right away in the PowerShell session that ran the installer. Otherwise, run the $env:Path = ... command it prints. Other terminals that are already open keep their old PATH: open a new one, and fully restart VS Code or Windows Terminal if you use their terminals. Set CATLEX_NO_MODIFY_PATH=1 (or CI) to leave the user PATH unchanged.

Quick start

With a messages directory like this:

messages/
  en.json
  pt.json
  es.json

Run:

catlex validate

By default catlex looks for messages/ and treats en.json as the base locale.

Feature deep-dives (how each command works, JSON shapes, CI): docs/.

What it checks

Issue Meaning Default
Missing Key exists in the base locale but not in another locale Error
Extra Key exists in a locale but not in the base Warning

Use --strict-extra to treat extra keys as errors.

Usage

catlex validate [options]
Option Description
--dir <path> Messages directory relative to the project root
--base <locale> Base locale file stem (e.g. en → en.json)
--cwd <path> Project root (default: current directory)
--strict-extra Treat extra keys as errors
--no-config Do not load or execute project catlex.config.* files
--allow-js-config Allow loading catlex.config.js|mjs|ts (executes project code)
--json Print JSON instead of the interactive terminal UI

Examples:

catlex validate
catlex validate --dir locales --base en
catlex validate --strict-extra
catlex validate --json
catlex validate --no-config --json

Configuration

Optional. Place a config file in the project root. First match wins:

  1. catlex.config.json
  2. catlex.config.js
  3. catlex.config.mjs
  4. catlex.config.ts

CLI flags override the config file. Defaults:

Field Default
messagesDir "messages"
baseLocale "en"
strictExtra false

Example catlex.config.json:

{
  "messagesDir": "messages",
  "baseLocale": "en",
  "strictExtra": false,
  "translate": {
    "guidanceFile": "glossary.md"
  }
}

.js / .mjs / .ts configs are executable code (dynamic import) and are refused by default. Pass --allow-js-config only in trusted local environments. Prefer catlex.config.json, or --no-config with CLI flags. Generated GitHub Actions workflows from catlex ci include --no-config by default.

JSON config is still project-controlled policy (not just data): it can set openai.baseUrl / openai.headers. Catlex rejects non-https and private/link-local base URLs unless you pass --allow-insecure-base-url.

Source scan (alpha)

Scan JSX/TSX/Vue SFCs for obvious hardcoded user-visible strings that should go through next-intl instead:

catlex scan
catlex scan --dir src
catlex scan --json
Option Description
--dir <path> Source root relative to the project root (default: .)
--cwd <path> Project root (default: current directory)
--json Print JSON instead of the interactive terminal UI

This command is alpha: false positives and missed issues may occur. Detection covers JSX text and common user-facing attributes (placeholder, alt, title, aria-*); translation calls like t("…") and <Trans> children are not flagged.

AI translate (alpha)

Fill missing string keys by comparing each locale against the base locale and asking OpenAI to propose translations:

export OPENAI_API_KEY=sk-...
catlex translate --dry-run
catlex translate --yes
catlex translate --locale pt --model gpt-5.4-mini
catlex translate --base-url https://openrouter.ai/api/v1 --model openai/gpt-5.4-mini
catlex translate --json
Option Description
--dir <path> Messages directory relative to the project root
--base <locale> Base locale file stem (e.g. en)
--cwd <path> Project root (default: current directory)
--locale <locale> Target locale (repeatable or comma-separated; default: all non-base)
--model <id> OpenAI model id (default: gpt-5.4-mini)
--base-url <url> OpenAI-compatible API base URL (default: official OpenAI endpoint)
--dry-run List missing keys without calling the API or writing files
--yes Skip both interactive prompts and write files
--no-config Do not load or execute project catlex.config.* files
--allow-js-config Allow loading catlex.config.js|mjs|ts (executes project code)
--allow-insecure-base-url Allow http or private/link-local OpenAI base URLs
--json Print JSON instead of the interactive terminal UI
--concurrency <n> Max parallel translation API calls (default: 4, range 1–32)
--guidance <text> Extra project guidance appended to the model prompt
--guidance-file <path> Read extra project guidance from a file inside --cwd (absolute only if still under --cwd; symlinks refused)

Requires OPENAI_API_KEY in the environment. Catlex never stores API keys in config files.

To use an OpenAI-compatible provider (OpenRouter, proxies, self-hosted gateways), set a base URL via --base-url, OPENAI_BASE_URL, or openai.baseUrl in catlex.config.* (CLI wins over config over env). The URL must be public https unless you pass --allow-insecure-base-url (for trusted local proxies). The endpoint must implement the OpenAI API surface Catlex uses (chat completions with tool calling). Optional provider headers (for example OpenRouter HTTP-Referer / X-Title) can be set under openai.headers in config only. Parallelism is translate.concurrency in config or --concurrency on the command (CLI wins over config over the default of 4). Extra translation guidance (a terminology glossary) is translate.guidance, translate.guidanceFile, --guidance, or --guidance-file (CLI inline text wins over the CLI file, which wins over config inline, which wins over config file; do not pass both CLI flags). --guidance-file must resolve inside --cwd (absolute only if still under --cwd; no symlinks); translate.guidanceFile must resolve inside the config file directory. Guidance file contents are sent to the LLM provider:

{
  "openai": {
    "baseUrl": "https://openrouter.ai/api/v1",
    "headers": {
      "HTTP-Referer": "https://example.com",
      "X-Title": "My App"
    }
  },
  "translate": {
    "concurrency": 8,
    "guidanceFile": "glossary.md"
  }
}
OPENAI_API_KEY=... OPENAI_BASE_URL=https://openrouter.ai/api/v1 catlex translate --model openai/gpt-5.4-mini

--dry-run only reports which string keys are missing (and which non-string leaves are skipped). It does not call the model and does not require OPENAI_API_KEY.

In interactive mode (no --yes / --dry-run), catlex asks whether to run automatic translation before calling the model, then shows the proposals and asks again before writing files. --yes skips both prompts.

This command is alpha: translations may be incorrect and bugs may occur. Only missing string leaves are filled; arrays and other non-string values are skipped. Existing locale files are updated in place — new locale files are not created.

AI translate Markdown (alpha prototype)

Translate one Markdown file, or every Markdown file in a directory. The file command takes one --to locale. The directory command repeats --to <locale> <dir> for each target.

export OPENAI_API_KEY=sk-...
catlex translate markdown ./docs/en/example.md --from en --to pt-BR --out ./docs/pt-BR/example.md
catlex translate markdown ./docs/en/example.md --from en --to pt-BR --out ./docs/pt-BR/example.md --dry-run --json
catlex translate markdown dir ./example/en --from en --to pt-BR ./example/pt-BR
catlex translate markdown dir ./example/en --from en --to pt-BR ./example/pt-BR --to fr ./example/fr --to ru ./example/ru
Option / argument Description
<file> Markdown source (.md or .markdown) for translate markdown
<dir> Source directory for translate markdown dir
--from <locale> Source locale
--to <locale> Target locale for translate markdown (one locale)
--to <locale> <dir> Target locale and output directory for translate markdown dir (repeat for each locale)
--out <path> Write translated Markdown here (translate markdown only)
--cwd <path> Project root (default: current directory)
--model <id> OpenAI model id (default: gpt-5.4-mini)
--base-url <url> OpenAI-compatible API base URL (default: official OpenAI endpoint)
--dry-run Validate sources without calling the API or writing
--no-config Do not load or execute project catlex.config.* files
--allow-js-config Allow loading catlex.config.js|mjs|ts (executes project code)
--allow-insecure-base-url Allow http or private/link-local OpenAI base URLs
--json Print JSON instead of text
--concurrency <n> Max in-flight translations for translate markdown dir (default 4, range 1–32)
--guidance <text> Extra project guidance appended to the model prompt
--guidance-file <path> Read extra project guidance from a file inside --cwd (absolute only if still under --cwd; symlinks refused)

--from and --to are required. The file command also requires --out. Sources must stay under --cwd. Each file is at most 64 KiB. A missing output directory is created; an existing file is overwritten with no confirm prompt. translate markdown dir walks the source directory recursively, keeps relative paths, and skips files that are not Markdown. Each --to is one locale followed by its output directory. File and locale pairs run together, up to --concurrency at a time.

This command is alpha. See Translate Markdown.

AI translate review (alpha)

Review existing translations with OpenAI. Missing keys in scope are errors. Present keys are judged ok or wrong.

Before API calls, the command prints the resolved source locale, target locale(s), messages directory, and model, then streams key progress. With --json, that banner and progress go to stderr so stdout stays pure JSON. At the end it prints a compact summary (keys reviewed, issues found, fixes, files changed, locales, model).

export OPENAI_API_KEY=sk-...
catlex translate review --json
catlex translate review --since main --json
catlex translate review --since main --auto-fix --yes --json
catlex translate review --verbose
Option Description
--dir <path> Messages directory relative to the project root
--base <locale> Base locale file stem (e.g. en)
--cwd <path> Project root (default: current directory)
--locale <locale> Target locale (repeatable or comma-separated; default: all non-base)
--model <id> OpenAI model id (default: gpt-5.4-mini)
--base-url <url> OpenAI-compatible API base URL (default: official OpenAI endpoint)
--since <ref> Only review keys changed between <ref> and the current working tree (recommended in CI)
--auto-fix Propose fixes for wrong / missing keys
--yes Apply auto-fix writes without interactive confirmation
--no-config Do not load or execute project catlex.config.* files
--allow-js-config Allow loading catlex.config.js|mjs|ts (executes project code)
--allow-insecure-base-url Allow http or private/link-local OpenAI base URLs
--json Print JSON instead of the interactive terminal UI
--verbose Print per-chunk progress details (paths reviewed in each batch)
--concurrency <n> Max parallel translation API calls (default: 4, range 1–32)
--guidance <text> Extra project guidance appended to the model prompt
--guidance-file <path> Read extra project guidance from a file inside --cwd (absolute only if still under --cwd; symlinks refused)

Without --since, catlex reviews the full corpus (every string key in the base locale × each target locale). That is expensive and noisy — prefer --since locally for focused work and always in CI. Full-corpus review still issues one model call per chunk of 50 keys; the default of 4 concurrent calls reduces wall-clock time but does not change how many calls run in total.

With --since:

  • Diff is since…working tree (includes uncommitted message edits).
  • A change in the base locale file causes that path to be reviewed in every target locale.
  • A change only in a sibling locale file (e.g. pt.json) reviews that path only in that locale, compared to the current base value.
  • Removed keys are reported informatively and do not fail the gate.
  • The report includes a Scope summary: current branch (or detached HEAD), resolved --since SHA, compared message files, and key/removed/skipped counts.

--auto-fix collects suggested values; without --yes, catlex shows proposals and asks before writing. With --auto-fix --yes, fixes are written and the command exits 0 only if every issue was fixed.

Requires OPENAI_API_KEY. This command is alpha: model verdicts may be wrong.

CI example (changed keys only)

Use a full git history (or fetch the base ref) so --since can resolve:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  with:
    fetch-depth: 0

- run: catlex translate review --no-config --since "$CATLEX_SINCE" --json --guidance-file ./glossary.md
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
    CATLEX_SINCE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || 'origin/main' }}

Generated workflows use --no-config. Translate and review jobs also pass --guidance-file ./glossary.md, so keep a glossary at the repository root (or edit the run: line). translate.concurrency in catlex.config.* does not apply on those jobs. They still use the runtime default of 4 parallel API calls. To raise or lower that in Actions, add --concurrency to the workflow run: line.

Pass GitHub context values through env (never interpolate ${{ }} directly into run: scripts). On push (no PR base), the expression above falls back to origin/main. Set optional repository variable OPENAI_BASE_URL when using an OpenAI-compatible endpoint in CI; leave it unset to use the official OpenAI API.

Exit codes and CI

Code Meaning
0 Validation/scan/translate completed (including cancel / nothing to do), or review passed (including successful auto-fix)
1 Validation failed, scan found hardcoded strings, review failed, missing API key, or an unexpected command error
2 scan completed with one or more per-file scanner errors (partial results may still be reported)

For pipelines, prefer --json and --no-config (so project JS/TS config is not executed on the runner):

catlex validate --no-config --json
catlex scan --json
catlex translate --no-config --dry-run --json
catlex translate review --no-config --since origin/main --json

Crash logs

When an unexpected error escapes command handling (an uncaught exception or unhandled rejection), Catlex persists a short crash log to ~/.catlex/logs/, prints the error and the saved path to stderr so it can be attached to bug reports, and exits with code 1. Logs are readable only by your user. Logs older than 30 days are pruned whenever a new crash log is written.

The log contains a timestamp, the command invoked, the working directory, the runtime's Node version, the error message, and the stack trace when available. It never includes environment variables.

Secrets are masked in the logged command: the values of --guidance, --base-url, and any flag whose name contains key, token, secret, or password, plus credentials embedded in URLs (https://user:token@host) and the values of URL parameters with those words in their names (?access_token=...). Masking is best effort, so review a log before sharing it, and avoid uploading ~/.catlex/logs/ as a CI artifact. Logs written by earlier versions are not masked, so delete any that may contain secrets.

To opt out of automatic crash-log creation, set the environment variable CATLEX_NO_CRASH_LOGS=1. Crashes then print the stack trace to stderr instead, and still exit with code 1.

Add GitHub Actions workflows

Interactively scaffold one or more workflows (Space to toggle, Enter to confirm):

catlex ci

(init-ci remains as an alias of ci.)

Workflow File What it does
Validate messages .github/workflows/validate-messages.yml catlex validate --no-config --json
Review translations .github/workflows/review-translations.yml catlex translate review --no-config --since … --json (gate only)
Review, auto-fix, and commit .github/workflows/review-fix-translations.yml Review with --no-config --auto-fix --yes, then commit
Fill missing translations and commit .github/workflows/translate-fill.yml catlex translate --no-config --yes, then commit

AI workflows require repository secret OPENAI_API_KEY. Optionally set Actions variable OPENAI_BASE_URL for an OpenAI-compatible API endpoint (generated workflows pass vars.OPENAI_BASE_URL). Generated installs pin the Catlex version that scaffolded the file. Gate-only jobs use permissions: contents: read. Auto-commit workflows isolate write access to a separate commit job (stefanzweifel/git-auto-commit-action) with a same-repository guard so commits are skipped for fork pull requests. If a selected file already exists, you are asked whether to overwrite it.

Building from source

Requires Bun 1.4.4 (see .bun-version):

bun install
bun run build            # → dist/catlex (current platform)
bun run build:all        # → all release targets
bun run build:linux:x64  # → dist/catlex-linux-x64
bun run build:mac:arm64  # → dist/catlex-darwin-arm64

Per-OS scripts: build:linux:x64, build:linux:arm64, build:mac:x64, build:mac:arm64, build:windows:x64.

How each feature works: docs/. Contributor and agent notes: AGENTS.md.

Development verification

Use the pinned Bun version in .bun-version. Run bun install --frozen-lockfile, bun run check, bun run typecheck, bun run test, bun audit, and bun run fallow:audit. Build with bun run build and verify offline commands with bun run smoke; bun run build:all compiles all five release targets.

TypeScript 7 checks types. The scanner uses Microsoft's @typescript/typescript6 compatibility package because TypeScript 7 does not expose the compiler API used to parse JSX and Vue source. The wrapper is pinned at 6.0.2 and the lockfile resolves its @typescript/old alias to TypeScript 6.0.3. Keep both toolchains updated independently; consumers do not need a TypeScript compiler peer. Update .bun-version, packageManager and @types/bun together; Dependabot leaves Bun types for that coordinated update. Update the Fallow dependency, action SHA and explicit CI CLI version together; those entries are also excluded from independent bot bumps.

New releases include SHA256SUMS. The Unix and Windows installers verify the selected binary before replacing an existing installation; CATLEX_INSTALL_DIR can override the destination. The latest installer requires a checksum-bearing release. To install an older release without a manifest, use that release's own installer. Checksums detect corruption; they do not authenticate a compromised publisher.

New releases also carry a signed SLSA build provenance attestation for every asset. The installers do not check it because they cannot assume the GitHub CLI is present, so verify a downloaded file yourself:

gh attestation verify catlex-linux-x64 --repo Hammertail/catlex --signer-workflow Hammertail/catlex/.github/workflows/release.yml

An attestation proves which workflow and commit produced a file; the commit is the one the release was dispatched from, before the automated version bump. It does not prove that the source or its dependencies are benign. The release workflow builds and tests in a read-only job, and only a separate job that runs no repository or dependency code can sign, push and publish. Release assets are immutable once published, and gh release verify confirms a release still matches what was published. Binaries are not byte-for-byte reproducible across checkout paths or output names, so rely on the attestation instead of comparing a local rebuild. Windows binaries have no Authenticode signature.

Repository CI checks formatting without committing changes, checks types and dependencies, and tests both color modes. It cross-compiles every release target and runs native offline smoke and installer tests on Linux, macOS and Windows. Native checks for other operating systems run in GitHub Actions; cross-compilation locally does not execute those binaries.

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages