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#
- Supported Languages
- Language Detection
- User Preferences
- Content Localization
- API Reference
- Translation Workflow
- 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:
- Unicode Block Analysis - Identifies script type (Latin, CJK, Arabic, Cyrillic)
- Pattern Matching - Language-specific regex patterns
- Word Frequency - Common word detection
- N-gram Analysis - Trigram statistical patterns
API Endpoints#
POST /v1/detect
Detect language from text or headers.
Request:
{
"text": "Bonjour, comment allez-vous?",
"headers": {
"Accept-Language": "fr-FR,fr;q=0.9,en;q=0.8"
}
}
Response:
{
"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:
{
"texts": ["Hello world", "Hola mundo", "Bonjour le monde"]
}
Response:
{
"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:
{
"locale": "es",
"timezone": "America/Mexico_City",
"autoDetect": false,
"fallbackLanguages": ["en"]
}
POST /v1/users/:userId/language-preferences
Update user's language preferences.
Request:
{
"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:
{
"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:
{
"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/localesPOST /v1/courses/:courseId/localesGET /v1/courses/:courseId/locales/:localePUT /v1/courses/:courseId/locales/:localeDELETE /v1/courses/:courseId/locales/:localePOST /v1/courses/:courseId/locales/:locale/set-default
Lesson Locales#
Same endpoints pattern as meditations:
GET /v1/lessons/:lessonId/localesPOST /v1/lessons/:lessonId/localesGET /v1/lessons/:lessonId/locales/:localePUT /v1/lessons/:lessonId/locales/:localeDELETE /v1/lessons/:lessonId/locales/:localePOST /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):
POST /v1/meditations
{
"title": "Morning Gratitude",
"description": "Start your day with gratitude...",
"locale": "en"
}
Step 2: Request Translation#
Mark a locale as in progress:
POST /v1/meditations/:id/locales
{
"locale": "es",
"translationStatus": "in_progress"
}
Step 3: Apply Machine Translation#
Update with machine-translated content:
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:
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:
PUT /v1/meditations/:id/locales/es
{
"translationStatus": "approved"
}
Best Practices#
Content Guidelines#
-
Write for Translation
- Use clear, simple language in source content
- Avoid idioms that don't translate well
- Keep sentences relatively short
- Use consistent terminology
-
Localized Data Structure
- Store text that needs translation in structured fields
- Use
localized_dataJSONB for additional locale-specific fields - Don't embed translatable text in code
-
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#
-
Locale Codes
- Always use lowercase locale codes
- Validate against supported languages
- Store the normalized base language
-
Default Locale
- Every content item must have exactly one default locale
- Default locale cannot be deleted
- Changing default updates the
is_defaultflag on all locales
-
Fallback Chain
textRequested Locale → Available Locales → Default Locale → English -
Performance
- Cache locale data per content item
- Use language detection caching (5-minute TTL)
- Batch locale operations when possible
Quality Assurance#
-
Translation Scoring
- Use
translation_quality_score(0-100) to track quality - Scores below 80 should be flagged for review
- Track
word_countto detect incomplete translations
- Use
-
Review Process
- Machine translations must be human-reviewed before
approved - Track reviewer with
reviewer_id - Record review timestamp with
reviewed_at
- Machine translations must be human-reviewed before
-
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#
Last updated: January 2, 2026