HYTOPIA Translations - Browser Library

Automatically translate your web content to the user's locale using HYTOPIA's translation services.

Features

• 🌍 Automatic Detection - Automatically finds and translates all text in your DOM
• 🔄 Real-time Translation - Watches for new content and translates it on the fly
• 💾 Smart Caching - Uses IndexedDB for large-scale translation caching
• ⚡ Batch Processing - Efficiently batches translation requests
• 🎯 Locale Aware - Automatically detects user's BCP47 language code
• 🚀 Lightweight - Simple, elegant implementation with no dependencies

Development

Local Development & Testing

cd browser-lib
npm install
npm run dev

This will start a Vite dev server at http://localhost:3000 and open example.html with hot reload.

Installation

Via NPM

npm install @hytopia/translations

Note: This library is written in TypeScript and designed to be imported directly by your bundler (Vite, Webpack, etc.).

Usage

Basic Usage

import HYTOPIATranslations from '@hytopia/translations';

// Initialize with your API endpoint
await HYTOPIATranslations.init('https://dev.translations.hytopia.com');

That's it! The library will automatically:

1. Detect the user's language (e.g., es-ES, fr-FR, ja-JP)
2. Find all text content in your page
3. Translate it to the user's language
4. Watch for new content and translate it automatically

Override Language Detection

// Force a specific language instead of auto-detecting
await HYTOPIATranslations.init('https://dev.translations.hytopia.com', 'ja-JP');

This is useful for:

• Testing translations
• Allowing users to manually select their language
• Supporting custom language selection UI

Skip Translation for Specific Elements

Add the data-hytopia-skip attribute to any element you want to exclude:

<div data-hytopia-skip>
  This text will not be translated
</div>

How It Works

1. Detection - On init, finds all text nodes in the DOM
2. Hash Generation - Creates reference hashes for each text + target language
3. Cache Check - Checks local IndexedDB cache first
4. Batch Request - Requests translations in batches (2-second intervals)
5. DOM Update - Updates text nodes with translated content
6. Observation - Watches for new DOM nodes and translates them automatically

Browser Compatibility

• ✅ Chrome/Brave
• ✅ Safari
• ✅ Firefox
• ✅ Edge
• ✅ WebView (iOS/Android)

Requires browsers with support for:

• MutationObserver
• IndexedDB
• SubtleCrypto (for hash generation)
• fetch API

API Reference

HYTOPIATranslations.init(endpoint: string, languageCode?: string): Promise<void>

Initialize the translation library with your API endpoint.

Parameters:

• endpoint (string, required) - Your HYTOPIA translations API endpoint
• languageCode (string, optional) - BCP47 language code override (e.g., 'es-ES', 'ja-JP', 'fr-FR')

Examples:

// Auto-detect user's language
await HYTOPIATranslations.init('https://prod.translations.hytopia.com');

// Force specific language
await HYTOPIATranslations.init('https://prod.translations.hytopia.com', 'ja-JP');

Advanced Usage

With Module Bundlers

import HYTOPIATranslations from '@hytopia/translations';

// In your app initialization
async function initApp() {
  await HYTOPIATranslations.init(process.env.TRANSLATIONS_API);
  // Rest of your app...
}

initApp();

With React

import { useEffect } from 'react';
import HYTOPIATranslations from '@hytopia/translations';

function App() {
  useEffect(() => {
    HYTOPIATranslations.init('https://dev.translations.hytopia.com');
  }, []);

  return <div>Your app content</div>;
}

With Vue

import HYTOPIATranslations from '@hytopia/translations';

export default {
  mounted() {
    HYTOPIATranslations.init('https://dev.translations.hytopia.com');
  }
}

Storage

The library uses IndexedDB for caching translations, which can handle:

• Gigabytes of data (browser dependent)
• Persistent storage across sessions
• Efficient key-value lookups

Cache is keyed by reference hash (text + language combination).

Performance

• Batch Processing - Translations are batched every 2 seconds
• Smart Caching - Translations are cached locally to minimize API calls
• Efficient Hashing - Uses SHA-256 with 96-bit truncation for compact hashes
• Minimal DOM Impact - Only watches for text nodes, ignores other changes

License

ISC