Context Awareness

Overview

Context awareness is a key differentiator of AI Translations for Laravel. Unlike simple key-by-key translation tools, this package provides the LLM with complete context about your entire translation file, enabling consistent terminology, appropriate tone, and contextual accuracy.

Why Context Matters

Consider translating the English word “Cancel” to German:

// Simple translation: just the word
'button.cancel' => 'Abbrechen'

// But what if your app uses different terms?
'dialog.cancel' => 'Abbrechen'  // Inconsistent with...
'form.cancel' => 'Verwerfen'     // ...existing usage

Context awareness ensures your translations feel cohesive, as if written by a single translator familiar with your entire application.

Full File Context Strategy

The package sends both complete source and target files to the LLM, even when translating just a few missing keys.

Implementation

// TranslationAgent.php:143-156
$message = ($retry || $index > 0) 
    ? new UserMessage($prompt)  // Subsequent chunks: minimal prompt
    : new UserMessage(<<<PROMPT  // First chunk: full context
    <{$this->from->language}-file>
    {$this->from->toJson()}
    </{$this->from->language}-file>

    <{$this->to->language}-file>
    {$this->to->toJson()}
    </{$this->to->language}-file>

    {$prompt}
    PROMPT);

What the LLM Receives

Source File (from)
Target File (to)
Missing Keys
System Instructions

The complete source language file in JSON format:

{
  "auth.failed": "These credentials do not match our records.",
  "auth.password": "The provided password is incorrect.",
  "auth.throttle": "Too many login attempts. Please try again in {seconds} seconds.",
  "validation.required": "The {attribute} field is required.",
  "validation.email": "The {attribute} must be a valid email address.",
  "validation.max.string": "The {attribute} must not be greater than {max} characters."
  // ... all other keys
}

Purpose: Shows the LLM what needs to be translated and provides context about the application domain.

The existing target language file in JSON format:

{
  "auth.failed": "Diese Zugangsdaten sind nicht korrekt.",
  "auth.password": "Das angegebene Passwort ist falsch.",
  "validation.required": "Das Feld {attribute} ist erforderlich.",
  "validation.email": "Das Feld {attribute} muss eine gültige E-Mail-Adresse sein."
  // ... existing translations (may be incomplete)
}

Purpose: Provides translation style, terminology choices, and tone that should be maintained.

The specific keys that need translation:

auth.throttle
validation.max.string

Purpose: Tells the LLM exactly which keys to translate in this chunk.

Detailed instructions about the translation task:

You are a real estate software translator.
You translate Laravel language files from en to de.

Try to reuse the old translations or adapt your new 
translations with the existing ones as context. 
We don't want to change existing UI around too much.

Purpose: Guides the LLM’s translation approach and emphasizes consistency.

How Context Maintains Consistency

The LLM uses the full file context to make informed decisions across multiple dimensions:

1. Terminology Consistency

The LLM learns your application’s specific vocabulary:

Technical Terms

Scenario: Your app uses “Workspace” instead of “Project”

// Source (en)
{
  "workspace.create": "Create Workspace",
  "workspace.delete": "Delete Workspace",
  "workspace.settings": "Workspace Settings"
  // New key to translate:
  "workspace.invite": "Invite to Workspace"
}

Without context: Might translate as “Einladen zum Projekt” (Project)With context: Translates as “Zum Arbeitsbereich einladen” (Workspace)The LLM sees you consistently use “Workspace” and maintains that terminology.

Domain-Specific Language

Scenario: Real estate application with specific terms

// Existing translations show domain
{
  "property.list": "Immobilien auflisten",
  "property.details": "Immobiliendetails",
  "agent.profile": "Maklerprofil"
  // New translation maintains domain:
  "property.featured": "Hervorgehobene Immobilien"
}

The LLM understands it’s a real estate context and uses appropriate terminology like “Immobilien” (properties) and “Makler” (agent) rather than generic alternatives.

Brand-Specific Terms

Scenario: Your brand uses specific capitalization or terminology

{
  "feature.smartMatch": "SmartMatch enabled",
  "feature.smartMatchDesc": "SmartMatch finds..."
  // New key preserves brand term:
  "feature.smartMatchSettings": "SmartMatch Settings"
}

The LLM recognizes “SmartMatch” is a proper noun and doesn’t translate it, maintaining brand consistency.

2. Tone and Formality

Translations maintain consistent formality levels:

// Formal tone (German "Sie" form)
{
  "welcome.greeting": "Willkommen! Bitte melden Sie sich an.",
  "profile.update": "Aktualisieren Sie Ihr Profil"
  // New translation matches formality:
  "account.verify": "Verifizieren Sie Ihr Konto"  // Uses "Sie"
}

// vs. Informal tone (German "du" form)
{
  "welcome.greeting": "Willkommen! Bitte melde dich an.",
  "profile.update": "Aktualisiere dein Profil"
  // New translation matches informality:
  "account.verify": "Verifiziere dein Konto"  // Uses "du"
}

The system instructions explicitly tell the LLM to “try to reuse the old translations or adapt your new translations with the existing ones as context” (TranslationAgent.php:60-61).

3. Placeholder Handling

The LLM learns how your translations handle Laravel’s placeholders:

// Existing pattern:
{
  "validation.required": "The {attribute} field is required.",
  "validation.min.string": "The {attribute} must be at least {min} characters."
}

// LLM maintains pattern in German:
{
  "validation.required": "Das Feld {attribute} ist erforderlich.",
  "validation.min.string": "Das Feld {attribute} muss mindestens {min} Zeichen lang sein.",
  // New translation follows same pattern:
  "validation.max.string": "Das Feld {attribute} darf maximal {max} Zeichen lang sein."
}

Key observations:

Placeholders like {attribute}, {min}, {max} are never translated
Sentence structure adapts to target language while preserving placeholders
Consistent phrasing (“Das Feld …”) across validation messages

4. Punctuation and Formatting

Style choices like punctuation are maintained:

// Source file uses periods:
{
  "success.saved": "Changes saved successfully.",
  "success.deleted": "Item deleted successfully."
}

// Target maintains periods:
{
  "success.saved": "Änderungen erfolgreich gespeichert.",
  "success.deleted": "Element erfolgreich gelöscht.",
  "success.updated": "Erfolgreich aktualisiert."  // New: also has period
}

Context Preservation Across Chunks

When translating large files, context is maintained throughout the chunking process:

// TranslationAgent.php:143-156
$message = ($retry || $index > 0) 
    ? new UserMessage($prompt)
    : new UserMessage(<<<PROMPT
    <{$this->from->language}-file>
    {$this->from->toJson()}
    </{$this->from->language}-file>

    <{$this->to->language}-file>
    {$this->to->toJson()}
    </{$this->to->language}-file>

    {$prompt}
    PROMPT);

First Chunk

Receives complete source and target files, establishing full context.

Subsequent Chunks

Continue the conversation without resending files. The LLM’s context window retains the full file contents from the first message.

Consistency Maintained

Even though later chunks don’t explicitly include the files, the LLM remembers the context and maintains consistency.

This approach optimizes token usage while preserving context quality. The full files are sent once, not repeatedly for each chunk.

Context-Aware Instructions

The system prompt provides explicit guidance on using context:

// TranslationAgent.php:50-72 (simplified)
You are given the contents of the original {$from->language} file, 
and contents of the {$to->language} file if it exists already and 
is outdated.

If a file is passed, try to reuse the old translations or to adapt 
your new translations with the existing ones as context. We don't 
want to change existing UI around too much.

Key directives:

Reuse Translations

Leverage existing translations to understand terminology preferences and style.

Adapt New Content

Make new translations feel like they belong to the existing set.

Minimize UI Changes

Consistency prevents user confusion from varying translation styles.

Complete Context

Full source and target files provide comprehensive understanding.

Real-World Context Benefits

Here’s how context awareness improves real translations:

Example 1: Validation Messages

Without Context
With Context

Problem: Inconsistent phrasing across validation messages

{
  "required": "Dieses Feld ist erforderlich",
  "email": "E-Mail muss gültig sein",
  "min": "Mindestens {min} Zeichen",
  "max": "{max} Zeichen Maximum"  // Inconsistent style!
}

Each key translated independently results in varying sentence structures.

Solution: Consistent phrasing pattern maintained

{
  "required": "Das Feld {attribute} ist erforderlich",
  "email": "Das Feld {attribute} muss eine gültige E-Mail sein",
  "min": "Das Feld {attribute} muss mindestens {min} Zeichen haben",
  "max": "Das Feld {attribute} darf maximal {max} Zeichen haben"
}

The LLM recognizes the pattern “Das Feld …” and maintains it.

Example 2: Button Labels

Without Context
With Context

Problem: Mixed verb forms and styles

{
  "save": "Speichern",        // Infinitive
  "delete": "Gelöscht",       // Past participle  
  "cancel": "Abbruch",        // Noun
  "submit": "Senden"          // Infinitive
}

Solution: Consistent infinitive form

{
  "save": "Speichern",
  "delete": "Löschen",
  "cancel": "Abbrechen",
  "submit": "Senden"
}

All buttons use infinitive verb form, matching UI convention.

Example 3: Error Messages

Without Context
With Context

Problem: Inconsistent tone (formal vs informal)

{
  "unauthorized": "Sie sind nicht berechtigt",     // Formal (Sie)
  "forbidden": "Du darfst das nicht",              // Informal (du)
  "not_found": "Die Seite wurde nicht gefunden"   // Neutral
}

Solution: Uniform formality level

{
  "unauthorized": "Sie sind nicht berechtigt",
  "forbidden": "Sie haben keine Zugriffsberechtigung",
  "not_found": "Die Seite wurde nicht gefunden"
}

Consistent formal address (“Sie”) throughout the application.

Optimizing for Context Quality

Keep Source Language High Quality

Your source language directly affects translation quality:

Clear

Good: “The password field is required”Bad: “pwd req”Clear source text produces clear translations.

Consistent

Good: Always use “Workspace” (not “Project” sometimes)Consistency in source ensures consistency in translations.

Complete

Good: Full sentences with proper grammarBad: Fragments or abbreviationsComplete source helps LLM understand context.

Contextual

Good: “validation.required”: “The field is required”Bad: “required”: “Required”Descriptive keys and complete sentences provide better context.

Organize your language files logically:

// Good: Related translations in same file
lang/en/auth.php        // All authentication messages
lang/en/validation.php  // All validation messages  
lang/en/admin.php       // All admin interface text

// The LLM gets better context when related translations are together

When the LLM translates validation.php, all validation messages are in context, enabling it to maintain consistent phrasing patterns across all validation errors.

Limitations and Considerations

Context Window Limits

Very large translation files (1000+ keys) may exceed LLM context windows.Solution: The chunking strategy keeps each request manageable, and conversation context maintains consistency across chunks.

First Translation Quality

When translating to a completely new language, there’s no existing target file to provide translation style context.Solution: Use the standard (non-fast) model for first translations to new languages. The source file context is still valuable.

Conflicting Existing Translations

If your existing translations are inconsistent, the LLM might perpetuate those inconsistencies.Solution: Clean up your source and primary target language files before translating to additional languages.

Best Practices

Maintain Quality Source Files

Keep your primary language (usually English) complete, clear, and consistent. It’s the foundation for all translations.

Translate Incrementally

When adding features, translate to your primary target languages first, then use those as reference for additional languages.

Review First Translation

For the first translation to a new language, carefully review output to establish quality baseline.

Use Standard Models for New Languages

Don’t use --fast when translating to a completely new language - context quality matters most.

Group Related Content

Organize translations logically (auth, validation, admin, etc.) so related content shares context.

Context awareness is most effective when your source language files are well-organized and consistently written. Invest time in your primary language, and translations to all other languages will benefit.

Get Started

Configuration

Usage

Core Concepts

Examples

Overview

Why Context Matters

Full File Context Strategy

Implementation

What the LLM Receives

How Context Maintains Consistency

1. Terminology Consistency

2. Tone and Formality

3. Placeholder Handling

4. Punctuation and Formatting

Context Preservation Across Chunks

Context-Aware Instructions

Reuse Translations

Adapt New Content

Minimize UI Changes

Complete Context

Real-World Context Benefits

Example 1: Validation Messages

Example 2: Button Labels

Example 3: Error Messages

Optimizing for Context Quality

Keep Source Language High Quality

Clear

Consistent

Complete

Contextual

Limitations and Considerations

Best Practices

Build docs developers (and LLMs) love

Get Started

Configuration

Usage

Core Concepts

Examples

​Overview

​Why Context Matters

​Full File Context Strategy

​Implementation

​What the LLM Receives

​How Context Maintains Consistency

​1. Terminology Consistency

​2. Tone and Formality

​3. Placeholder Handling

​4. Punctuation and Formatting

​Context Preservation Across Chunks

​Context-Aware Instructions

Reuse Translations

Adapt New Content

Minimize UI Changes

Complete Context

​Real-World Context Benefits

​Example 1: Validation Messages

​Example 2: Button Labels

​Example 3: Error Messages

​Optimizing for Context Quality

​Keep Source Language High Quality

Clear

Consistent

Complete

Contextual

​Group Related Translations

​Limitations and Considerations

​Best Practices

Build docs developers (and LLMs) love

Overview

Why Context Matters

Full File Context Strategy

Implementation

What the LLM Receives

How Context Maintains Consistency

1. Terminology Consistency

2. Tone and Formality

3. Placeholder Handling

4. Punctuation and Formatting

Context Preservation Across Chunks

Context-Aware Instructions

Real-World Context Benefits

Example 1: Validation Messages

Example 2: Button Labels

Example 3: Error Messages

Optimizing for Context Quality

Keep Source Language High Quality

Group Related Translations

Limitations and Considerations

Best Practices