Eve library

Localization Guide

Guide

Revision 1

On this page

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
  2. Language Detection
  3. User Preferences
  4. Content Localization
  5. API Reference
  6. Translation Workflow
  7. 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#

text
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 }]
}
text
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#

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

Get user's language preferences.

Response:

json
{
  "locale": "es",
  "timezone": "America/Mexico_City",
  "autoDetect": false,
  "fallbackLanguages": ["en"]
}
text
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#

text
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"
    }
  ]
}
text
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"
}
text
GET /v1/meditations/:meditationId/locales/:locale

Get a specific locale.

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

Update a locale.

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

Delete a locale (cannot delete default).

text
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#

text
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

    text
    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


Last updated: January 2, 2026