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 - Configurable LRU cache (default: 500 entries, 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 { LiveI18nProvider, LiveText } from '@livei18n/react-sdk';

// Wrap your app with the provider
function App() {
  return (
    <LiveI18nProvider config={{
      apiKey: 'your-api-key',
      customerId: 'your-customer-id'
    }}>
      <MyComponent />
    </LiveI18nProvider>
  );
}

// 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 with configurable settings:

  • 500 entries by default (customizable)
  • 1-hour TTL by default (customizable)
  • Automatic cleanup of expired entries
  • Memory efficient with size limits
// Custom cache configuration
<LiveI18nProvider config={{
  apiKey: 'your-api-key',
  customerId: 'your-customer-id',
  cache: {
    entrySize: 1000,    // Increase cache size
    ttlHours: 24        // Extend cache lifetime
  }
}}>
  <YourApp />
</LiveI18nProvider>

Architecture​

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

Installation & Setup​

1. Install the Package​

npm install @livei18n/react-sdk

2. Wrap Your App​

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

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

function App() {
  return (
    <LiveI18nProvider config={{
      apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
      customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
    }}>
      <YourAppContent />
    </LiveI18nProvider>
  );
}

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)
<LiveI18nProvider config={{
  apiKey: 'your-api-key',
  customerId: 'your-customer-id',
  debug: process.env.NODE_ENV === 'development'
}}>
  <YourApp />
</LiveI18nProvider>

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>,
  LiveI18nProvider: ({ children }) => <div>{children}</div>,
  useLiveI18n: () => ({
    translate: jest.fn(),
    defaultLanguage: 'en-US',
    updateDefaultLanguage: jest.fn(),
    clearCache: jest.fn()
  })
}));

Next Steps​

Troubleshooting​

Common Issues​

Translations not appearing?

  • Check your API key and customer ID
  • Verify <LiveText> components are inside <LiveI18nProvider>
  • 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.