Translation API Fix - Summary

Problem Statement

The translation feature was not showing as available in Chrome Beta, even with Experimental Web Features enabled. Users were seeing "Translation not available" instead of the translation dropdown.

Root Cause Analysis

The Issue

The codebase was implementing the outdated Translation API specification that used:

// OLD API (deprecated)
if ('translation' in self && self.translation && 'createTranslator' in self.translation) {
    const canTranslate = await self.translation.canTranslate({
        sourceLanguage: 'en',
        targetLanguage: 'es'
    });
    const translator = await self.translation.createTranslator({
        sourceLanguage: 'en',
        targetLanguage: 'es'
    });
}

However, the current Translation API specification (as of 2024-2025) uses:

// NEW API (current spec)
if ('Translator' in window && window.Translator) {
    const availability = await Translator.availability({
        sourceLanguage: 'en',
        targetLanguage: 'es'
    });
    const translator = await Translator.create({
        sourceLanguage: 'en',
        targetLanguage: 'es'
    });
}

Why It Failed

1. The browser check 'translation' in self always returned false because the API moved from self.translation to window.Translator
2. The code never detected the API as available, even when it was present
3. The UI always showed "Translation not available" instead of the translation controls

Solution Implemented

Code Changes

1. Updated TypeScript Interfaces

Before:

interface TranslationAPI {
    canTranslate(options: { sourceLanguage: string; targetLanguage: string }): Promise<string>;
    createTranslator(options: { sourceLanguage: string; targetLanguage: string }): Promise<Translator>;
}

declare global {
    interface WindowOrWorkerGlobalScope {
        translation?: TranslationAPI;
    }
}

After:

interface TranslatorConstructor {
    create(options: TranslatorCreateOptions): Promise<Translator>;
    availability(options: TranslatorCreateOptions): Promise<'unavailable' | 'downloadable' | 'downloading' | 'available'>;
}

declare global {
    interface Window {
        Translator?: TranslatorConstructor;
    }
}

2. Updated Browser Support Check

Before:

if ('translation' in self && self.translation && 'createTranslator' in self.translation) {
    const canTranslate = await self.translation.canTranslate({
        sourceLanguage: 'en',
        targetLanguage: 'es'
    });
    this.canTranslate = canTranslate !== 'no';
}

After:

if ('Translator' in window && window.Translator) {
    const availability = await window.Translator.availability({
        sourceLanguage: 'en',
        targetLanguage: 'es'
    });
    this.canTranslate = availability !== 'unavailable';
}

3. Updated Translator Creation

Before:

this.translator = await self.translation.createTranslator({
    sourceLanguage: 'en',
    targetLanguage: targetLanguage
});

After:

this.translator = await window.Translator.create({
    sourceLanguage: 'en',
    targetLanguage: targetLanguage
});

Files Modified

1. CompendiumUI/script.ts - Updated TranslationService class
2. CompendiumUI/translation.test.ts - Updated tests to check for new API
3. TRANSLATION_IMPLEMENTATION.md - Updated documentation
4. TRANSLATION_FEATURE_README.md - Updated API detection examples
5. TESTING_TRANSLATION.md - Added new testing guide

Verification

Build & Tests

✅ All 69 tests pass ✅ TypeScript compilation successful ✅ No build errors ✅ Code review passed with no issues ✅ Security scan (CodeQL) passed with 0 alerts

Expected Behavior

When Translation API is available: - ✅ Translation dropdown appears in navigation menu - ✅ User can select from 12 languages - ✅ Content translates when language is selected - ✅ Warning banner appears when translated - ✅ Can return to English original

When Translation API is not available: - ✅ "Translation not available" link appears in header - ✅ Tooltip explains requirements when clicked - ✅ Suggests using browser's built-in translation

Console Output

When the page loads with the new code:

If API is available:

Translation API availability: available -> canTranslate: true

If API requires download:

Translation API availability: downloadable -> canTranslate: true

If API is not supported:

Translation API not supported in this browser

Testing Instructions

Prerequisites

1. Chrome Canary, Dev, or Beta (Version 128+)
2. Enable flags in chrome://flags:
3. #translation-api
4. #enable-experimental-web-platform-features
5. Restart Chrome

Quick Test

Open browser console and type:

// Check if API exists
'Translator' in window  // Should return true

// Check availability
await Translator.availability({ sourceLanguage: 'en', targetLanguage: 'es' })
// Should return: 'available', 'downloadable', 'downloading', or 'unavailable'

Full Test

1. Build and run: cd CompendiumUI && npm install && npm run dev
2. Navigate to http://localhost:5173
3. Look for translation dropdown in menu
4. Select a language and verify translation works
5. Verify warning banner appears
6. Return to English and verify restoration

References

API Specification

• New Spec: https://github.com/WICG/translation-api
• Chrome Status: https://chromestatus.com/feature/5182950152642560
• Explainer: https://github.com/WICG/translation-api/blob/main/explainer.md

Key Differences

Aspect	Old API	New API
Namespace	self.translation	window.Translator
Check method	canTranslate() returns string	availability() returns enum
Create method	createTranslator()	create()
Return values	'yes', 'no', 'after-download'	'available', 'downloadable', 'downloading', 'unavailable'

Impact

This fix ensures that users with Chrome Beta and experimental flags enabled will now see the translation feature as available, allowing them to: - Test the experimental translation feature - Translate Copyright Compendium content into 12 languages - Provide feedback on the feature before wider release

Future Considerations

• Monitor Translation API specification for further changes
• Update when API is released to stable Chrome
• Consider adding fallback to cloud translation services
• Add translation quality indicators
• Support for additional languages as they become available