Translation Context: Why It Matters and How to Provide It

Why Translation Context Matters

Translation context is the difference between a professional, native-feeling localization and an awkward, confusing user experience. The same English word can have multiple meanings depending on context—"Open" could be a verb (open a file), an adjective (store is open), or a noun (golf open tournament)—and translators need to know which meaning you intend. Without context, translators make assumptions that often prove wrong, resulting in translations that are technically correct but contextually inappropriate. A button labeled "Close" might translate to "cerrar" (close a door/window) instead of "finalizar" (close/complete a task) in Spanish, or "schließen" (close) instead of "beenden" (finish) in German. Context encompasses screenshots showing where text appears, character limits preventing overflow, descriptions explaining functionality, placeholder examples clarifying variable formats, and tone guidelines ensuring brand consistency. Providing context upfront reduces translation time, eliminates costly revision cycles, and dramatically improves quality. Studies show context-aware translations require 40% fewer revisions and achieve 60% higher quality scores than context-free translations. IntlPull's screenshot and OCR features automate context capture, making it effortless for developers to provide translators with the visual and textual context they need.

Types of Context That Matter

Visual Context: Screenshots

Screenshots provide immediate understanding of where and how text appears:

TypeScriptCopy
1// Instead of translating this blind:
2{
3  "nav.home": "Home",
4  "nav.settings": "Settings"
5}
6
7// Translators see a screenshot showing:
8// - Navigation bar position
9// - Available space (affects translation length)
10// - Visual hierarchy
11// - Surrounding UI elements

What screenshots should show:

• Exact UI location
• Available space constraints
• Text formatting (bold, italic, size)
• Proximity to other UI elements
• Device/platform context (mobile vs desktop)

Character Limit Context

Some UI areas have strict space constraints:

JSONCopy
1{
2  "button.submit": {
3    "message": "Submit",
4    "maxLength": 15,
5    "context": "Primary action button (mobile)"
6  },
7  "notification.title": {
8    "message": "New message received",
9    "maxLength": 50,
10    "context": "Push notification title (truncates with ...)"
11  }
12}

Descriptive Context

Explain what the text does and when users see it:

JSONCopy
1{
2  "error.network": {
3    "message": "Connection failed",
4    "context": "Error shown when user loses internet connection during form submission"
5  },
6  "status.pending": {
7    "message": "Pending",
8    "context": "Order status label shown after payment but before processing"
9  }
10}

Placeholder Context

Clarify variable formats and examples:

JSONCopy
1{
2  "greeting": {
3    "message": "Welcome back, {userName}!",
4    "context": "{userName} is the user's first name. Example: 'Welcome back, Sarah!'",
5    "placeholders": {
6      "userName": {
7        "example": "Sarah"
8      }
9    }
10  },
11  "order.summary": {
12    "message": "Order #{orderId} placed on {date}",
13    "context": "{orderId} is a 6-digit number, {date} is formatted like 'Feb 12, 2026'",
14    "placeholders": {
15      "orderId": {
16        "example": "123456"
17      },
18      "date": {
19        "example": "Feb 12, 2026"
20      }
21    }
22  }
23}

Tone and Formality Context

Brand voice affects translation choices:

JSONCopy
1{
2  "welcome.message": {
3    "message": "Hey there! Ready to get started?",
4    "context": "Informal, friendly tone. Target young professional audience.",
5    "tone": "casual"
6  },
7  "legal.terms": {
8    "message": "By proceeding, you agree to our terms.",
9    "context": "Formal, legal language. Must be precise.",
10    "tone": "formal"
11  }
12}

Same Word, Different Translations

Example: "Open"

Example: "Close"

How to Provide Context

Using JSON Comments (Non-Standard)

Some tools support extended JSON with comments:

JSON5Copy
1{
2  // Button shown in top-right corner of dashboard
3  "dashboard.settings": "Settings",
4
5  // Greeting shown after successful login
6  // {userName} is the user's first name
7  "greeting": "Welcome, {userName}!"
8}

Using ARB Format

ARB (Application Resource Bundle) has built-in metadata:

JSONCopy
1{
2  "@@locale": "en",
3  "welcomeMessage": "Welcome to our app",
4  "@welcomeMessage": {
5    "type": "text",
6    "description": "Greeting shown on first app launch",
7    "context": "Homepage header",
8    "screenshot": "screenshots/welcome.png",
9    "maxLength": 50
10  }
11}

Using XLIFF Format

XLIFF supports rich context natively:

XMLCopy
1<trans-unit id="welcome">
2  <source>Welcome</source>
3  <target>Bienvenido</target>
4  <note>Greeting shown on homepage header</note>
5  <context-group purpose="location">
6    <context context-type="sourcefile">HomePage.tsx</context>
7    <context context-type="linenumber">42</context>
8  </context-group>
9  <extradata>
10    <![CDATA[
11      maxLength: 50
12      tone: friendly
13    ]]>
14  </extradata>
15</trans-unit>

Using Translation Management Systems

IntlPull and similar TMS platforms provide structured context fields:

TypeScriptCopy
1// When adding a key via IntlPull API
2await intlpull.createKey({
3  key: 'welcome.message',
4  value: 'Welcome to our app',
5  context: {
6    description: 'Greeting shown on first app launch',
7    screenshot: await uploadScreenshot('welcome.png'),
8    maxLength: 50,
9    tone: 'friendly',
10    location: 'HomePage.tsx:42'
11  }
12});

Developer Workflow for Adding Context

Step 1: Capture Screenshots

TypeScriptCopy
1// Automated screenshot capture during development
2import puppeteer from 'puppeteer';
3
4async function captureTranslationContext(url: string, selector: string) {
5  const browser = await puppeteer.launch();
6  const page = await browser.newPage();
7
8  await page.goto(url);
9  await page.waitForSelector(selector);
10
11  // Highlight the specific element
12  await page.evaluate((sel) => {
13    const el = document.querySelector(sel);
14    if (el) {
15      el.style.outline = '3px solid red';
16    }
17  }, selector);
18
19  const screenshot = await page.screenshot();
20  await browser.close();
21
22  return screenshot;
23}
24
25// Usage
26const screenshot = await captureTranslationContext(
27  'http://localhost:3000',
28  '[data-i18n="welcome.message"]'
29);

Step 2: Annotate Translation Keys

TypeScriptCopy
1// Use data attributes for automatic context extraction
2<button
3  data-i18n="button.submit"
4  data-i18n-context="Primary action button on checkout page"
5  data-i18n-max-length="20"
6  data-i18n-tone="formal"
7>
8  {t('button.submit')}
9</button>

Step 3: Extract Context Automatically

TypeScriptCopy
1import { parseHTML } from './parser';
2
3function extractI18nContext(html: string) {
4  const doc = parseHTML(html);
5  const elements = doc.querySelectorAll('[data-i18n]');
6
7  const contexts = [];
8
9  elements.forEach(el => {
10    contexts.push({
11      key: el.getAttribute('data-i18n'),
12      context: el.getAttribute('data-i18n-context'),
13      maxLength: el.getAttribute('data-i18n-max-length'),
14      tone: el.getAttribute('data-i18n-tone'),
15      // Infer more context from DOM
16      tagName: el.tagName,
17      className: el.className,
18      position: el.getBoundingClientRect()
19    });
20  });
21
22  return contexts;
23}

Step 4: Sync with TMS

TypeScriptCopy
1// Push context to IntlPull
2import { IntlPullClient } from '@intlpull/sdk';
3
4const client = new IntlPullClient({ apiKey: process.env.INTLPULL_API_KEY });
5
6async function syncContext() {
7  const contexts = extractI18nContext(html);
8
9  for (const ctx of contexts) {
10    await client.updateKey(ctx.key, {
11      context: ctx.context,
12      maxLength: ctx.maxLength ? parseInt(ctx.maxLength) : undefined,
13      metadata: {
14        tagName: ctx.tagName,
15        className: ctx.className
16      }
17    });
18  }
19}

IntlPull's Screenshot + OCR Feature

IntlPull automates context capture with advanced features:

Automatic Text Detection

Upload a screenshot and IntlPull uses OCR to:

• Detect all visible text in the image
• Suggest matches to existing translation keys
• Automatically link screenshots to relevant keys
• Highlight missing translations

TypeScriptCopy
1// Upload screenshot via API
2const screenshot = await client.uploadScreenshot({
3  file: screenshotBuffer,
4  projectId: 'proj_123',
5  autoDetect: true // Enable OCR
6});
7
8// IntlPull returns detected text with confidence scores
9console.log(screenshot.detectedText);
10// [
11//   { text: 'Welcome', confidence: 0.98, key: 'welcome.message' },
12//   { text: 'Get Started', confidence: 0.95, key: 'button.start' },
13//   { text: 'Learn More', confidence: 0.92, key: null } // Not found
14// ]

Visual Translation Editor

Translators see:

• Original screenshot with highlighted text
• Side-by-side comparison of source and target
• Character count with visual overflow indicators
• RTL preview for Arabic/Hebrew

Context Quality Scoring

IntlPull scores each key based on context completeness:

Score > 80: Excellent context Score 50-79: Good context Score < 50: Missing critical context

Measuring Quality Improvement

Before Context (Baseline)

JSONCopy
{
  "close": "Close"
}

Translation results:

• Spanish: "Cerrar" (50% wrong when used for "Close deal")
• German: "Schließen" (60% wrong for "Close account")
• Revision cycles: 2-3

After Context

JSONCopy
1{
2  "dialog.close": {
3    "message": "Close",
4    "context": "Button to dismiss dialog window",
5    "screenshot": "screenshots/dialog-close.png",
6    "maxLength": 10
7  },
8  "sales.close": {
9    "message": "Close",
10    "context": "Button to finalize sales deal",
11    "screenshot": "screenshots/close-deal.png",
12    "tone": "professional"
13  }
14}

Translation results:

• Spanish: "Cerrar" (dialog), "Cerrar trato" (sales) ✅
• German: "Schließen" (dialog), "Abschließen" (sales) ✅
• Revision cycles: 0-1

Metrics to Track

TypeScriptCopy
1interface ContextMetrics {
2  translationAccuracy: number;      // % correct on first attempt
3  revisionCycles: number;           // Average revisions needed
4  translatorConfidence: number;     // 1-5 scale
5  timeToComplete: number;           // Hours per 1000 words
6  contextScore: number;             // 0-100 based on completeness
7}
8
9// Example comparison
10const beforeContext: ContextMetrics = {
11  translationAccuracy: 0.65,
12  revisionCycles: 2.3,
13  translatorConfidence: 2.8,
14  timeToComplete: 8.5,
15  contextScore: 25
16};
17
18const afterContext: ContextMetrics = {
19  translationAccuracy: 0.92,
20  revisionCycles: 0.6,
21  translatorConfidence: 4.5,
22  timeToComplete: 5.2,
23  contextScore: 85
24};
25
26// 42% improvement in accuracy
27// 74% reduction in revisions
28// 39% faster completion

Best Practices

✅ Always provide screenshots for UI text ✅ Include character limits for space-constrained elements ✅ Explain abbreviations and acronyms ✅ Give placeholder examples for variable formatting ✅ Specify tone (formal, casual, technical, playful) ✅ Note pluralization requirements ✅ Flag gender-specific content ✅ Indicate reusability (can this translation be reused elsewhere?)

❌ Don't assume translators understand your product ❌ Don't skip context for "obvious" strings ❌ Don't use technical jargon in context descriptions ❌ Don't forget to update context when UI changes

FAQ

Q: How much context is too much? A: More is better, but prioritize: screenshot > description > character limit > examples. Aim for 2-3 sentences in descriptions.

Q: Should I provide context for every single string? A: Yes. Even simple strings benefit from context. "OK" button context helps translators choose between "OK", "Aceptar", "Vale", "De acuerdo" in Spanish.

Q: Can I use machine translation for context descriptions? A: Yes, but keep descriptions in English. Translators typically read English context descriptions, and MT can introduce confusion if translated poorly.

Q: How do I handle context for strings shared across multiple locations? A: Provide screenshots for the most important location. Note in the context if it's reused: "Also appears in settings menu and profile page."

Q: Do screenshots need to be high resolution? A: Medium resolution is fine (1920x1080 max). The goal is clarity, not print quality. Compress images to reduce TMS load times.

Q: How often should I update screenshots? A: Update when UI changes affect the visible context. IntlPull can detect when screenshots become outdated based on OCR mismatches.

Q: What if translators still make mistakes despite good context? A: Create a glossary for recurring terms, provide more examples, and consider brief translator training on your product domain.