Localization (i18n)

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

// Import translation files
import translationEn from './en/translation.json';
import translationEs from './es/translation.json';
import translationFr from './fr/translation.json';
// ... 40+ more languages

export const defaultNS = 'translation';

export const resources = {
  en: { translation: translationEn },
  es: { translation: translationEs },
  fr: { translation: translationFr },
  'zh-Hans': { translation: translationZh_Hans },
  'zh-Hant': { translation: translationZh_Hant },
  // ... more languages
} as const;

i18n
  .use(LanguageDetector)        // Detect user language
  .use(initReactI18next)         // React integration
  .init({
    fallbackLng: {
      'zh-TW': ['zh-Hant', 'en'],
      'zh-HK': ['zh-Hant', 'en'],
      zh: ['zh-Hans', 'en'],
      default: ['en'],
    },
    fallbackNS: 'translation',
    ns: ['translation'],
    debug: false,
    defaultNS,
    resources,
    interpolation: { escapeValue: false },  // React handles XSS
  });

export default i18n;

import { useEffect } from 'react';
import { TOptions } from 'i18next';
import { useRecoilValue } from 'recoil';
import { useTranslation } from 'react-i18next';
import { resources } from '~/locales/i18n';
import store from '~/store';

export type TranslationKeys = keyof typeof resources.en.translation;

export default function useLocalize() {
  const lang = useRecoilValue(store.lang);
  const { t, i18n } = useTranslation();

  useEffect(() => {
    if (i18n.language !== lang) {
      i18n.changeLanguage(lang);
    }
  }, [lang, i18n]);

  return (phraseKey: TranslationKeys, options?: TOptions) => t(phraseKey, options);
}

import { useLocalize } from '~/hooks';

function MyComponent() {
  const localize = useLocalize();

  return (
    <div>
      <h1>{localize('com_ui_welcome')}</h1>
      <button>{localize('com_ui_save')}</button>
      <p>{localize('com_ui_error_message')}</p>
    </div>
  );
}

const localize = useLocalize();

// Simple interpolation
<span>
  {localize('com_ui_by_author', { 0: displayName })}
</span>

// Multiple variables
<div aria-label={localize('com_agents_agent_card_label', {
  name: agent.name,
  description: agent.description ?? '',
})}>

{
  "com_ui_by_author": "by {{0}}",
  "com_agents_agent_card_label": "{{name}} agent. {{description}}"
}

// Component
const tokenCount = 5;
const key = tokenCount === 1 ? 'com_ui_token' : 'com_ui_tokens';

<span>{tokenCount} {localize(key)}</span>

{
  "com_ui_token": "token",
  "com_ui_tokens": "tokens"
}

{
  "com_ui_token_count": "{{count}} token",
  "com_ui_token_count_plural": "{{count}} tokens"
}

localize('com_ui_token_count', { count: tokenCount })

com_ui_*          - General UI elements
com_agents_*      - Agent-related features
com_assistants_*  - Assistant features
com_auth_*        - Authentication
com_nav_*         - Navigation
com_endpoint_*    - Model endpoints
com_files_*       - File management
com_error_*       - Error messages
com_a11y_*        - Accessibility announcements

{
  "com_ui_save": "Save",
  "com_ui_cancel": "Cancel",
  "com_ui_delete": "Delete",
  "com_ui_loading": "Loading...",
  
  "com_agents_marketplace": "Agent Marketplace",
  "com_agents_create_error": "There was an error creating your agent.",
  "com_agents_search_placeholder": "Search agents...",
  
  "com_error_network_title": "Connection Problem",
  "com_error_network_message": "Unable to connect to the server.",
  "com_error_retry": "Try Again",
  
  "com_a11y_ai_composing": "The AI is still composing.",
  "com_a11y_end": "The AI has finished their reply."
}

// Good: Semantic, descriptive keys
com_agents_marketplace_subtitle
com_agents_error_loading
com_ui_by_author

// Bad: Generic or unclear
text1
error
message
author_name

{
  // ... existing keys
  "com_agents_new_feature_title": "New Feature",
  "com_agents_new_feature_description": "This is a new feature for agents.",
  "com_agents_action_label": "Perform action with {{name}}"
}

import { useLocalize } from '~/hooks';

function NewFeature({ agent }: Props) {
  const localize = useLocalize();

  return (
    <div>
      <h2>{localize('com_agents_new_feature_title')}</h2>
      <p>{localize('com_agents_new_feature_description')}</p>
      <button aria-label={localize('com_agents_action_label', { name: agent.name })}>
        {localize('com_ui_continue')}
      </button>
    </div>
  );
}

<div
  aria-label={localize('com_agents_agent_card_label', {
    name: agent.name,
    description: agent.description ?? '',
  })}
  aria-describedby={agent.description ? `agent-${agent.id}-description` : undefined}
>
  <Label>{agent.name}</Label>
  {agent.description && (
    <p
      id={`agent-${agent.id}-description`}
      aria-label={localize('com_agents_description_card', {
        description: agent.description,
      })}
    >
      {agent.description}
    </p>
  )}
</div>

{
  "com_a11y_ai_composing": "The AI is still composing.",
  "com_a11y_start": "The AI has started their reply.",
  "com_a11y_end": "The AI has finished their reply.",
  "com_agents_search_aria": "Search for agents",
  "com_agents_load_more_label": "Load more agents from {{category}} category"
}

import { atom } from 'jotai';
import { atomWithStorage } from 'jotai/utils';

export const languageAtom = atomWithStorage<string>('language', 'en', undefined, {
  getOnInit: true,
});

import { useAtom } from 'jotai';
import { languageAtom } from '~/store';

function LanguageSwitcher() {
  const [language, setLanguage] = useAtom(languageAtom);

  const languages = [
    { code: 'en', name: 'English' },
    { code: 'es', name: 'Español' },
    { code: 'fr', name: 'Français' },
    { code: 'zh-Hans', name: '简体中文' },
    // ... more languages
  ];

  return (
    <select value={language} onChange={(e) => setLanguage(e.target.value)}>
      {languages.map((lang) => (
        <option key={lang.code} value={lang.code}>
          {lang.name}
        </option>
      ))}
    </select>
  );
}

fallbackLng: {
  'zh-TW': ['zh-Hant', 'en'],
  'zh-HK': ['zh-Hant', 'en'],
  zh: ['zh-Hans', 'en'],
  default: ['en'],
},

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { i18n } = useTranslation();
  const isRTL = i18n.dir() === 'rtl';

  return (
    <div dir={i18n.dir()} className={isRTL ? 'rtl-layout' : 'ltr-layout'}>
      {/* Component content */}
    </div>
  );
}

const statusKey = isActive 
  ? 'com_ui_status_active' 
  : 'com_ui_status_inactive';

<span>{localize(statusKey)}</span>

const categories = [
  { value: 'general', label: localize('com_agents_category_general') },
  { value: 'finance', label: localize('com_agents_category_finance') },
  { value: 'it', label: localize('com_agents_category_it') },
];

// Translation keys follow a pattern
const categoryKey = `com_agents_category_${category}` as TranslationKeys;
const categoryLabel = localize(categoryKey);

// With fallback
const categoryLabel = category.startsWith('com_') 
  ? localize(category as TranslationKeys)
  : category;  // Use raw value if not a translation key

const categoryLabel = useMemo(() => {
  if (!agent.category) return '';

  const category = categories.find((cat) => cat.value === agent.category);
  if (category) {
    if (category.label && category.label.startsWith('com_')) {
      return localize(category.label as TranslationKeys);
    }
    return category.label;
  }

  return agent.category.charAt(0).toUpperCase() + agent.category.slice(1);
}, [agent.category, categories, localize]);

// TypeScript will error if key doesn't exist
localize('com_nonexistent_key');  // ❌ Type error
localize('com_ui_save');           // ✅ Valid

import { render } from '@testing-library/react';
import { I18nextProvider } from 'react-i18next';
import i18n from '~/locales/i18n';

describe('MyComponent', () => {
  it('should render in Spanish', async () => {
    await i18n.changeLanguage('es');
    
    const { getByText } = render(
      <I18nextProvider i18n={i18n}>
        <MyComponent />
      </I18nextProvider>
    );
    
    expect(getByText('Guardar')).toBeInTheDocument();  // Spanish for "Save"
  });
});