i18n-workflow_skill

Overview

This skill defines a standardized multilingual development workflow for a Mario Kart world player web application. It enforces consistent JSON translation files across five languages (Traditional Chinese, Simplified Chinese, English, Japanese, Korean) and provides patterns for keys, persistence, and runtime switching. The goal is predictable translations, easy maintenance, and reliable language switching in UI components.

How this skill works

The workflow prescribes a file layout under src/i18n/locales with one JSON file per supported language and a central i18next configuration. It enforces a dot-separated key namespace (category.subcategory.key), requires simultaneous updates to all five locales, and includes utilities for language persistence using a Jotai atom and a hook to sync i18next. It also documents testing, JSON validation, pluralization, parameterized strings, and recommended review practices.

When to use it

• Adding any user-visible text or messages
• Modifying existing text that will be shown to users
• Introducing a new feature that requires translations
• Validating translation completeness before merge
• Implementing or fixing language selection and persistence

Best practices

• Define and follow a consistent key namespace (category.subcategory.key)
• Always update all five locale files together to keep structure identical
• Use t() in components instead of hardcoded text and prefer Trans for inline HTML
• Keep translations concise to fit UI constraints and handle long content via multiple keys
• Assign language owners and review translation PRs; track translation changes in Git

Example use cases

• Adding a new feature: add keys in newFeature.* to all locale JSONs and use t('newFeature.title') in the component
• Language selector: wire i18n.changeLanguage and persist with a Jotai atomWithStorage key like 'mario-kart-language'
• Dynamic content: implement parameterized strings for greetings and item counts using {{name}} and count-based plural keys
• CI check: run a script that reads all locale JSONs and fails the build if key structures differ
• Image localization: load language-specific assets based on current i18n.language