Phase 2: Multi-Language Support with Translation.io

[kevalyq]

🌍 Goal

Integrate Translation.io with Lingui to provide seamless multi-language support in the SecPal frontend, enabling users to interact with the application in their preferred language.

---

📋 Tasks

1. Install Dependencies

npm install --save @lingui/react
npm install --save-dev @lingui/cli
npm install --save-dev @lingui/babel-plugin-lingui-macro

2. Configure Lingui

Create .linguirc (WITHOUT hardcoded API key):

{
  "locales": ["en", "de"],
  "sourceLocale": "en",
  "catalogs": [{
    "path": "src/locales/{locale}/messages",
    "include": ["src"]
  }],
  "format": "po",
  "service": {
    "name": "TranslationIO"
  }
}

3. Secure API Key Management

⚠️ IMPORTANT: DO NOT commit API key to repository!

The Translation.io API key can be found in the Translation.io project settings or contact the project admin.

Option A: Environment Variable (Recommended)

# .env.local (git-ignored)
VITE_TRANSLATION_IO_API_KEY=your_api_key_here

# Use in sync command:
TRANSLATION_IO_API_KEY=$VITE_TRANSLATION_IO_API_KEY npm run sync

Option B: .linguirc.local (git-ignored)

{
  "service": {
    "name": "TranslationIO",
    "apiKey": "your_api_key_here"
  }
}

Update .gitignore:

.env.local
.linguirc.local

4. Package.json Scripts

{
  "scripts": {
    "sync": "lingui extract --overwrite && lingui compile",
    "sync_and_purge": "lingui extract --overwrite --clean && lingui compile"
  }
}

5. Setup Lingui Provider

Update src/main.tsx:

import { i18n } from '@lingui/core';
import { I18nProvider } from '@lingui/react';
import { messages as enMessages } from './locales/en/messages';
import { messages as deMessages } from './locales/de/messages';

i18n.load({
  en: enMessages,
  de: deMessages,
});

const locale = navigator.language.split('-')[0] || 'en';
i18n.activate(locale);

createRoot(rootElement).render(
  <StrictMode>
    <I18nProvider i18n={i18n}>
      <App />
    </I18nProvider>
  </StrictMode>
);

6. Create Language Switcher Component

// src/components/LanguageSwitcher.tsx
import { useLingui } from '@lingui/react';

export function LanguageSwitcher() {
  const { i18n } = useLingui();
  
  return (
    <select 
      value={i18n.locale} 
      onChange={(e) => i18n.activate(e.target.value)}
    >
      <option value="en">English</option>
      <option value="de">Deutsch</option>
    </select>
  );
}

7. Localize Components

Replace hardcoded strings with Lingui macros:

import { Trans, t } from '@lingui/macro';

// JSX:
<h1><Trans>SecPal - a guard's best friend</Trans></h1>

// Attributes:
<input placeholder={t`Enter your name`} />

8. Extract and Sync Translations

npm run sync

This will:

• Extract translatable strings
• Upload to Translation.io
• Download existing translations

9. Testing

• Language detection works correctly
• Language switcher changes UI language
• All strings are properly translated
• Language preference persists across sessions
• RTL support if needed

---

🔒 Security Considerations

1. ✅ API key stored in environment variable or git-ignored file
2. ✅ .gitignore updated to exclude sensitive files
3. ✅ CI/CD configured with secret environment variables
4. ✅ Documentation for developers on obtaining API key

---

📚 Documentation

For Developers

• Contact project admin for Translation.io API key
• Setup instructions in README
• Environment variable requirements

For Translators

• Guide on using Translation.io interface
• Context for translatable strings
• Translation workflow

---

🔗 Related

• Epic: Epic: Progressive Web App Infrastructure #64 (Progressive Web App Infrastructure)
• Previous Phase: Phase 1: PWA Offline-First Foundation #65 (Phase 1 - PWA Foundation)
• API Multi-Language: PR-2: Frontend Translation.io Integration & i18n Setup api#85
• Translation.io Project: https://translation.io/secpal/frontend

---

✅ Acceptance Criteria

• Lingui configured with Translation.io integration
• API key managed securely (not in git)
• Language switcher component implemented
• All UI strings use Lingui macros
• Initial translations complete (English, German)
• Language preference persists
• Tests passing for language switching
• Documentation complete

---

Type: Sub-Issue of Epic #64
Priority: High
Estimated Effort: 3-5 days
Dependencies: Phase 1 ✅ Complete

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.