React SDK Installation

Step-by-step guide to install and configure the LiveI18n React SDK in your application.

Prerequisites

Before installing the React SDK, ensure you have:

Node.js 16+ and npm/yarn
React 16.8+ (hooks support required)
LiveI18n account with API keys (get started)

Installation

Using npm

npm install @livei18n/react-sdk

Using yarn

yarn add @livei18n/react-sdk

Using pnpm

pnpm add @livei18n/react-sdk

Environment Setup

1. Configure Environment Variables

Create a .env file in your project root:

# .env
REACT_APP_LIVEI18N_API_KEY=your_api_key_here
REACT_APP_LIVEI18N_CUSTOMER_ID=your_customer_id_here

warning

Never commit actual API keys to version control. Use environment variables for all sensitive credentials.

2. Add to .gitignore

Ensure your .gitignore includes:

# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

Basic Configuration

1. Wrap Your App with the Provider

In your app's entry point (usually src/index.js or src/App.js), wrap your application with the LiveI18nProvider:

import React from 'react';
import ReactDOM from 'react-dom/client';
import { LiveI18nProvider } from '@livei18n/react-sdk';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <LiveI18nProvider config={{
    apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
    customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
  }}>
    <App />
  </LiveI18nProvider>
);

2. First Translation

Add your first translation to any component inside the provider:

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

function App() {
  return (
    <div>
      <h1>
        <LiveText>Welcome to our application!</LiveText>
      </h1>
    </div>
  );
}

export default App;

Advanced Configuration

Custom Configuration Options

<LiveI18nProvider config={{
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID,
  
  // Optional: Custom API endpoint
  endpoint: 'https://api.livei18n.com',
  
  // Optional: Default language (see detailed explanation below)
  defaultLanguage: 'es-ES'
}}>
  <App />
</LiveI18nProvider>

Default Language Configuration

The defaultLanguage option controls what language LiveText components translate to when no explicit language prop is provided. This is a powerful feature for setting global translation behavior:

Auto-Detection Mode (No defaultLanguage)

When defaultLanguage is not specified, the SDK automatically detects the user's browser language:

// Auto-detect mode - uses browser language
<LiveI18nProvider config={{
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
  // No defaultLanguage specified
}}>
  <App />
</LiveI18nProvider>

// This will translate to the user's browser language
<LiveText>Welcome to our app!</LiveText>

Fixed Default Language

Set a specific language as the default for all translations:

// Fixed language mode - always translate to Spanish
<LiveI18nProvider config={{
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID,
  defaultLanguage: 'es-ES'
}}>
  <App />
</LiveI18nProvider>

// This will translate to Spanish
<LiveText>Welcome to our app!</LiveText>

Per-Component Language Override

Individual components can override the default language:

// These components override the default language
<LiveText language="fr-FR">Welcome!</LiveText>  {/* French */}
<LiveText language="de-DE">Welcome!</LiveText>  {/* German */}
<LiveText>Welcome!</LiveText>                    {/* Uses defaultLanguage or auto-detect */}

Dynamic Language Switching

You can update the default language at runtime using the useLiveI18n hook:

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

function LanguageSwitcher() {
  const { updateDefaultLanguage, defaultLanguage } = useLiveI18n();
  
  const handleLanguageChange = (language) => {
    // Update the default language for all LiveText components
    updateDefaultLanguage(language);
    
    // To enable auto-detection, pass undefined
    // updateDefaultLanguage(undefined);
  };

  return (
    <select 
      value={defaultLanguage || ''} 
      onChange={(e) => handleLanguageChange(e.target.value || undefined)}
    >
      <option value="">Auto-detect</option>
      <option value="en-US">English</option>
      <option value="es-ES">Spanish</option>
      <option value="fr-FR">French</option>
    </select>
  );
}

Common Language Codes

Here are commonly used language codes for defaultLanguage:

Language	Code	Example
English (US)	`en-US`	American English
English (UK)	`en-GB`	British English
Spanish (Spain)	`es-ES`	European Spanish
Spanish (Mexico)	`es-MX`	Mexican Spanish
French (France)	`fr-FR`	European French
German	`de-DE`	German
Italian	`it-IT`	Italian
Portuguese (Brazil)	`pt-BR`	Brazilian Portuguese
Japanese	`ja-JP`	Japanese
Korean	`ko-KR`	Korean
Chinese (Simplified)	`zh-CN`	Simplified Chinese
Chinese (Traditional)	`zh-TW`	Traditional Chinese
Russian	`ru-RU`	Russian

Best Practices

For Global Applications:

// Let users' browsers determine the language
<LiveI18nProvider config={{
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
  // No defaultLanguage - auto-detect
}}>
  <App />
</LiveI18nProvider>

For Region-Specific Applications:

// Set a specific default for your target market
<LiveI18nProvider config={{
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID,
  defaultLanguage: 'es-ES' // Spanish market
}}>
  <App />
</LiveI18nProvider>

For Multi-Tenant Applications:

// Set default based on user preferences or tenant settings
const userLanguage = getUserPreference() || 'en-US';

<LiveI18nProvider config={{
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID,
  defaultLanguage: userLanguage
}}>
  <App />
</LiveI18nProvider>

TypeScript Setup

The SDK includes full TypeScript definitions. For custom types:

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

// Extend LiveText props if needed
interface CustomLiveTextProps extends LiveTextProps {
  customProp?: string;
}

const CustomLiveText: React.FC<CustomLiveTextProps> = (props) => {
  return <LiveText {...props} />;
};

Framework Integration

Next.js Setup

For Next.js applications:

// pages/_app.js
import { LiveI18nProvider } from '@livei18n/react-sdk';

export default function App({ Component, pageProps }) {
  return (
    <LiveI18nProvider config={{
      apiKey: process.env.NEXT_PUBLIC_LIVEI18N_API_KEY,
      customerId: process.env.NEXT_PUBLIC_LIVEI18N_CUSTOMER_ID
    }}>
      <Component {...pageProps} />
    </LiveI18nProvider>
  );
}

Create React App

For Create React App (standard setup shown above works perfectly).

Vite Setup

For Vite applications:

// src/main.jsx
import { LiveI18nProvider } from '@livei18n/react-sdk';
import App from './App';

root.render(
  <LiveI18nProvider config={{
    apiKey: import.meta.env.VITE_LIVEI18N_API_KEY,
    customerId: import.meta.env.VITE_LIVEI18N_CUSTOMER_ID
  }}>
    <App />
  </LiveI18nProvider>
);

Verification

1. Test Your Setup

After installation, test your setup:

function TestComponent() {
  return (
    <div>
      <LiveText>Hello, world!</LiveText>
      <LiveText language="es-ES">Hello, world!</LiveText>
      <LiveText tone="friendly">Welcome!</LiveText>
    </div>
  );
}

2. Check Browser Console

Open browser dev tools and look for:

✅ No error messages
✅ Network requests to LiveI18n API
✅ Successful translation responses

3. Use the Demo

Verify your API keys work with our interactive demo:

Enter your API key and customer ID
Test various translations
Confirm everything works as expected

Troubleshooting

Common Issues

Components not translating?

// ❌ Wrong - LiveText used outside provider
function App() {
  return <LiveText>Hello</LiveText>; // Error: must be within provider
}

// ✅ Correct - LiveText used inside provider
<LiveI18nProvider config={{ /* config */ }}>
  <App />
</LiveI18nProvider>

function App() {
  return <LiveText>Hello</LiveText>; // Works correctly
}

Environment variables not loading?

Verify variable names start with REACT_APP_ (CRA) or NEXT_PUBLIC_ (Next.js)
Restart your development server after adding variables
Check .env file is in the project root

TypeScript errors?

# Install types if needed
npm install --save-dev @types/react

API requests failing?

Verify API keys in the demo
Check network tab for error details
Ensure customer ID matches your account

Performance Tips

Reduce bundle size:

// ✅ Import only what you need
import { LiveText } from '@livei18n/react-sdk';

// ❌ Avoid importing everything
import * as LiveI18n from '@livei18n/react-sdk';

Optimize rendering:

// ✅ Wrap stable text that won't change frequently
<LiveText>Static welcome message</LiveText>

// ⚠️ Be careful with dynamic content
<LiveText>Hello {username}</LiveText> // Creates new cache entries

Next Steps

Now that the SDK is installed:

Learn basic usage - Start translating
See real examples - Implementation patterns
Try the demo - Test your setup

Need help? Check our troubleshooting guide or contact support.

Prerequisites​

Installation​

Using npm​

Using yarn​

Using pnpm​

Environment Setup​

1. Configure Environment Variables​

2. Add to .gitignore​

Basic Configuration​

1. Wrap Your App with the Provider​

2. First Translation​

Advanced Configuration​

Custom Configuration Options​

Default Language Configuration​

Auto-Detection Mode (No defaultLanguage)​

Fixed Default Language​

Per-Component Language Override​

Dynamic Language Switching​

Common Language Codes​

Best Practices​

TypeScript Setup​

Framework Integration​

Next.js Setup​

Create React App​

Vite Setup​

Verification​

1. Test Your Setup​

2. Check Browser Console​

3. Use the Demo​

Troubleshooting​

Common Issues​

Performance Tips​

Next Steps​