i18next-localization-workflow

name	i18next-localization-workflow
metadata	{"category":"Localization and Internationalization (i18n)"}
description	Implement production-grade i18next localization workflows, dynamic locale switching, ICU message syntax formatting, fallback strategies, namespaces, and automated translation extraction. Trigger when configuring internationalization (i18n) in React/Next.js/Vue applications or setting up localization workflows.
compatibility	Node.js 18+, i18next 23+, react-i18next, next-i18next, TypeScript

i18next Localization Workflow Skill Guide

This skill provides architecture standards, directory layouts, configuration patterns, and extraction workflows for building multi-locale applications using i18next.

---

1. Locales Directory & Namespace Architecture

Organize locale dictionaries logically by language tag and domain namespaces:

public/
└── locales/
    ├── en/
    │   ├── common.json        # Shared UI elements (buttons, navigation, footers)
    │   ├── auth.json          # Authentication forms and error messages
    │   └── dashboard.json     # Dashboard metrics and reports
    ├── ar/                    # Arabic translations
    │   ├── common.json
    │   ├── auth.json
    │   └── dashboard.json
    └── fr/                    # French translations
        ├── common.json
        ├── auth.json
        └── dashboard.json
src/
├── lib/
│   └── i18n.ts                # i18next core client initialization
└── i18next-parser.config.js   # Automated translation extractor config

---

2. i18next Initialization Configuration (src/lib/i18n.ts)

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import HttpApi from 'i18next-http-backend';

export const SUPPORTED_LOCALES = ['en', 'ar', 'fr', 'es'] as const;
export type SupportedLocale = typeof SUPPORTED_LOCALES[number];

i18n
  .use(HttpApi)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: SUPPORTED_LOCALES,
    defaultNS: 'common',
    ns: ['common', 'auth', 'dashboard'],
    
    debug: process.env.NODE_ENV === 'development',
    
    interpolation: {
      escapeValue: false, 
    },
    
    : {
      : ,
    },
    
    : {
      : [, , , ],
      : [],
      :  *  * , 
    },
  });

  i18n;

---

3. Translation Dictionary Files (public/locales/en/auth.json)

Enforce ICU message syntax for plurals, interpolation, and gender/context:

{
  "welcome_user": "Welcome back, {{name}}!",
  "items_count_one": "You have {{count}} item in your cart.",
  "items_count_other": "You have {{count}} items in your cart.",
  "last_login_date": "Last login was on {{val, datetime}}",
  "status_message": "User status is {{context}}"
}

---

4. React Component Usage & Dynamic Switching

import React from 'react';
import { useTranslation } from 'react-i18next';

export const UserWelcomeBanner: React.FC<{ userName: string; cartCount: number }> = ({
  userName,
  cartCount,
}) => {
  const { t, i18n } = useTranslation('auth');

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
    // Update HTML dir attribute for RTL support if needed
    document.documentElement.dir = lng === 'ar' ? 'rtl' : 'ltr';
    document.documentElement.lang = lng;
  };

  return (
    <div className="p-4 rounded-lg bg-slate-100 dark:bg-slate-800">
      <h2 className="text-xl font-bold">{t('welcome_user', { name: userName })}</h2>
      <p>{t('items_count', { count: cartCount })}</>

      
         changeLanguage('en')} className="px-3 py-1 bg-blue-500 text-white rounded">
          English
        
         changeLanguage('ar')} className="px-3 py-1 bg-green-500 text-white rounded">
          العربية
        
      
    
  );
};

---

5. Automated Translation Extraction (i18next-parser.config.js)

Automate extraction of t('key') tokens from TypeScript source code into JSON files:

module.exports = {
  contextSeparator: '_',
  createOldCatalogs: false,
  defaultNamespace: 'common',
  defaultValue: '',
  indentation: 2,
  lexers: {
    ts: ['JsxLexer'],
    tsx: ['JsxLexer'],
    default: ['JsxLexer'],
  },
  locales: ['en', 'ar', 'fr'],
  output: 'public/locales/$LOCALE/$NAMESPACE.json',
  input: ['src/**/*.{ts,tsx}'],
  sort: true,
};

Run extraction via CLI:

npx i18next

---

6. Anti-Patterns & Best Practices

Anti-Pattern	Localization Bug	Production Best Practice
String concatenation (t('welcome') + ' ' + userName)	Fails in languages with different word orders (e.g. Arabic, Japanese).	Use variable interpolation (t('welcome_user', { name: userName })).
Using hardcoded plural logic (count === 1 ? 'item' : 'items')	Fails in languages with complex plural rules (Arabic has 6 plural forms).	Use i18next plural keys (_one, _zero, _two, _few, _many, _other).
Storing all translations in a single monolithic JSON file	Slows initial page load due to large bundle sizes.	Split translations into logical namespaces (common, auth, dashboard).
Hardcoding date, currency, or number formats manually	Violates locale conventions across different countries.	Format dates and numbers using native Intl APIs or i18next formatters.