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. Initialize the SDK

In your app's entry point (usually src/index.js or src/App.js), add:

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

// Initialize LiveI18n before rendering your app
initializeLiveI18n({
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
});

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

2. First Translation

Add your first translation to any component:

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

initializeLiveI18n({
  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'
});

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
initializeLiveI18n({
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
  // No defaultLanguage specified
});

// 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
initializeLiveI18n({
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID,
  defaultLanguage: 'es-ES'
});

// 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 without re-initializing:

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

function LanguageSwitcher() {
  const handleLanguageChange = (language) => {
    // Update the global default language
    updateDefaultLanguage(language);
    
    // To enable auto-detection, pass undefined
    // updateDefaultLanguage(undefined);
  };

  return (
    <select onChange={(e) => handleLanguageChange(e.target.value)}>
      <option value="en-US">English</option>
      <option value="es-ES">Spanish</option>
      <option value="fr-FR">French</option>
      <option value="">Auto-detect</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
French (Canada)	fr-CA	Canadian 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
initializeLiveI18n({
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID
  // No defaultLanguage - auto-detect
});

For Region-Specific Applications:

// Set a specific default for your target market
initializeLiveI18n({
  apiKey: process.env.REACT_APP_LIVEI18N_API_KEY,
  customerId: process.env.REACT_APP_LIVEI18N_CUSTOMER_ID,
  defaultLanguage: 'es-ES' // Spanish market
});

For Multi-Tenant Applications:

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

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

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 { initializeLiveI18n } from '@livei18n/react-sdk';

// Initialize on app startup
initializeLiveI18n({
  apiKey: process.env.NEXT_PUBLIC_LIVEI18N_API_KEY,
  customerId: process.env.NEXT_PUBLIC_LIVEI18N_CUSTOMER_ID
});

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Create React App

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

Vite Setup

For Vite applications:

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

initializeLiveI18n({
  apiKey: import.meta.env.VITE_LIVEI18N_API_KEY,
  customerId: import.meta.env.VITE_LIVEI18N_CUSTOMER_ID
});

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:

1. Enter your API key and customer ID
2. Test various translations
3. Confirm everything works as expected

Troubleshooting

Common Issues

SDK not initializing?

// ❌ Wrong - initialization after component render
function App() {
  initializeLiveI18n({ /* config */ }); // Too late!
  return <LiveText>Hello</LiveText>;
}

// ✅ Correct - initialization before app render
initializeLiveI18n({ /* config */ });
function App() {
  return <LiveText>Hello</LiveText>;
}

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
• Explore advanced features - Customization
• See real examples - Implementation patterns
• Try the demo - Test your setup

Need help? Check our troubleshooting guide or contact support.