i18n-guidelines

Prompt file imported from ZACK770/studytoy (.windsurf/workflows/i18n-guidelines.md). Copyright stays with the author.

i18n Guidelines

Setup in Every Component

import { useTranslation } from 'react-i18next'

export default function MyComponent() {
  const { t, i18n } = useTranslation()

Rules

1. No hardcoded UI text — every user-visible string goes through t().
2. No emojis — use Lucide icons instead.
3. Do not translate user-generated content (game names, descriptions, comments, etc.).
4. Every new key must be added to both JSON files:
   • frontend/src/i18n/locales/en.json (English — also the fallback)
   • frontend/src/i18n/locales/he.json (Hebrew)
5. Key naming: namespace.keyName, e.g. settings.title, settings.saveBtn.
6. Static label arrays — use labelKey instead of inline strings:

   const TABS = [{ labelKey: 'nav.settings' }, { labelKey: 'nav.profile' }]
   // In JSX: {t(tab.labelKey)}

7. Dynamic values — use interpolation:

   t('common.level', { level: 5 })  // "Level 5" / "רמה 5"

8. RTL/LTR — standalone pages/modals should set:

   dir={i18n.language === 'he' ? 'rtl' : 'ltr'}

   Components inside AppShell inherit direction automatically.

Fallback Behavior

• fallbackLng is set to 'en' in frontend/src/i18n/index.ts.
• If a translation key is missing, English text is shown automatically.

Workflow

Write component → Add keys to en.json + he.json → Verify build (npx tsc --noEmit)

Adding a New Language

1. Copy en.json to a new file, e.g. ar.json.
2. Translate all values (keep keys unchanged).
3. Register in frontend/src/i18n/index.ts:

   import ar from './locales/ar.json'
   // In resources:
   ar: { translation: ar },
   // In supportedLngs:
   supportedLngs: ['he', 'en', 'ar'],

4. For RTL languages, update the direction check:

   const dir = ['he', 'ar'].includes(lng) ? 'rtl' : 'ltr'