i18n
Manage translations for this Svelte SPA's custom i18n system. Use whenever the user mentions translations, i18n, langStore, t(), adding/translating keys, hardcoded strings, missing translations, langu
SKILL.md.claude/skills/i18n/SKILL.md
GitHubi18n for this Svelte SPA
This project uses a custom i18n system (NOT Paraglide — see AGENTS.md decision #6 for why). All operations should preserve this architecture: flat JSON files + t(key, vars?) function. Do NOT migrate to Paraglide/inlang or introduce compile-time extraction without explicit user request.
Project conventions (DO NOT BREAK)
File layout
- Translation files:
frontend/src/lib/i18n/{en,id}.json - Loader:
frontend/src/lib/i18n/index.svelte.ts - Base language:
en(English) — reference structure for integrity/validation checks - Second language:
id(Indonesian) - Keep both files in sync — any add/delete must update BOTH
Key style — FLAT snake_case
Keys are flat dotted strings using underscores, grouped by prefix. Examples:
site_name, site_tagline
nav_home, nav_admin
hello_title, hello_subtitle, hello_description
admin_title, admin_text
login_title, login_username, login_password
Never use nested objects ({"nav": {"home": "..."}}) — this project uses flat keys only. When using the MCP, tools may suggest nested style — override to flat or reject nested key suggestions.
Interpolation
Uses {var} placeholder syntax:
"items_count": "{count} items"
t('items_count', { count: 3 })
When adding translations with placeholders, ensure the same {var} names appear in both en and id versions. The interpolator does not validate missing vars — output will show the literal {var} text.
Usage in components
<script>
import { t, i18n } from '$lib/i18n/index.svelte';
</script>
<h1>{t('site_name')}</h1>
<button onclick={() => i18n.toggle()}>{t('lang_toggle')}</button>
Never call t() outside Svelte reactive context expecting reactivity — t() reads i18n.current which is $state, so it only updates inside Svelte components.
Editing translations
There's no MCP server wired up for this project's i18n (only playwright and svelte are configured in .opencode/opencode.json) — this is plain JSON, so read and edit the files directly rather than looking for a specialized tool.
User asks "what's missing / is everything translated?"
- Read both
en.jsonandid.jsonand diff the key sets — a key present in one but not the other is a bug - Grep
frontend/srcfort('...')calls and confirm every key referenced in code actually exists in both files - Report using a markdown table: | key | status | notes |
User asks "add a new translation key" or "translate [string]"
- Check whether a similar key already exists first (grep for the English text or a likely key prefix)
- Add the new key to both
en.jsonandid.json, using the flat snake_case style with the appropriate prefix (nav_,hero_,section_,about_,admin_,settings_, etc.) — keep it at the same relative position in both files so they stay easy to diff by eye - Wire it up in the component with
t('new_key') - Remind the user: "Restart
pnpm devor refresh the page — Svelte doesn't hot-reload JSON imports."
User asks "extract hardcoded strings" / "find untranslated text in component"
- Read the component and identify literal user-facing strings not already wrapped in
t(...) - Propose keys in the snake_case style above, with EN/ID translations
- Do NOT auto-extract — show the user the proposed texts → keys → EN/ID translations and ask for confirmation
- After confirmation, add the keys to both JSON files and replace the literal strings with
t('key')calls
User asks "rename / delete a key"
- Grep
frontend/src/for every reference to the key first: pattern\bt\(['"]old_key['"] - Show the user every call site before touching anything
- After the user confirms, rename/delete in both
en.jsonandid.json, then update every.sveltefile that calledt('old_key', ...)
User asks "show structure / stats" or "validate / organize files"
Read both JSON files directly and compare — there's no dedicated tool for this, it's just JSON. If the key sets have drifted apart, add the missing keys (ask the user for the translation text if you don't know it) rather than silently deleting the extras.
Common pitfalls
1. Keys with mixed casing
The project enforces lowercase snake_case. If the MCP suggests nav.Home or nav_home_page_title_v2, reject silently and propose the project-style equivalent (nav_home, home_title).
2. Plurals / count
There is no pluralization system. Keys like items_count accept {count} and render as "{count} items". Do not introduce ICU MessageFormat or new plural libraries.
3. Component rewiring after key rename
After renaming any key, ALL .svelte files using t('old_key', ...) must be updated. Use grep:
pattern: \bt\(['"]old_key['"]
include: *.svelte
4. Adding a third language (e.g., zh)
- Create
frontend/src/lib/i18n/zh.jsonwith all keys (copy fromen.jsonas starting point) - Update
index.svelte.ts: extendLangtype + adding todictionaries - Update
i18n.toggle()— currently only flips en ↔ id, won't rotate to third language - Update MCP config if needed; MCP will auto-detect the new file
- Verify with
i18n_check_translation_integrity
5. Spaces and special chars in keys
Keys must match [a-z][a-z0-9_]*. Indonesian text with /, :, spaces in value is fine — only keys are constrained.
Important: do NOT touch
frontend/src/lib/i18n/index.svelte.ts— Svelte store mechanics are stable. Only modify when adding a third language.- IDs of existing translations: renaming breaks runtime silently (
t('old_key')returns the raw literal). Always grep first. - The
STORAGE_KEY = 'desa_wisata_lang'constant inindex.svelte.ts— used by existing users; changing it forgets their language preference.
Verification after any change
Before declaring "done":
- Confirm
en.jsonandid.jsonhave identical key sets (no key present in only one) - Grep
frontend/srcfor everyt('key')call and confirm each key exists in both files - If you added
{var}interpolation, confirm the same{var}names appear in both language versions