Skip to main content

React SDK

The LiveI18n React SDK provides seamless internationalization for React applications with a simple component-based approach.

Overview​

The React SDK offers:

  • <LiveText> component - Wrap any text for automatic translation
  • Intelligent caching - LRU cache with 500 entries and 1-hour TTL
  • TypeScript support - Full type definitions included
  • Automatic fallbacks - Original text displayed if translation fails
  • Zero configuration - Works out of the box with minimal setup

Quick Example​

import { initializeLiveI18n, LiveText } from '@livei18n/react-sdk';

// Initialize once in your app root
initializeLiveI18n({
  apiKey: 'your-api-key',
  customerId: 'your-customer-id'
});

// Use anywhere in your components
function MyComponent() {
  return (
    <div>
      <h1>
        <LiveText>Welcome to our application!</LiveText>
      </h1>
      <p>
        <LiveText tone="friendly" context="user greeting">
          Hello, how can we help you today?
        </LiveText>
      </p>
    </div>
  );
}

Key Features​

Component-Based Translation​

The <LiveText> component makes translation as simple as wrapping your text:

<LiveText>Your text here</LiveText>

Context & Tone Support​

Provide context and tone for better translation quality:

<LiveText 
  tone="professional"
  context="business email"
>
  Thank you for your inquiry
</LiveText>

Language Detection​

The SDK automatically detects the user's language preference:

// Automatically uses browser language
<LiveText>Hello world</LiveText>

// Override with specific language
<LiveText language="es-ES">Hello world</LiveText>

Intelligent Caching​

Built-in LRU cache optimizes performance:

  • 500 entries maximum
  • 1-hour TTL for cached translations
  • Automatic cleanup of expired entries
  • Memory efficient with size limits

Architecture​

┌─────────────────────────────────┐
│         React App               │
│  ┌─────────────────────────┐   │
│  │    <LiveText>           │   │
│  │    - Text Analysis      │   │
│  │    - Cache Check        │   │
│  │    - API Request        │   │
│  │    - Fallback Handling  │   │
│  └─────────────────────────┘   │
│              │                  │
│  ┌─────────────────────────┐   │
│  │    LRU Cache            │   │
│  │    - 500 entries        │   │
│  │    - 1 hour TTL         │   │
│  │    - SHA-256 keys       │   │
│  └─────────────────────────┘   │
└─────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────┐
│       LiveI18n API              │
│  - Translation Service          │
│  - Language Detection           │
│  - Cost Optimization            │
└─────────────────────────────────┘

Installation & Setup​

1. Install the Package​

npm install @livei18n/react-sdk

2. Initialize the SDK​

Add this to your app's root component (usually App.js or index.js):

import { initializeLiveI18n } from '@livei18n/react-sdk';

initializeLiveI18n({
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
});

3. Use the Component​

import { LiveText } from '@livei18n/react-sdk';

function MyComponent() {
  return <LiveText>Hello, world!</LiveText>;
}

Advanced Usage​

Error Handling​

The SDK handles errors gracefully:

// If translation fails, shows original text
<LiveText>This text will always display</LiveText>

Performance Optimization​

The SDK includes several performance optimizations:

  • Request deduplication - Identical requests are merged
  • Automatic batching - Multiple translations in single API call
  • Smart caching - Canonical cache keys prevent duplicates
  • Memory management - LRU eviction prevents memory leaks

Development Mode​

Enable debug logging in development:

// Enable debug mode (not recommended for production)
initializeLiveI18n({
  apiKey: 'your-api-key',
  customerId: 'your-customer-id',
  debug: process.env.NODE_ENV === 'development'
});

Testing​

With the Demo​

Test your setup with our interactive demo:

  1. Enter your API key and customer ID
  2. Try different text inputs
  3. Test various languages and contexts
  4. Verify caching behavior

Unit Testing​

Mock the SDK for unit tests:

// Mock the SDK in tests
jest.mock('@livei18n/react-sdk', () => ({
  LiveText: ({ children }) => <span>{children}</span>,
  initializeLiveI18n: jest.fn()
}));

Next Steps​

Troubleshooting​

Common Issues​

Translations not appearing?

  • Check your API key and customer ID
  • Verify initialization is called before using <LiveText>
  • Test with the demo

Performance issues?

  • Check cache hit rates in browser dev tools
  • Verify you're not re-initializing the SDK

Need help? Contact support or check our troubleshooting guide.