Translation Algorithm

The GET translations algorithm is the core intelligence behind Langsys that determines the best available translation for each phrase. It considers multiple factors to provide the most accurate and contextually appropriate translation.

How the Algorithm Works

When you request translations using the GET /translations endpoint, the algorithm follows a sophisticated process to find the best translation for each phrase:

1. Project Translation Lookup — first checks for project-specific translations
2. Translation Memory Search — searches the organization’s translation memory
3. Locale Matching — applies locale matching rules to find the best fit
4. Context Consideration — takes into account the context of content blocks
5. Fallback Handling — provides appropriate fallbacks when no translation exists

Translation Sources

1. Project Translations

Project translations are the highest priority source. These are translations that have been specifically created for your project and are stored in the project’s translation database.

• Human translations — translations created by human translators
• Project-specific context — translations tailored to your project’s needs
• Highest priority — always preferred over other sources

2. Translation Memory

Translation memory contains translations from across your organization. It includes:

• Previous translations — translations from other projects in your organization
• Machine translations — AI-generated translations when human translations aren’t available
• Shared knowledge — leverages translations from similar content

Locale Matching Strategy

The algorithm uses a sophisticated locale matching system to find the best available translation:

Exact Match (Highest Priority)

An exact match occurs when a translation exists for the exact locale you’re requesting (e.g., requesting es-ES and finding a translation for es-ES).

• Score: 100 — perfect match
• Priority: Highest — always preferred
• Context: Exact — perfect locale and cultural context

Default Language Match

When no exact match exists, the algorithm looks for translations in the default language for that locale (e.g., requesting es-ES and finding a translation for es).

• Score: 80 — very good match
• Priority: High — good cultural and linguistic fit
• Context: Language-appropriate — correct language, may need regional adjustment

General Language Match

If no default language match exists, the algorithm looks for translations in related languages or fallback languages.

• Score: 60 — acceptable match
• Priority: Medium — may need review
• Context: Language family — related language, may need significant adjustment

Untranslated (Fallback)

When no translation exists, the algorithm returns the original phrase with appropriate metadata.

• Score: 0 — no translation available
• Priority: Lowest — requires translation
• Context: Original — returns the source phrase

Context-Aware Translation

For content blocks, the algorithm considers the context of each phrase within the larger content structure:

Content Block Context

• Phrase relationships — considers how phrases relate to each other
• Structural context — takes into account the HTML structure
• Consistent terminology — ensures consistent translation of related terms

Context Matching

The algorithm prioritizes translations that come from the same content block or similar contexts:

• Same content block — translations from the same content block are preferred
• Similar content — translations from similar content types are considered
• Category matching — translations from the same category are prioritized

Translation Quality Indicators

The algorithm provides quality indicators to help you understand the source and quality of each translation:

Translation Sources

• Human Translation — created by human translators
• Machine Translation — generated by AI translation services
• Translation Memory — retrieved from existing translations
• Project Translation — specific to your project

Quality Scores

• Exact Match (100) — perfect locale and context match
• High Quality (80–99) — very good match with minor adjustments needed
• Medium Quality (60–79) — good match, may need review
• Low Quality (1–59) — acceptable but needs review
• Untranslated (0) — no translation available

Algorithm Flow

1. Phrase Identification — identify all phrases that need translation
2. Project Translation Lookup — search for project-specific translations
3. Exact Locale Match — look for exact locale matches first
4. Default Language Match — look for default language matches
5. Translation Memory Search — search organization’s translation memory
6. Context Consideration — apply context-aware matching rules
7. Quality Assessment — calculate quality scores for each translation
8. Best Match Selection — select the highest quality translation
9. Fallback Handling — provide appropriate fallbacks when needed

Response Format

{
    "data": {
        "welcome-message": {
            "phrase": "Welcome to our app",
            "translation": "Bienvenido a nuestra aplicación",
            "locale": "es",
            "score": 100,
            "source": "human",
            "quality": "exact_match",
            "context": "project"
        }
    },
    "stats": {
        "total_phrases": 100,
        "translated_phrases": 95,
        "untranslated_phrases": 5,
        "machine_translated": 20,
        "human_translated": 75
    }
}

Performance Optimization

Caching Strategy

• Translation caching — frequently accessed translations are cached
• Locale caching — locale-specific translations are cached
• Project caching — project-specific translations are cached

Query Optimization

• Batch processing — multiple phrases are processed in batches
• Efficient lookups — optimized database queries for fast retrieval
• Memory management — efficient memory usage for large translation sets

Best Practices

Translation Management

• Provide human translations — human translations always take priority
• Use consistent terminology — maintain consistent terminology across your content
• Review machine translations — always review AI-generated translations
• Update translations regularly — keep translations up to date

Content Organization

• Use meaningful categories — categorize content for better context matching
• Group related content — use content blocks for related phrases
• Maintain context — keep related phrases together

Error Handling

Fallback Scenarios

• No translation available — returns original phrase with untranslated flag
• Invalid locale — falls back to default language or original phrase
• Database errors — graceful degradation with error logging

Quality Assurance

• Translation validation — validates translation quality and completeness
• Error reporting — reports translation issues and gaps
• Quality metrics — tracks translation quality over time

Next Steps

• API Reference — complete API documentation
• Overview — learn more about Langsys features