Docs · i18n guardrails

i18n guardrails (skill + hook)

Sonenta ships an optional skill and guard hook for Claude Code that make internationalization the default in your project, so new user-facing text becomes a managed translation key instead of a hardcoded string, and anything that slips through gets flagged the moment it is written.

They are opt-in, non-intrusive, and run entirely locally (no backend calls).

What you get

A skill (sonenta-i18n)

Ambient guidance that loads automatically when your project’s Claude session touches UI text. It steers Claude to register new user-facing strings as Sonenta keys (via the MCP tools or the CLI), follow your glossary, preserve placeholders and plurals, and keep coverage green. You do not invoke it, it just makes i18n the default way strings get written.

A guard hook

Runs on every file edit. It scans UI files (.tsx, .jsx, .ts, .js, .vue, .svelte) for hardcoded user-facing strings and, if it finds any, prints an alert and nudges Claude to extract them into keys. Strings already routed through t() / <Trans>, bound attributes, URLs, and identifiers are ignored, so false positives stay low.

Why

Hardcoded strings are the most expensive place to lose i18n: they escape review, ship to production, and surface as untranslated screens for real users. Catching them at the moment of the edit, in the editor, before commit, before CI, is the cheapest fix. And because every new string flows into Sonenta as a key, your translation coverage, glossary, and translation memory keep improving with ordinary day-to-day work.

Install

Requires the Sonenta CLI. CLI docs →

# in your project root
sonenta skills add sonenta-i18n

This writes three files under .claude/ and merges the hook into your settings without touching anything else you have there:

.claude/skills/sonenta-i18n/SKILL.md      # the ambient skill
.claude/hooks/sonenta-i18n-guard.mjs      # the guard
.claude/settings.json                     # a PostToolUse(Edit|Write) entry

Reload your Claude Code session afterward, skills load at session start.

You can also turn it on when scaffolding a project:

sonenta init --skills

Opt-in and enforcement

Default: advisory. The guard alerts on hardcoded strings; it never blocks your work.
Enforce (opt-in): set SONENTA_HOOK_BLOCK=1 in the session to turn the guard into a hard gate that asks Claude to resolve the strings before moving on.

export SONENTA_HOOK_BLOCK=1   # make the guard blocking for this session

Keeping it current

The skill and hook are versioned templates. To refresh installed ones to the latest bundled version:

sonenta update          # refreshes agents + skills; preserves anything you customized
sonenta skills list     # see what is available and what is installed

If you edited the installed skill or hook yourself, sonenta update leaves it untouched and reports it as customized, re-run with --force to overwrite.

Remove

sonenta skills remove sonenta-i18n

This deletes the skill and hook files and prunes only its entry from .claude/settings.json, leaving any other hooks and settings intact.

Command reference

Command	What it does
sonenta skills list	List bundled skills and whether each is installed
sonenta skills add sonenta-i18n	Install the skill + guard hook (merge-safe); `--force` to overwrite
sonenta skills remove sonenta-i18n	Remove the skill, hook, and its settings entry
sonenta init --skills	Opt in while scaffolding a project
sonenta update	Refresh installed skills (and agents) to the latest version
SONENTA_HOOK_BLOCK=1	Environment flag, make the guard blocking for the session

Always reload your Claude Code session after add / remove / update, skills load at session start.