Replexica SDK (for JavaScript)

The Replexica SDK is a powerful tool for developers who need to integrate real-time AI-powered localization into their applications. It's designed to be simple to use, yet flexible enough to handle complex localization scenarios.

When to Use Replexica SDK

The SDK shines in scenarios where you need dynamic, context-aware translations:

1. Chat applications: Translate messages on-the-fly.
2. Email clients: Provide real-time translation of incoming emails.
3. Comment systems: Localize user-generated content in real-time.
4. Social media tools: Provide multilingual experiences for user posts and comments.

Getting Started

First, install the SDK:

npm install @replexica/sdk

Then, initialize it in your code:

import { ReplexicaEngine } from '@replexica/sdk';

const replexica = new ReplexicaEngine({
  apiKey: 'your-api-key-here',
});

Core Features

The SDK provides several specialized methods for different localization needs:

1. localizeText: For simple string translations

const localizedText = await replexica.localizeText(
  'Hello, world!',
  { sourceLocale: 'en', targetLocale: 'es' }
);

2. batchLocalizeText: For translating text into multiple languages at once

const localizedTexts = await replexica.batchLocalizeText(
  'Hello, world!',
  { 
    sourceLocale: 'en',
    targetLocales: ['es', 'fr', 'de'],
    fast: true // optional
  }
);
// Returns an array of translations in the requested order:
// ['¡Hola Mundo!', 'Bonjour le monde!', 'Hallo Welt!']

3. localizeObject: For translating objects with string values

const localizedContent = await replexica.localizeObject(
  { greeting: 'Hello', farewell: 'Goodbye' },
  { sourceLocale: 'en', targetLocale: 'es' }
);

4. localizeChat: For chat conversations, preserving speaker names

const localizedChat = await replexica.localizeChat([
  { name: 'Alice', text: 'Hello!' },
  { name: 'Bob', text: 'Hi there!' }
], { sourceLocale: 'en', targetLocale: 'es' });

5. localizeHtml: For HTML documents, preserving structure and formatting

const localizedHtml = await replexica.localizeHtml(
  '<div>Hello <strong>world</strong></div>',
  { sourceLocale: 'en', targetLocale: 'es' }
);

6. recognizeLocale: For detecting the language of text

const locale = await replexica.recognizeLocale('Bonjour le monde');
// Returns: 'fr'

Configuration Options

When initializing the SDK, you can customize several parameters:

1. apiKey (required): Your unique identifier for accessing the Replexica API.
2. batchSize (optional): Maximum number of items per API request. Defaults to 50, max 250.
3. idealBatchItemSize (optional): Target word count per batch. Defaults to 500, max 2500.

const replexica = new ReplexicaEngine({
  apiKey: 'your-api-key-here',
  batchSize: 100,
  idealBatchItemSize: 1000
});

Translation Parameters

All localization methods accept these parameters:

1. sourceLocale: The original content's language code (e.g., 'en')
2. targetLocale: The desired translation language code (e.g., 'es')
3. fast (optional): Enable faster but potentially less accurate translations

const quickTranslation = await replexica.localizeText(
  'Hello world',
  { 
    sourceLocale: 'en', 
    targetLocale: 'es',
    fast: true 
  }
);

Progress Tracking

For long-running translations, you can monitor progress using a callback:

await replexica.localizeObject(
  largeObject,
  { sourceLocale: 'en', targetLocale: 'es' },
  (progress) => console.log(`Translation progress: ${progress}%`)
);

Under the Hood

While you don't need to know this to use the SDK, understanding how it works can help you use it more effectively:

1. Content chunking: The SDK breaks your content into optimal chunks based on batchSize and idealBatchItemSize.

2. Progress tracking: The SDK keeps track of processed chunks, enabling accurate progress reporting.

3. Error handling: It manages API errors, retrying failed requests when appropriate.

4. Response aggregation: After all chunks are processed, the SDK reassembles them into a single response.

This approach allows the SDK to handle large volumes of content efficiently, while providing a simple interface for developers.

Best Practices

1. Reuse the ReplexicaEngine instance: Creating a new instance for every request is inefficient.

2. Handle errors: While the SDK manages many error scenarios, your app should still have error handling in place.

3. Use the progress callback for long-running tasks: This helps provide feedback to users during large translation jobs.

4. Consider your content structure: The SDK works best with flat objects. If you have deeply nested content, consider flattening it before passing it to the SDK.

By leveraging the Replexica SDK, you can add powerful, AI-driven localization capabilities to your application with minimal effort. Whether you're building a chat app, a content platform, or any other multilingual software, Replexica SDK provides the tools you need to create seamless, real-time localization experiences.