I18n

i18n: Find and edit translation keys

You are helping the user manage i18n JSON translation files for the Welcome To My Garden (WTMG) SvelteKit project.

File locations

All locale files live in src/locales/. Enumerate them using find src/locales -name "*.json" | head -20 (from the repo root). The currently supported languages are defined in the SUPPORTED_LANGUAGES constant in src/lib/types/general.ts.

The 5 standard locales are: en, nl, de, fr, es.

How to respond to user requests

If no args are given, ask the user what they want to do — options include:

• Find where a key is used in the codebase
• Add a new translation key across all locales
• Check which keys are missing in non-English locales
• Edit an existing translation value
• Build a translation worksheet for what changed since a commit (since.py)
• Find translation keys that look unused, for review before deletion (unused.py)
• Clean up empty {} subtrees left behind after removing keys (prune-empty.py)

If args are given, interpret them as the task. Common forms:

• add <key-path> "<english value>" — add a new key to all locale files
• find <key-path> — show the current value of a key in all locales
• missing — list keys present in en.json but absent in at least one other locale
• edit <key-path> — show current values and update translations

Key rules

1. Always use the scripts in scripts/. Do not edit the JSON files by hand or with the Edit tool — use the scripts. They preserve the file's indent=2 formatting, UTF-8 (non-ASCII) characters, and trailing newline, so diffs stay clean.
2. Edit all locales together. When adding or editing a key, update all 5 locale files. Generate the translations yourself — you don't need to ask the user for them. Only ask if the user has told you about a specific translation source/process to follow. Follow translation guidelines in guidelines.md.
3. English is the source of truth. When checking for missing keys, compare all locales against en.json.
4. Never create a new locale file. Only edit the locale files that already exist in src/locales/. Do not seed or scaffold a *.json for a language that isn't there yet (e.g. pl) — adding a language is a separate, deliberate step (registering it in SUPPORTED_LANGUAGES and wiring it up). When asked to translate into a not-yet-supported language, deliver the translations in the since.py CSV worksheet instead (see below), never in a new locale file.
5. Don't fill in a value that would be identical to English. svelte-i18n falls back to the English value whenever a key is absent from a locale (fallbackLocale: 'en' in src/routes/+layout.ts). So if the correct translation for a locale is exactly the same string as en — a proper name, a do-not-translate term (WTMG, Superfan, Welcome To My Garden), or a value that's "" in English too — leave the key absent from that locale instead of duplicating the English string. This is intentional, not an oversight: don't "fix" it by filling these in when you see them in missing.py output, and don't re-add them after they've been removed for this reason, unless the user explicitly asks for full key parity across locales. This only applies when the value would be truly identical — if it differs even slightly (e.g. French adding a space before ?), it's a real translation and belongs in the file.

Locating keys in code

Translation keys are referenced via $_('key.path') or $t('key.path') in Svelte components, and get(_)('key.path') or get(t)('key.path') in JS/TS files.

To find where a key is used:

grep -r "key.path" src/

Keys can also be dynamically generated (e.g. root.${dynamicKeyPart}.subkey), so grep doesn't give a 100% guarantee.

Scripts

The skill ships three Python scripts in the scripts/ folder next to this file. Run them from the repo root so that src/locales resolves. They require only the Python 3 standard library. Each accepts --help and an optional --base <dir> to point at a different locales directory.

Reference the scripts by their path relative to the repo root, e.g. .agents/skills/i18n/scripts/show.py.

show.py <key-path> [--lang en] — read a key or section

Prints the value at a dot-notation path for every locale. Works for leaf keys (prints the string) and whole sections (dumps the subtree). Use it to inspect current state before editing, to answer find <key-path>, or to see a section's structure before adding keys to it.

python3 .agents/skills/i18n/scripts/show.py chat.archive      # one key, all locales
python3 .agents/skills/i18n/scripts/show.py chat              # whole section
python3 .agents/skills/i18n/scripts/show.py chat.archive --lang en

Missing keys print as <missing>.

missing.py [--lang nl] — diff locales against en.json

Reports, for each non-English locale, the keys present in en.json but absent there ("missing"), and any keys present there but not in en.json ("extra"). Use it for the missing request and to audit translation completeness.

Not every "missing" key is a gap to fill — per key rule 5, a key that's intentionally left absent because its translation is identical to English will show up here too. Before translating a reported-missing key, check whether it's actually one of these identical-to-English cases; if so, leave it absent.

python3 .agents/skills/i18n/scripts/missing.py
python3 .agents/skills/i18n/scripts/missing.py --lang nl

patch.py [patch.json] — add or update keys

Reads a JSON patch keyed by locale, whose values mirror the nested JSON structure (not dot-notation), and deep-merges it into each locale file — so only the keys you specify are touched and sibling keys are preserved. It works for a single key or a large batch.

Pass the patch as a file argument or pipe it on stdin (a heredoc is usually easiest):

python3 .agents/skills/i18n/scripts/patch.py << 'EOF'
{
  "en": { "chat": { "archive-confirm": "Are you sure you want to archive this conversation?" } },
  "nl": { "chat": { "archive-confirm": "Weet je zeker dat je dit gesprek wilt archiveren?" } },
  "de": { "chat": { "archive-confirm": "Möchten Sie diese Unterhaltung wirklich archivieren?" } },
  "fr": { "chat": { "archive-confirm": "Voulez-vous vraiment archiver cette conversation ?" } },
  "es": { "chat": { "archive-confirm": "¿Seguro que quieres archivar esta conversación?" } }
}
EOF

It prints which keys it touched per file. Nested sections (e.g. no-archived.title) and ICU placeholders ({name}, {count}) are just normal JSON values — include them verbatim.

remove.py <key-path> [--lang nl] — delete a key or section

Deletes the key at a dot-notation path from every locale (or one with --lang). Works for a leaf or a whole subtree. Any parent object left empty by the deletion is pruned, so no empty {} husks remain.

python3 .agents/skills/i18n/scripts/remove.py chat.archived-new-activity
python3 .agents/skills/i18n/scripts/remove.py chat.tip            # whole subtree

rename.py <old-path> <new-path> [--lang nl] — rename/move a key

Moves a key (leaf or section) to a new dot-notation path in every locale, preserving each locale's own translated value. Creates destination parents as needed and prunes emptied source parents. It does not touch source code — grep for $_('old.path') / get(_)('old.path') references in components and update them yourself.

# 1. update the component reference(s) first:
grep -rn "chat.archived-new-activity" src/
# 2. then move the key across all locales:
python3 .agents/skills/i18n/scripts/rename.py chat.archived-new-activity chat.open-archive