Skip to main content

i18next-translation

Find hardcoded user-facing strings, replace them with t() calls, and add the corresponding keys to both locale files (he.json AND en.json). Ported from cursor-rules; the conventions are owned by i18n-localization, applied in components by frontend-developer.

Per-app i18n lib: i18next/react-i18next on the dashboards, next-i18next on management, next-intl on the consumer app. Match the app you are in.

When NOT to use​

  • Technical values (IDs, class names, log messages, keys).
  • 3rd-party component props that expect non-translated values.
  • Strings already wrapped in t().

Workflow​

1. Detect hardcoded strings​

  • JSX text nodes: <h1>Welcome back</h1>, <span>Submit</span>.
  • String literals in user-facing attributes: placeholder="Search…", aria-label="Close".
  • Button/link labels, headings, error messages, tooltips, toasts.

2. Convert to t()​

// before
<h1>Welcome back</h1>
<button>Submit</button>

// after
import { useTranslation } from 'react-i18next';
const MyComponent = () => {
  const { t } = useTranslation();           // top of the component, namespace if applicable
  return <><h1>{t('welcomeBack')}</h1><button>{t('submit')}</button></>;
};

Add the useTranslation import + const { t } = useTranslation() if missing.

3. Key naming​

  • camelCase: welcomeBack, submitForm, noResults β€” descriptive, context-aware (userProfileTitle, not title).
  • Namespaces / dot-notation: common.cancel, dashboard.org.sectionName.
  • Check the existing locale files for the project's established patterns before adding.

4. Generate keys in BOTH locales​

Add to both src/i18n/en.json and src/i18n/he.json β€” never one without the other (Hebrew is first-class, not a stub). Keep the key sets identical.

// en.json            // he.json
{ "welcomeBack": "Welcome back", "submit": "Submit" }   { "welcomeBack": "Χ©ΧœΧ•Χ Χ©Χ•Χ‘", "submit": "Χ©ΧœΧ—" }

5. Type-safety + legacy migration​

  • Prefer typed resources (i18next.d.ts / useTranslation<'ns'>()) so a bad key fails compile.
  • If you see const { t } = useAppData(); (legacy), migrate it to useTranslation and move the strings into the locale files.

Output​

The edited component (strings β†’ t()) + the new keys added to both he.json and en.json, reported with the namespace used. The wording of customer copy is product/PRD Β§7.4; you own the key + the mechanism.

Cross-references​

  • i18n-localization β€” owns the key conventions + RTL + locale files.
  • frontend-developer β€” wires t() into components.
  • Source: cursor-rules bewith-i18next-translation skill + bewith-i18n-conventions.mdc.