React Native SDK - Quick Start Guide

Prerequisites

React Native 0.60+
iOS 10.0+ / Android API 21+
Node.js 14+
A GetTranslated account and API key

Step 1: Installation

Install the SDK and its dependencies:

npm install @gettranslated/react-native-sdk
# or
yarn add @gettranslated/react-native-sdk

For iOS, install native dependencies:

cd ios && pod install

Step 2: Basic Setup

The SDK provides two translation methods:

t() - For bundled/extracted resources (strings known at build time) - Primary method
getDynamicTranslation() - For dynamic strings (server-side messages, user-generated content, etc.)

Option A: TranslationProvider with t() (Recommended)

Use t() with extracted translation resources for your UI strings. These resources are generated by the GetTranslated CLI and bundled with your app:

import React from 'react';
import { View, Text, Button } from 'react-native';
import { TranslationProvider, useTranslation } from '@gettranslated/react-native-sdk';

// Load your extracted translation resources (generated by CLI)
import enTranslations from './src/i18n/locales/en.json';
import esTranslations from './src/i18n/locales/es.json';
import frTranslations from './src/i18n/locales/fr.json';

const resources = {
  en: { translation: enTranslations },
  es: { translation: esTranslations },
  fr: { translation: frTranslations },
};

// Wrap your app
export default function App() {
  return (
    <TranslationProvider apiKey="your-ck-api-key" resources={resources}>
      <MainScreen />
    </TranslationProvider>
  );
}

// Use translations in components - t() is synchronous, no async/await needed!
function MainScreen() {
  const { t, changeLanguage, currentLanguage } = useTranslation();

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text style={{ fontSize: 24, marginBottom: 20 }}>{t('Welcome')}</Text>
      <Text style={{ fontSize: 18, marginBottom: 20 }}>{t('Hello, !', { name: 'John' })}</Text>
      <Text style={{ fontSize: 16, marginBottom: 20 }}>{t('item_count', { count: 5 })}</Text>
      <Button title={t('Switch Language')} onPress={() => changeLanguage('es')} />
    </View>
  );
}

💡 Tip: Use the GetTranslated CLI to extract and sync your translation resources. Run translate sync to generate en.json, es.json, etc. files that you can import into your app.

📁 Multiple Language Files (Namespaces): The SDK supports organizing translations into multiple namespaces (e.g., translation, currencies, errors). Access them using namespace:key syntax (e.g., t('currencies:usd')) or the ns option. See the Complete Integration Guide for detailed documentation on using multiple namespaces.

Pluralization Format

The SDK supports i18next's structured plural object format. Define plurals in your JSON files using a structured object:

// en.json
{
  "item_count": {
    "zero": "No items",
    "one": " item",
    "other": " items"
  }
}

Then use it in your code:

<Text>{t('item_count', { count: 5 })}</Text>
// Result: "5 items" (automatically selects correct plural form)

Supported plural quantities: zero, one, two, few, many, other (always required as fallback).

See the Complete Integration Guide for detailed pluralization documentation.

Dynamic Translations (Advanced Use Case)

Use getDynamicTranslation() for strings that aren't known at build time, such as server-side error messages or user-generated content:

function ErrorScreen({ errorMessage }) {
  const { getDynamicTranslation } = useTranslation();
  const [translatedError, setTranslatedError] = React.useState(errorMessage);

  React.useEffect(() => {
    const translateError = async () => {
      // Translate server-side error message (not in bundled resources)
      const translation = await getDynamicTranslation(errorMessage);
      setTranslatedError(translation);
    };
    translateError();
  }, [errorMessage]);

  return (
    <View>
      <Text style={{ color: 'red' }}>{translatedError}</Text>
    </View>
  );
}

When to use each method:

t() - Use for all UI strings, button labels, screen titles, etc. (extracted via CLI and bundled into your app)
getDynamicTranslation() - Use only for dynamic content like API error messages, user-generated text, or content from external sources

Option B: Static Methods

For direct SDK access without React context:

import GetTranslated from '@gettranslated/react-native-sdk';

// Load extracted resources
import enTranslations from './locales/en.json';
import esTranslations from './locales/es.json';

const resources = {
  en: { translation: enTranslations },
  es: { translation: esTranslations }
};

// Initialize with resources
await GetTranslated.init('your-ck-api-key', undefined, undefined, resources);

// In React components - use t() from hook (preferred)
function MyComponent() {
  const { t } = useTranslation();
  return (
    <View>
      <Text>{t('Welcome')}</Text>
      <Text>{t('Hello, !', { name: 'John' })}</Text>
    </View>
  );
}

// Static method (for utility functions outside components)
const greeting = GetTranslated.t('Welcome');

// Use getDynamicTranslation() for dynamic strings (async)
const serverError = await GetTranslated.getDynamicTranslation('Connection timeout');

// Optional: Change language (only if implementing a language selector)
// Note: The SDK automatically sets language based on system preferences
await GetTranslated.setLanguage('es');

Automatic Language Detection: The SDK automatically sets the application language during initialization based on system preferences and saved overrides. You do not need to manually set the language unless you want to implement a custom language selector.

Step 3: Test Your Integration

Run your app: npx react-native run-ios or npx react-native run-android
Check the console: Look for GetTranslated initialization messages
Test language switching: Tap the "Switch Language" button. You can also set language overrides on a per-user basis from your project's User Overrides settings in the GetTranslated dashboard.
Verify translations: Text should change between languages

Step 4: Add More Features

Using t() with Extracted Resources

The t() function works with your extracted translation resources. It's synchronous, so no async/await is needed:

function MyComponent() {
  const { t } = useTranslation();

  return (
    <View>
      {/* Simple translation */}
      <Text>{t('Welcome')}</Text>
      
      {/* With interpolation */}
      <Text>{t('Hello, !', { name: 'John' })}</Text>
      
      {/* With count/pluralization */}
      <Text>{t(' items', { count: 5 })}</Text>
      
      {/* In button titles */}
      <Button title={t('Submit')} onPress={handleSubmit} />
    </View>
  );
}

User Authentication

const { login } = useTranslation();

const handleLogin = async () => {
  await login('user-123');
  console.log('User logged in!');
};

Error Handling

<TranslationProvider
  apiKey="your-ck-api-key"
  resources={resources}
  onError={(error) => {
    console.error('Translation error:', error);
    Alert.alert('Error', 'Translation failed');
  }}
>
  <App />
</TranslationProvider>

Debug Logging

import { LogLevel } from '@gettranslated/react-native-sdk';

// Enable debug logging
<TranslationProvider
  apiKey="your-ck-api-key"
  logLevel={LogLevel.DEBUG}
  resources={resources}
>
  <App />
</TranslationProvider>

// Or for static initialization
await GetTranslated.init('your-ck-api-key', undefined, LogLevel.DEBUG);

Multiple Translations

const loadMultipleTranslations = async () => {
  const [welcome, goodbye, thanks] = await Promise.all([
    getDynamicTranslation('Welcome!'),
    getDynamicTranslation('Goodbye!'),
    getDynamicTranslation('Thank you!')
  ]);
  
  setTexts({ welcome, goodbye, thanks });
};

Common Issues & Solutions

❌ "useTranslation must be used within a TranslationProvider"

Solution: Wrap your component with TranslationProvider

❌ Translations not showing

Solution: Check that isInitialized is true before calling getDynamicTranslation

❌ iOS build fails

Solution: Run cd ios && pod install after installing the SDK

❌ Android build fails

Solution: Clean and rebuild: npx react-native clean && npx react-native run-android

❌ Debug logs not appearing

Solution: Debug logs use console.log for better visibility. If you still don't see logs:

Clear Metro cache: npx expo start --clear
Use LogLevel.DEBUG enum (not string)
Check browser console settings

Additional Options

withTranslations HOC (for Class Components)

If you're using class components, you can use the withTranslations HOC:

import React from 'react';
import { View, Text, Button } from 'react-native';
import { withTranslations, TranslationProvider } from '@gettranslated/react-native-sdk';

// Class component using HOC
class MyComponent extends React.Component {
  render() {
    const { t } = this.props;
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Text style={{ fontSize: 24, marginBottom: 20 }}>
          {t('Hello, World!')}
        </Text>
        <Text style={{ fontSize: 16, marginBottom: 20 }}>
          {t('Welcome, !', { name: 'John' })}
        </Text>
        <Button title={t('Switch Language')} onPress={() => console.log('Language switch')} />
      </View>
    );
  }
}

// Wrap component with HOC
const TranslatedComponent = withTranslations(MyComponent);

// Use in your app
export default function App() {
  return (
    <TranslationProvider apiKey="your-ck-api-key">
      <TranslatedComponent />
    </TranslationProvider>
  );
}

Next Steps

📖 Complete Integration Guide 🔄 Migration from react-i18next 📦 NPM Package

Need Help?

📧 Email: [email protected]

📖 Docs: Full Documentation

License

This SDK is licensed under the MIT License.