Skip to main content

Basic Usage

Learn how to use the LiveI18n React SDK for common translation scenarios in your application.

The LiveText Component​

The <LiveText> component is the core of the React SDK. It automatically translates any text content based on the user's language preferences.

Simple Translation​

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

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

With Context and Tone​

Provide context and tone for better translation quality:

function LoginForm() {
  return (
    <div>
      <LiveText 
        context="login form"
        tone="friendly"
      >
        Please sign in to continue
      </LiveText>
    </div>
  );
}

Language Detection​

Automatic Detection​

By default, LiveI18n detects the user's preferred language from their browser settings:

// Automatically uses navigator.language
<LiveText>Hello, world!</LiveText>

Explicit Language​

Override the automatic detection with a specific language:

// Force Spanish translation
<LiveText language="es-ES">Hello, world!</LiveText>

// Use language codes or natural language
<LiveText language="spanish">Hello, world!</LiveText>
<LiveText language="français">Hello, world!</LiveText>

Common Patterns​

function Navigation() {
  return (
    <nav>
      <ul>
        <li><LiveText context="navigation">Home</LiveText></li>
        <li><LiveText context="navigation">About</LiveText></li>
        <li><LiveText context="navigation">Contact</LiveText></li>
        <li><LiveText context="navigation">Products</LiveText></li>
      </ul>
    </nav>
  );
}

Form Labels​

function ContactForm() {
  return (
    <form>
      <label>
        <LiveText context="form label">Full Name</LiveText>
        <input type="text" />
      </label>
      
      <label>
        <LiveText context="form label">Email Address</LiveText>
        <input type="email" />
      </label>
      
      <label>
        <LiveText context="form label">Message</LiveText>
        <textarea />
      </label>
      
      <button type="submit">
        <LiveText context="form button" tone="action">
          Send Message
        </LiveText>
      </button>
    </form>
  );
}

Error Messages​

function ErrorMessage({ error }) {
  if (!error) return null;
  
  return (
    <div className="error">
      <LiveText context="error message" tone="apologetic">
        {error}
      </LiveText>
    </div>
  );
}

Success Messages​

function SuccessMessage() {
  return (
    <div className="success">
      <LiveText context="success message" tone="celebratory">
        Your account has been created successfully!
      </LiveText>
    </div>
  );
}

Dynamic Content​

User-Generated Content​

For dynamic content, provide context to help with translation:

function UserProfile({ user }) {
  return (
    <div>
      <h2>
        <LiveText context="user profile greeting">
          Welcome back, {user.name}!
        </LiveText>
      </h2>
      
      <p>
        <LiveText 
          context="user stats"
          tone="informational"
        >
          You have {user.unreadCount} unread messages
        </LiveText>
      </p>
    </div>
  );
}

Status Messages​

function OrderStatus({ status, orderNumber }) {
  const getStatusMessage = (status) => {
    switch (status) {
      case 'pending':
        return `Order #${orderNumber} is being processed`;
      case 'shipped':
        return `Order #${orderNumber} has been shipped`;
      case 'delivered':
        return `Order #${orderNumber} has been delivered`;
      default:
        return `Order #${orderNumber} status unknown`;
    }
  };

  return (
    <div className={`status ${status}`}>
      <LiveText 
        context="order status"
        tone="informational"
      >
        {getStatusMessage(status)}
      </LiveText>
    </div>
  );
}

Best Practices​

1. Use Descriptive Context​

// ✅ Good - provides clear context
<LiveText context="shopping cart button">Add to Cart</LiveText>

// ❌ Avoid - too generic
<LiveText context="button">Add to Cart</LiveText>

2. Choose Appropriate Tone​

// ✅ Match tone to content
<LiveText tone="professional">Terms of Service</LiveText>
<LiveText tone="friendly">Welcome!</LiveText>
<LiveText tone="urgent">Action Required</LiveText>

3. Keep Text Semantic​

// ✅ Semantic and translatable
<LiveText>Learn More</LiveText>

// ❌ Avoid technical jargon that doesn't translate well
<LiveText>onClick Handler</LiveText>

4. Handle Edge Cases​

function ProductPrice({ price, currency }) {
  // Don't translate currency symbols or numbers
  return (
    <div>
      <LiveText context="product pricing">Price:</LiveText>
      {' '}
      <span>{price} {currency}</span>
    </div>
  );
}

Performance Considerations​

Caching Behavior​

The SDK automatically caches translations:

// These will be cached and reused
<LiveText>Home</LiveText>  // Cache hit after first load
<LiveText>Home</LiveText>  // Instant from cache

Avoiding Cache Pollution​

// ✅ Good - stable cache keys
<LiveText context="greeting">Hello</LiveText>

// ⚠️ Be careful - creates many cache entries
<LiveText>Hello {Math.random()}</LiveText>  // Don't do this

Memory Management​

The SDK uses LRU (Least Recently Used) cache eviction:

  • 500 entries maximum
  • 1-hour TTL (Time To Live)
  • Automatic cleanup of expired entries

Error Handling​

Graceful Fallbacks​

The SDK automatically falls back to original text if translation fails:

// If translation fails, shows "Hello, world!"
<LiveText>Hello, world!</LiveText>

Network Errors​

Translations continue working during network issues thanks to caching:

// Works offline if previously cached
<LiveText>Welcome back!</LiveText>

Testing Your Implementation​

Manual Testing​

  1. Change your browser language settings
  2. Reload your application
  3. Verify translations appear correctly

Using the Demo​

Test your text with the interactive demo:

  1. Enter your API keys
  2. Try your exact text strings
  3. Test different languages and contexts

Browser Dev Tools​

Monitor translation behavior:

  1. Open Network tab
  2. Look for API calls to api.livei18n.com
  3. Check for successful responses and caching

Common Use Cases​

E-commerce​

function ProductCard({ product }) {
  return (
    <div className="product-card">
      <h3>{product.name}</h3>
      <p>
        <LiveText context="product price">Price:</LiveText>
        {' '}${product.price}
      </p>
      <button>
        <LiveText context="shopping action">Add to Cart</LiveText>
      </button>
    </div>
  );
}

Dashboard​

function Dashboard({ stats }) {
  return (
    <div className="dashboard">
      <h1>
        <LiveText context="dashboard title">Analytics Dashboard</LiveText>
      </h1>
      
      <div className="stats-grid">
        <div className="stat">
          <h2>{stats.users}</h2>
          <p>
            <LiveText context="dashboard metric">Active Users</LiveText>
          </p>
        </div>
        <div className="stat">
          <h2>{stats.revenue}</h2>
          <p>
            <LiveText context="dashboard metric">Total Revenue</LiveText>
          </p>
        </div>
      </div>
    </div>
  );
}

Next Steps​

Now that you understand basic usage:

Troubleshooting​

Translations Not Appearing​

  1. Check browser console for errors
  2. Verify SDK initialization
  3. Test API keys with the demo
  4. Check network requests in dev tools

Slow Performance​

  1. Monitor cache hit rates
  2. Avoid translating dynamic content
  3. Use consistent context and tone
  4. Check for excessive re-renders

Need help? Contact our support team or check the troubleshooting guide.