Skip to content

Browser-Based Translation Implementation Guide

Overview

This document describes the experimental browser-based translation feature for the Copyright Compendium web viewer. The implementation uses the emerging Translation API (formerly known as the Chrome Translation API), which provides privacy-preserving, on-device machine translation.

Current Status

⚠️ EXPERIMENTAL FEATURE

The Translation API is currently in early development and only available in: - Chrome 120+ with experimental features enabled - Edge Canary builds with experimental features

Enabling the Translation API (for testing)

To test this feature in Chrome:

  1. Open Chrome and navigate to: chrome://flags
  2. Search for "Translation API"
  3. Enable the following flags:
  4. #translation-api - Enable Translation API
  5. #enable-experimental-web-platform-features - Enable experimental features
  6. Restart Chrome
  7. Visit the Compendium site and test the translation dropdown

Architecture

Components

  1. TranslationService Class (script.js)
  2. Manages browser translation API integration
  3. Checks for API availability
  4. Handles translation of DOM elements

  5. Maintains translation state

  6. UI Components (index.html)

  7. Language selector dropdown (12 languages)
  8. Translation disclaimer banner
  9. Browser compatibility notice

  10. "View Original" link

  11. Styling (style.css)

  12. USWDS-compliant design for translation controls
  13. Responsive layout for mobile/desktop
  14. Accessible color schemes and focus states

Supported Languages

The implementation supports translation to the following languages:

  1. Spanish (Español) - es
  2. Chinese (中文) - zh
  3. French (Français) - fr
  4. German (Deutsch) - de
  5. Japanese (日本語) - ja
  6. Korean (한국어) - ko
  7. Russian (Русский) - ru
  8. Arabic (العربية) - ar
  9. Portuguese (Português) - pt
  10. Italian (Italiano) - it
  11. Hindi (हिन्दी) - hi
  12. Vietnamese (Tiếng Việt) - vi

Technical Implementation

Translation API Usage

The implementation uses the following API pattern (based on the new Translation API specification):

// Check API availability
const availability = await Translator.availability({
    sourceLanguage: 'en',
    targetLanguage: 'es'
});

// Create translator instance
const translator = await Translator.create({
    sourceLanguage: 'en',
    targetLanguage: 'es'
});

// Translate text
const translatedText = await translator.translate(originalText);

Translation Process

  1. User selects a target language from dropdown
  2. System checks if Translation API is available
  3. If available:
  4. Shows disclaimer banner
  5. Creates translator instance for language pair (en → target)
  6. Traverses DOM tree to find text nodes
  7. Translates each text node individually
  8. Updates DOM with translated content
  9. If not available:
  10. Shows browser compatibility notice
  11. Disables translation dropdown

Content Preservation

The implementation: - Only translates text nodes (preserves HTML structure) - Skips <script> and <style> elements - Maintains hyperlinks and formatting - Stores original content for restoration

User Experience

Disclaimer

When translation is active, a prominent warning banner appears:

⚠️ Experimental Translation: This is an automatically translated version and is not official. The translation may contain inaccuracies or errors. For authoritative information, please refer to the original English version.

Restoring Original Content

Users can return to the original English version by: 1. Selecting "English (Original)" from the dropdown 2. Clicking the "original English version" link in the disclaimer

Both actions reload the current chapter to ensure complete restoration.

Browser Compatibility

Supported Browsers (Future)

  • Chrome 120+ (with flags enabled currently)
  • Edge Canary (with flags enabled)
  • Expected stable support in Chrome/Edge 2024-2025

Unsupported Browsers

For browsers without Translation API support, the implementation: - Shows an informational banner - Suggests using Chrome 120+ or browser's built-in translation - Disables the language selector gracefully

Fallback Options

Users in unsupported browsers can still translate using:

  1. Browser Built-in Translation
  2. Chrome: Right-click → "Translate to [language]"
  3. Edge: Similar right-click menu

  4. Safari: Translation available in address bar

  5. Third-party Extensions

  6. Google Translate extension
  7. Microsoft Translator
  8. Other translation extensions

Privacy and Performance

Privacy Benefits

The Translation API provides: - On-device processing - No text sent to servers - No data collection - Translation happens locally - No cookies or tracking - Pure client-side operation - Offline capability - Works without internet (after model download)

Performance Characteristics

  • First translation: May be slow (model download)
  • Subsequent translations: Fast (model cached)
  • Memory usage: Moderate (translation models loaded in memory)
  • Network usage: One-time model download per language

Future Enhancements

Planned Improvements

  1. Progressive Enhancement
  2. Detect Translation API availability at runtime

  3. Gracefully degrade to external services if needed

  4. Translation Persistence

  5. Remember user's language preference
  6. Auto-translate on page navigation

  7. Store preference in localStorage

  8. Enhanced UX

  9. Loading indicators during translation
  10. Progress bars for long documents

  11. Translation confidence indicators

  12. Additional Features

  13. Side-by-side view (original + translation)
  14. Inline terminology tooltips
  15. Translation quality feedback

Integration with Other Translation Services

If the Translation API is not available or suitable, the architecture allows for integration with:

  1. Google Cloud Translation API - Server-side translation
  2. Microsoft Translator - Enterprise translation service
  3. DeepL API - High-quality neural translation
  4. LibreTranslate - Open-source self-hosted option

Testing

Manual Testing Checklist

  • [ ] Enable Translation API flags in Chrome
  • [ ] Select each supported language
  • [ ] Verify disclaimer appears
  • [ ] Check translation quality
  • [ ] Test "View Original" link
  • [ ] Verify restoration to English
  • [ ] Test in unsupported browser (Safari)
  • [ ] Verify graceful degradation
  • [ ] Check mobile responsive design
  • [ ] Test keyboard navigation (accessibility)

Test Cases

  1. Happy Path
  2. Select Spanish → Content translates → Disclaimer shows

  3. Select English → Content restores → Disclaimer hides

  4. Edge Cases

  5. Rapid language switching
  6. Translation during chapter navigation
  7. Translation with open glossary tooltips

  8. Translation with active search highlights

  9. Error Handling

  10. Translation API unavailable
  11. Network error during model download
  12. Translation timeout for large content

Code Maintenance

Key Files

  • CompendiumUI/index.html - HTML structure for translation UI
  • CompendiumUI/script.js - TranslationService class and event handlers
  • CompendiumUI/style.css - Translation UI styling
  • TRANSLATION_IMPLEMENTATION.md - This documentation

Updating Language List

To add/remove languages:

  1. Update index.html - Add/remove <option> elements
  2. Verify language code is supported by Translation API
  3. Test translation quality for new language
  4. Update this documentation

API Changes

Monitor the Translation API specification at: - https://github.com/WICG/translation-api - https://chromestatus.com/feature/5182950152642560

Deployment Notes

Production Considerations

  1. Feature Detection Required
  2. Always check 'translation' in self before using

  3. Provide clear messaging for unsupported browsers

  4. Error Handling

  5. Wrap all Translation API calls in try-catch
  6. Log errors for debugging

  7. Gracefully degrade on failure

  8. Performance Monitoring

  9. Track translation success/failure rates
  10. Monitor translation duration
  11. Alert on high error rates

Rollout Strategy

Phase 1: Experimental (Current) - Feature available in experimental branch - Requires manual flag enabling - Limited to testing/feedback

Phase 2: Early Access - Feature available in production with warning - Automatic detection of API availability - Opt-in for users with supported browsers

Phase 3: General Availability - Feature enabled by default when API is stable - Full browser support across Chrome/Edge - Comprehensive error handling and fallbacks

Support and Feedback

Known Limitations

  1. Translation quality varies by language pair
  2. Legal/technical terminology may be inaccurate
  3. Formatting may be affected in complex layouts
  4. Large documents may translate slowly

Reporting Issues

Users should be directed to report: - Translation accuracy issues → Copyright Office - Technical/UI issues → Development team - Browser compatibility issues → Browser vendor

Disclaimer Language

All translations must include:

This is an automatically translated version and is not official. The translation may contain inaccuracies or errors. For authoritative information, please refer to the original English version.

Accessibility

The translation feature includes:

  • Keyboard Navigation - Full keyboard control of language selector
  • Screen Reader Support - Proper ARIA labels and announcements
  • High Contrast - Follows USWDS color standards
  • Focus Indicators - Clear visual focus states
  • Semantic HTML - Proper heading hierarchy and landmarks

Conclusion

This implementation provides a foundation for browser-based translation of the Copyright Compendium while maintaining:

  • Privacy - All processing on-device
  • Accuracy - Clear disclaimers about non-official status
  • Accessibility - WCAG 2.1 AA compliance
  • Compatibility - Graceful degradation for unsupported browsers
  • Maintainability - Clean separation of concerns

As the Translation API matures and gains broader browser support, this feature will provide multilingual access to copyright information while preserving the authority and integrity of the original English content.

References