biblical-guide.com/temp/multi-language-implementation-plan.md

Multi-Language Support Implementation Plan

Overview

Add comprehensive multi-language support to the Ghid Biblic application, starting with English as the second language alongside Romanian.

Current State

• Database: Already supports multiple languages (lang field) and translations (translation field)
• Frontend: Hardcoded Romanian interface
• Vector Search: Romanian-only search logic
• Bible Data: Only Romanian (FIDELA) version imported

Implementation Phases

Phase 1: Core Infrastructure

1. Install i18n Framework

   • Add next-intl for Next.js internationalization
   • Configure locale routing (/ro/, /en/)
   • Set up translation file structure

2. Language Configuration

   • Create language detection and switching logic
   • Add language persistence (localStorage/cookies)
   • Configure default language fallbacks

3. Translation Files Structure

   messages/
   ├── ro.json (Romanian - existing content)
   ├── en.json (English translations)
   └── common.json (shared terms)
   

Phase 2: UI Internationalization

1. Navigation Component

   • Translate all menu items and labels
   • Add language switcher dropdown
   • Update routing for locale-aware navigation

2. Chat Interface

   • Translate all UI text and prompts
   • Add suggested questions per language
   • Update loading states and error messages

3. Page Content

   • Home page (/ → /[locale]/)
   • Bible browser (/bible → /[locale]/bible)
   • Search page (/search → /[locale]/search)
   • Prayer requests (/prayers → /[locale]/prayers)

Phase 3: Backend Localization

1. Vector Search Updates

   • Modify search functions to filter by language
   • Add language parameter to search APIs
   • Update hybrid search for language-specific full-text search

2. Chat API Enhancement

   • Language-aware Bible verse retrieval
   • Localized AI response prompts
   • Language-specific fallback responses

3. API Route Updates

   • Add locale parameter to all API endpoints
   • Update error responses for each language
   • Configure language-specific search configurations

Phase 4: Bible Data Management

1. English Bible Import

   • Source: API.Bible or public domain English Bible (KJV/ESV)
   • Adapt existing import script for English
   • Generate English embeddings using Azure OpenAI

2. Language-Aware Bible Browser

   • Add language selector in Bible interface
   • Filter books/chapters/verses by selected language
   • Show parallel verses when both languages available

Phase 5: Enhanced Features

1. Parallel Bible View

   • Side-by-side Romanian/English verse display
   • Cross-reference linking between translations
   • Language comparison in search results

2. Smart Language Detection

   • Auto-detect query language in chat
   • Suggest language switch based on user input
   • Mixed-language search capabilities

3. Advanced Search Features

   • Cross-language semantic search
   • Translation comparison tools
   • Language-specific biblical term glossaries

Technical Implementation Details

Routing Structure

Current: /page
New:     /[locale]/page

Examples:
- /ro/biblia (Romanian Bible)
- /en/bible (English Bible)
- /ro/rugaciuni (Romanian Prayers)
- /en/prayers (English Prayers)

Database Schema Changes

No changes needed - current schema already supports:

• Multiple languages via lang field
• Multiple translations via translation field
• Unique constraints per translation/language

Vector Search Updates

// Current
searchBibleHybrid(query: string, limit: number)

// Enhanced
searchBibleHybrid(query: string, language: string, limit: number)

Translation File Structure

// messages/en.json
{
  "navigation": {
    "home": "Home",
    "bible": "Bible",
    "prayers": "Prayers",
    "search": "Search"
  },
  "chat": {
    "placeholder": "Ask your biblical question...",
    "suggestions": [
      "What does the Bible say about love?",
      "Explain the parable of the sower",
      "What are the fruits of the Spirit?"
    ]
  }
}

Language Switcher Component

• Dropdown in navigation header
• Flag icons for visual identification
• Persist language choice across sessions
• Redirect to equivalent page in new language

Dependencies to Add

{
  "next-intl": "^3.x",
  "@formatjs/intl-localematcher": "^0.x",
  "negotiator": "^0.x"
}

File Structure Changes

app/
├── [locale]/
│   ├── page.tsx
│   ├── bible/
│   ├── prayers/
│   ├── search/
│   └── layout.tsx
├── api/ (unchanged)
└── globals.css

messages/
├── en.json
├── ro.json
└── index.ts

components/
├── language-switcher.tsx
├── navigation.tsx (updated)
└── chat/ (updated)

Testing Strategy

1. Unit Tests: Translation loading and language switching
2. Integration Tests: API endpoints with locale parameters
3. E2E Tests: Complete user flows in both languages
4. Performance Tests: Vector search with language filtering

Rollout Plan

1. Development: Implement Phase 1-3 (core infrastructure and UI)
2. Testing: Deploy to staging with Romanian/English support
3. Beta Release: Limited user testing with feedback collection
4. Production: Full release with both languages
5. Future: Add additional languages based on user demand

Estimated Timeline

• Phase 1-2: 2-3 days (i18n setup and UI translation)
• Phase 3: 1-2 days (backend localization)
• Phase 4: 2-3 days (English Bible import and embeddings)
• Phase 5: 3-4 days (enhanced features)
• Total: 8-12 days for complete implementation

Success Metrics

• Language switching works seamlessly
• Vector search returns accurate results in both languages
• AI chat responses are contextually appropriate per language
• User can browse Bible in preferred language
• Performance remains optimal with language filtering

Future Considerations

• Spanish, French, German language support
• Regional dialect variations
• Audio Bible integration per language
• Collaborative translation features for community contributions