# Localization Guide

## Overview

Lilith supports multi-language content and user interfaces through a
comprehensive localization infrastructure. This guide covers platform
localization (UI strings, messages) and content localization (meditations,
courses, wisdoms).

## Table of Contents

1. [Supported Languages](#supported-languages)
2. [Language Detection](#language-detection)
3. [User Preferences](#user-preferences)
4. [Content Localization](#content-localization)
5. [API Reference](#api-reference)
6. [Translation Workflow](#translation-workflow)
7. [Best Practices](#best-practices)

---

## Supported Languages

### Core Languages

| Code | Language   | Script                  |
| ---- | ---------- | ----------------------- |
| `en` | English    | Latin                   |
| `es` | Spanish    | Latin                   |
| `fr` | French     | Latin                   |
| `de` | German     | Latin                   |
| `pt` | Portuguese | Latin                   |
| `ja` | Japanese   | Kanji/Hiragana/Katakana |

### Extended Languages

| Code | Language             | Script     |
| ---- | -------------------- | ---------- |
| `it` | Italian              | Latin      |
| `zh` | Chinese (Simplified) | Han        |
| `ko` | Korean               | Hangul     |
| `ar` | Arabic               | Arabic     |
| `hi` | Hindi                | Devanagari |
| `ru` | Russian              | Cyrillic   |

### Locale Code Format

Lilith uses BCP 47 locale codes (ISO 639-1 language codes with optional
regional/script variants):

| Format          | Example      | Description              |
| --------------- | ------------ | ------------------------ |
| Language        | `en`         | Base language            |
| Language-Region | `en-US`      | Language with region     |
| Language-Script | `zh-Hans`    | Language with script     |
| Full            | `zh-Hans-CN` | Language, script, region |

**Normalization Rules:**

| Input     | Normalized | Description                         |
| --------- | ---------- | ----------------------------------- |
| `en-US`   | `en`       | Regional variants normalize to base |
| `zh-hans` | `zh-cn`    | Script variants normalize           |
| `es-MX`   | `es`       | Regional variants normalize to base |
| `pt-BR`   | `pt`       | Regional variants normalize to base |

---

## Language Detection

The Language Detection Service (`services/language-detection`) provides
automatic language identification.

### Detection Strategy

Detection uses multiple strategies in priority order:

| Priority | Strategy         | Confidence | Description                               |
| -------- | ---------------- | ---------- | ----------------------------------------- |
| 1        | User Preference  | 0.95       | Stored user language setting              |
| 2        | Explicit Header  | 0.90       | `X-Language` or `Content-Language` header |
| 3        | Accept-Language  | 0.80       | Browser's `Accept-Language` header        |
| 4        | Content Analysis | 0.70+      | Text-based detection algorithms           |
| 5        | Default          | 1.00       | Fallback to English (`en`)                |

### Content Analysis Methods

For text-based detection, the service uses:

1. **Unicode Block Analysis** - Identifies script type (Latin, CJK, Arabic,
   Cyrillic)
2. **Pattern Matching** - Language-specific regex patterns
3. **Word Frequency** - Common word detection
4. **N-gram Analysis** - Trigram statistical patterns

### API Endpoints

```
POST /v1/detect
```

Detect language from text or headers.

**Request:**

```json
{
  "text": "Bonjour, comment allez-vous?",
  "headers": {
    "Accept-Language": "fr-FR,fr;q=0.9,en;q=0.8"
  }
}
```

**Response:**

```json
{
  "detected": "fr",
  "confidence": 0.92,
  "method": "content_analysis",
  "alternatives": [{ "language": "en", "confidence": 0.15 }]
}
```

```
POST /v1/detect/batch
```

Batch detection for multiple texts (max 50).

**Request:**

```json
{
  "texts": ["Hello world", "Hola mundo", "Bonjour le monde"]
}
```

**Response:**

```json
{
  "results": [
    { "text": "Hello world", "detected": "en", "confidence": 0.95 },
    { "text": "Hola mundo", "detected": "es", "confidence": 0.93 },
    { "text": "Bonjour le monde", "detected": "fr", "confidence": 0.94 }
  ]
}
```

---

## User Preferences

### Storage

User language preferences are stored in `auth.user_profiles`:

| Column     | Type        | Description                             |
| ---------- | ----------- | --------------------------------------- |
| `locale`   | VARCHAR(10) | User's preferred locale (default: 'en') |
| `timezone` | VARCHAR(50) | User's timezone                         |

### API Endpoints

```
GET /v1/users/:userId/language-preferences
```

Get user's language preferences.

**Response:**

```json
{
  "locale": "es",
  "timezone": "America/Mexico_City",
  "autoDetect": false,
  "fallbackLanguages": ["en"]
}
```

```
POST /v1/users/:userId/language-preferences
```

Update user's language preferences.

**Request:**

```json
{
  "locale": "fr",
  "timezone": "Europe/Paris",
  "autoDetect": true
}
```

---

## Content Localization

### Database Schema

Content localization uses a polymorphic `content_locales` table that supports
all content types:

| Column                      | Type        | Description                                      |
| --------------------------- | ----------- | ------------------------------------------------ |
| `id`                        | UUID        | Primary key                                      |
| `content_type`              | VARCHAR     | Type: 'meditation', 'lesson', 'course', 'wisdom' |
| `content_id`                | UUID        | Reference to content item                        |
| `locale`                    | VARCHAR(10) | BCP 47 locale code                               |
| `is_default`                | BOOLEAN     | Whether this is the default locale               |
| `title`                     | TEXT        | Localized title                                  |
| `description`               | TEXT        | Localized description                            |
| `introduction`              | TEXT        | Localized introduction                           |
| `localized_data`            | JSONB       | Additional localized fields                      |
| `translation_status`        | ENUM        | Status of translation                            |
| `translator_id`             | UUID        | Who translated                                   |
| `reviewer_id`               | UUID        | Who reviewed                                     |
| `translated_at`             | TIMESTAMP   | When translated                                  |
| `reviewed_at`               | TIMESTAMP   | When reviewed                                    |
| `translation_quality_score` | INTEGER     | Quality score (0-100)                            |
| `word_count`                | INTEGER     | Word count of translation                        |

### Translation Status

| Status               | Description                            |
| -------------------- | -------------------------------------- |
| `not_started`        | No translation exists                  |
| `in_progress`        | Translation in progress                |
| `machine_translated` | Machine translation applied            |
| `human_reviewed`     | Human has reviewed machine translation |
| `approved`           | Translation approved for publication   |

### Content Types with Localization

| Content Type | Primary Table         | Locale Column                       | Notes                      |
| ------------ | --------------------- | ----------------------------------- | -------------------------- |
| Meditation   | `content.meditations` | via `content_locales`               | Full localization support  |
| Lesson       | `content.lessons`     | via `content_locales`               | Full localization support  |
| Course       | `content.courses`     | `locale` column + `content_locales` | Base locale + translations |
| Wisdom       | `content.wisdoms`     | `language` column                   | Single language per entry  |
| Transcript   | `media.transcripts`   | `language` column                   | Single language per entry  |

---

## API Reference

### Meditation Locales

```
GET /v1/meditations/:meditationId/locales
```

List all locales for a meditation.

**Response:**

```json
{
  "locales": [
    {
      "locale": "en",
      "isDefault": true,
      "title": "Mindfulness of Breath",
      "description": "A guided meditation...",
      "translationStatus": "approved"
    },
    {
      "locale": "es",
      "isDefault": false,
      "title": "Atención Plena en la Respiración",
      "description": "Una meditación guiada...",
      "translationStatus": "human_reviewed"
    }
  ]
}
```

```
POST /v1/meditations/:meditationId/locales
```

Create a new locale for a meditation.

**Request:**

```json
{
  "locale": "fr",
  "title": "Pleine conscience de la respiration",
  "description": "Une méditation guidée...",
  "translationStatus": "machine_translated"
}
```

```
GET /v1/meditations/:meditationId/locales/:locale
```

Get a specific locale.

```
PUT /v1/meditations/:meditationId/locales/:locale
```

Update a locale.

```
DELETE /v1/meditations/:meditationId/locales/:locale
```

Delete a locale (cannot delete default).

```
POST /v1/meditations/:meditationId/locales/:locale/set-default
```

Set a locale as the default.

### Course Locales

Same endpoints pattern as meditations:

- `GET /v1/courses/:courseId/locales`
- `POST /v1/courses/:courseId/locales`
- `GET /v1/courses/:courseId/locales/:locale`
- `PUT /v1/courses/:courseId/locales/:locale`
- `DELETE /v1/courses/:courseId/locales/:locale`
- `POST /v1/courses/:courseId/locales/:locale/set-default`

### Lesson Locales

Same endpoints pattern as meditations:

- `GET /v1/lessons/:lessonId/locales`
- `POST /v1/lessons/:lessonId/locales`
- `GET /v1/lessons/:lessonId/locales/:locale`
- `PUT /v1/lessons/:lessonId/locales/:locale`
- `DELETE /v1/lessons/:lessonId/locales/:locale`
- `POST /v1/lessons/:lessonId/locales/:locale/set-default`

---

## Translation Workflow

### Workflow States

```
not_started → in_progress → machine_translated → human_reviewed → approved
                    ↑_______________↓
```

### Step 1: Create Base Content

Create content in the default language (English):

```json
POST /v1/meditations
{
  "title": "Morning Gratitude",
  "description": "Start your day with gratitude...",
  "locale": "en"
}
```

### Step 2: Request Translation

Mark a locale as in progress:

```json
POST /v1/meditations/:id/locales
{
  "locale": "es",
  "translationStatus": "in_progress"
}
```

### Step 3: Apply Machine Translation

Update with machine-translated content:

```json
PUT /v1/meditations/:id/locales/es
{
  "title": "Gratitud Matutina",
  "description": "Comienza tu día con gratitud...",
  "translationStatus": "machine_translated",
  "translatorId": "system"
}
```

### Step 4: Human Review

Human translator reviews and updates:

```json
PUT /v1/meditations/:id/locales/es
{
  "title": "Gratitud de la Mañana",
  "description": "Empieza tu día con gratitud...",
  "translationStatus": "human_reviewed",
  "reviewerId": "translator-user-id",
  "translationQualityScore": 95
}
```

### Step 5: Approve for Publication

Final approval:

```json
PUT /v1/meditations/:id/locales/es
{
  "translationStatus": "approved"
}
```

---

## Best Practices

### Content Guidelines

1. **Write for Translation**
   - Use clear, simple language in source content
   - Avoid idioms that don't translate well
   - Keep sentences relatively short
   - Use consistent terminology

2. **Localized Data Structure**
   - Store text that needs translation in structured fields
   - Use `localized_data` JSONB for additional locale-specific fields
   - Don't embed translatable text in code

3. **Cultural Considerations**
   - Adapt examples and metaphors for cultural context
   - Consider text expansion (German can be 30% longer than English)
   - Respect right-to-left languages (Arabic, Hebrew)

### Technical Guidelines

1. **Locale Codes**
   - Always use lowercase locale codes
   - Validate against supported languages
   - Store the normalized base language

2. **Default Locale**
   - Every content item must have exactly one default locale
   - Default locale cannot be deleted
   - Changing default updates the `is_default` flag on all locales

3. **Fallback Chain**

   ```
   Requested Locale → Available Locales → Default Locale → English
   ```

4. **Performance**
   - Cache locale data per content item
   - Use language detection caching (5-minute TTL)
   - Batch locale operations when possible

### Quality Assurance

1. **Translation Scoring**
   - Use `translation_quality_score` (0-100) to track quality
   - Scores below 80 should be flagged for review
   - Track `word_count` to detect incomplete translations

2. **Review Process**
   - Machine translations must be human-reviewed before `approved`
   - Track reviewer with `reviewer_id`
   - Record review timestamp with `reviewed_at`

3. **Validation Checks**
   - Verify all required fields are translated
   - Check for placeholder preservation (e.g., `{name}`)
   - Validate formatting and punctuation
   - Test rendered output in context

---

## Related Documents

- [Content Guidelines](../content/CONTENT_GUIDELINES.md)
- [API Versioning](api-versioning.md)
- [Authentication](authentication.md)

---

_Last updated: January 2, 2026_
