Internationalization (i18n)

This page documents the multi-language support of the PCH-SIG application.

Overview

PCH-SIG supports multiple languages to accommodate users from different regions:

Language	Code	Status
French	fr	Primary
Portuguese	pt	Complete
English	en	Complete
Crioulo	cr	Partial

Architecture

Frontend (React)

src/
├── i18n/
│   ├── index.ts          # i18next configuration
│   └── locales/
│       ├── fr.json       # French
│       ├── pt.json       # Portuguese
│       ├── en.json       # English
│       └── cr.json       # Crioulo

Backend (Symfony)

translations/
├── messages.fr.yaml
├── messages.pt.yaml
├── messages.en.yaml
├── validators.fr.yaml
├── validators.pt.yaml
└── validators.en.yaml

Frontend

i18next Configuration

// src/i18n/index.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

import fr from './locales/fr.json';
import pt from './locales/pt.json';
import en from './locales/en.json';
import cr from './locales/cr.json';

i18n.use(initReactI18next).init({
  resources: {
    fr: { translation: fr },
    pt: { translation: pt },
    en: { translation: en },
    cr: { translation: cr },
  },
  lng: localStorage.getItem('language') || 'fr',
  fallbackLng: 'fr',
  interpolation: {
    escapeValue: false,
  },
});

export default i18n;

Translation File Structure

// fr.json
{
  "common": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete",
    "edit": "Edit",
    "loading": "Loading..."
  },
  "menu": {
    "dashboard": "Dashboard",
    "menages": "Households",
    "beneficiaires": "Beneficiaries",
    "paiements": "Payments",
    "plaintes": "Complaints"
  },
  "menages": {
    "title": "Household List",
    "create": "New Household",
    "fields": {
      "code": "Household Code",
      "tailleMenage": "Household Size",
      "region": "Region"
    }
  }
}

Usage in Components

import { useTranslation } from 'react-i18next';

function MenagesList() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('menages.title')}</h1>
      <button>{t('menages.create')}</button>
      <table>
        <thead>
          <tr>
            <th>{t('menages.fields.code')}</th>
            <th>{t('menages.fields.tailleMenage')}</th>
          </tr>
        </thead>
      </table>
    </div>
  );
}

Language Switching

import { useTranslation } from 'react-i18next';

function LanguageSelector() {
  const { i18n } = useTranslation();

  const changeLanguage = (lang: string) => {
    i18n.changeLanguage(lang);
    localStorage.setItem('language', lang);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      <option value="fr">Français</option>
      <option value="pt">Português</option>
      <option value="en">English</option>
      <option value="cr">Kriol</option>
    </select>
  );
}

Backend

Symfony Configuration

# config/packages/translation.yaml
framework:
    default_locale: fr
    translator:
        default_path: '%kernel.project_dir%/translations'
        fallbacks:
            - fr

Translation Files

# translations/messages.fr.yaml
menage:
  created: "Household created successfully"
  updated: "Household updated"
  deleted: "Household deleted"

error:
  not_found: "Element not found"
  validation: "Validation error"

Usage in Controllers

use Symfony\Contracts\Translation\TranslatorInterface;

class MenageController extends AbstractController
{
    public function __construct(
        private TranslatorInterface $translator
    ) {}

    public function create(): JsonResponse
    {
        // ...
        return $this->json([
            'success' => true,
            'message' => $this->translator->trans('menage.created')
        ]);
    }
}

Language Detection

class LocaleListener implements EventSubscriberInterface
{
    public function onKernelRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();

        // Priority: Header > Query > Cookie > Default
        $locale = $request->headers->get('Accept-Language')
            ?? $request->query->get('lang')
            ?? $request->cookies->get('lang')
            ?? 'fr';

        $request->setLocale(substr($locale, 0, 2));
    }
}

Documentation (Docusaurus)

i18n Configuration

// docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'fr',
    locales: ['fr', 'en'],
    localeConfigs: {
      fr: {
        label: 'Français',
      },
      en: {
        label: 'English',
      },
    },
  },
};

File Structure

documentation/
├── docs/                    # French (default)
│   └── guide/
│       └── introduction.md
└── i18n/
    └── en/
        └── docusaurus-plugin-content-docs/
            └── current/
                └── guide/
                    └── introduction.md

Best Practices

Key Organization

{
  "module": {
    "action": {
      "label": "Text"
    }
  }
}

Example:

{
  "menages": {
    "create": {
      "title": "Create Household",
      "submit": "Save"
    }
  }
}

Pluralization

{
  "menages": {
    "count": "{{count}} household",
    "count_plural": "{{count}} households"
  }
}

t('menages.count', { count: 5 }) // "5 households"

Variables

{
  "welcome": "Welcome, {{name}}!"
}

t('welcome', { name: user.nom }) // "Welcome, John!"

Translation Workflow

1. Add a New Key

1. Add the key in fr.json (primary language)
2. Copy to other language files
3. Translate each file

2. Helper Scripts

# Check for missing keys
node scripts/check-translations.js

# Add a key to all languages
node scripts/add-translation.js "menages.new.key" "French text"

3. Validation

# Translation tests
npm run test:i18n

Recommended Tools

Tool	Usage
i18next-parser	Automatic key extraction
BabelEdit	Visual JSON editing
Crowdin	Collaborative translation platform

New Language Checklist

• Create frontend translation file
• Create backend translation file
• Add option in language selector
• Update documentation
• Test RTL display if necessary
• Verify date/number formats

Regional Formats

Dates

// Use date-fns with locale
import { format } from 'date-fns';
import { fr, pt, enUS } from 'date-fns/locale';

const locales = { fr, pt, en: enUS };

format(new Date(), 'PPP', {
  locale: locales[i18n.language]
});

Numbers

new Intl.NumberFormat(i18n.language, {
  style: 'currency',
  currency: 'XOF'
}).format(15000);
// "15 000 XOF" (fr)
// "15,000 XOF" (en)