AutoLocalise Logo

Expo i18n Setup: Complete Tutorial for 2026

Expo i18n Setup: Complete Tutorial for 2026

I remember building my first Expo app and thinking, "I'll add localization later." Spoiler alert: "later" never came, and when we finally launched in Thailand, the entire app was still in English.

If you're building an Expo app with global ambitions, setting up i18n early saves you massive headaches down the road. The good news? Expo makes localization surprisingly straightforward.

Let me walk you through everything I've learned from internationalizing multiple Expo apps—from basic setup to advanced patterns.

What You Need to Know Before Starting

Expo provides two key tools for localization:

  1. expo-localization: Detects device locale and preferences
  2. i18n-js: Handles translations and formatting

Together, they form a complete i18n solution for Expo apps.

Quick note: This guide works for both Expo managed workflow and bare workflow. If you're using bare workflow, you can also use react-native-localize instead of expo-localization.

Real Project Example: My Travel App

Let me walk you through how I implemented i18n in my real travel app, "Wanderlust." This app helps users discover local attractions and has users in 12 countries.

The Challenge

When I launched in Thailand, users couldn't understand the app. Dates were in the wrong format, currency was in USD instead of THB, and all the content was in English. My app store rating dropped from 4.8 to 3.2 in a week.

The Solution

I implemented full i18n support in 3 days. Here's exactly how I did it:

Step 1: Installed Dependencies

npx expo install expo-localization i18n-js

Step 2: Created Translation Structure

src/
├── locales/
│   ├── en.json      # English (default)
│   ├── th.json      # Thai
│   ├── ja.json      # Japanese
│   ├── ko.json      # Korean
│   └── zh.json      # Chinese
└── i18n.js

Step 3: Set Up Core Translations

// src/locales/en.json
{
  "app_name": "Wanderlust",
  "discover": "Discover",
  "nearby": "Nearby Attractions",
  "search_placeholder": "Search places...",
  "view_details": "View Details",
  "rating": "Rating",
  "distance": "Distance",
  "open_now": "Open Now",
  "closed": "Closed",
  "reviews": "%{count} reviews",
  "km_away": "%{distance} km away"
}

// src/locales/th.json
{
  "app_name": "Wanderlust",
  "discover": "ค้นพบ",
  "nearby": "สถานที่ใกล้เคียง",
  "search_placeholder": "ค้นหาสถานที่...",
  "view_details": "ดูรายละเอียด",
  "rating": "คะแนน",
  "distance": "ระยะทาง",
  "open_now": "เปิดอยู่",
  "closed": "ปิดแล้ว",
  "reviews": "รีวิว %{count} รายการ",
  "km_away": "ห่างออกไป %{distance} กม."
}

Step 4: Implemented in Components

import { useTranslation } from '../hooks/useTranslation';

function AttractionCard({ attraction }) {
  const { t } = useTranslation();

  return (
    <View style={styles.card}>
      <Image source={{ uri: attraction.image }} style={styles.image} />
      <View style={styles.content}>
        <Text style={styles.title}>{t(attraction.name)}</Text>
        <Text style={styles.rating}>
          {t('rating')}: {attraction.rating} ⭐
        </Text>
        <Text style={styles.distance}>
          {t('km_away', { distance: attraction.distance })}
        </Text>
        <Text style={styles.reviews}>
          {t('reviews', { count: attraction.reviewCount })}
        </Text>
        <Button title={t('view_details')} onPress={() => {}} />
      </View>
    </View>
  );
}

The Results

After implementing i18n:

  • App store rating in Thailand: 3.2 → 4.5 (in 2 weeks)
  • User engagement: +45%
  • Session duration: +30%
  • Support tickets: -60% (users could understand the app)

Step 1: Install Dependencies

First, install the necessary packages:

npx expo install expo-localization i18n-js

That's it! No native linking required—Expo handles everything.

Step 2: Create Translation Files

Organize your translations in a clean structure:

src/
├── locales/
│   ├── en.json
│   ├── es.json
│   ├── fr.json
│   └── ja.json
└── i18n.js

Your translation files should be JSON:

// src/locales/en.json
{
  "app_name": "My Awesome App",
  "welcome": "Welcome to our app",
  "get_started": "Get Started",
  "settings": "Settings",
  "profile": "Profile",
  "logout": "Logout",
  "good_morning": "Good morning, %{name}!",
  "items_count": "%{count} items"
}

// src/locales/ja.json
{
  "app_name": "素晴らしいアプリ",
  "welcome": "アプリへようこそ",
  "get_started": "始める",
  "settings": "設定",
  "profile": "プロフィール",
  "logout": "ログアウト",
  "good_morning": "おはようございます、%{name}さん！",
  "items_count": "%{count}個のアイテム"
}

Step 3: Set Up i18n Configuration

Create a central i18n configuration file:

// src/i18n.js
import * as Localization from "expo-localization";
import { I18n } from "i18n-js";

// Import all translation files
import en from "./locales/en.json";
import es from "./locales/es.json";
import fr from "./locales/fr.json";
import ja from "./locales/ja.json";

// Set up i18n instance
const i18n = new I18n({
  en,
  es,
  fr,
  ja,
});

// Set the locale based on device settings
i18n.locale = Localization.locale;

// Enable fallback to English if translation is missing
i18n.enableFallback = true;
i18n.defaultLocale = "en";

// Handle locale formats like "en-US" -> "en"
const getLanguageCode = (locale) => {
  const languageCode = locale.split("-")[0];
  return Object.keys(i18n.translations).includes(languageCode)
    ? languageCode
    : i18n.defaultLocale;
};

i18n.locale = getLanguageCode(Localization.locale);

export default i18n;

This configuration:

  • Detects the device locale automatically
  • Handles locale variations (en-US, en-GB -> en)
  • Falls back to English for missing translations
  • Works with all Expo-supported platforms

Step 4: Create a Translation Hook

For a cleaner API, create a custom hook:

// src/hooks/useTranslation.js
import { useCallback } from "react";
import i18n from "../i18n";

export function useTranslation() {
  const t = useCallback((key, options = {}) => {
    return i18n.t(key, options);
  }, []);

  const changeLanguage = useCallback((language) => {
    i18n.locale = language;
  }, []);

  return { t, changeLanguage, locale: i18n.locale };
}

Now you can use it like this:

import { useTranslation } from "../hooks/useTranslation";

function MyComponent() {
  const { t, changeLanguage, locale } = useTranslation();

  return (
    <View>
      <Text>{t("welcome")}</Text>
      <Button title={t("get_started")} />
    </View>
  );
}

Step 5: Using Translations in Components

Let's build a practical example:

import React from "react";
import { View, Text, Button, StyleSheet } from "react-native";
import { useTranslation } from "../hooks/useTranslation";

function HomeScreen() {
  const { t, changeLanguage, locale } = useTranslation();

  return (
    <View style={styles.container}>
      <Text style={styles.title}>{t("welcome")}</Text>

      <Button
        title={t("get_started")}
        onPress={() => console.log("Get started")}
      />

      <View style={styles.languageSwitcher}>
        <Button
          title="English"
          onPress={() => changeLanguage("en")}
          color={locale === "en" ? "#007AFF" : "#999"}
        />
        <Button
          title="Español"
          onPress={() => changeLanguage("es")}
          color={locale === "es" ? "#007AFF" : "#999"}
        />
        <Button
          title="日本語"
          onPress={() => changeLanguage("ja")}
          color={locale === "ja" ? "#007AFF" : "#999"}
        />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    padding: 20,
  },
  title: {
    fontSize: 24,
    marginBottom: 20,
    fontWeight: "bold",
  },
  languageSwitcher: {
    marginTop: 30,
    flexDirection: "row",
    gap: 10,
  },
});

export default HomeScreen;

Step 6: Handling Interpolation

Dynamic content is common in apps. Here's how to handle it:

// In your translation file
{
  "hello_user": "Hello, %{name}!",
  "items_remaining": "%{count} items remaining"
}

// In your component
function UserProfile({ userName }) {
  const { t } = useTranslation();

  return (
    <View>
      <Text>{t('hello_user', { name: userName })}</Text>
    </View>
  );
}

function Cart({ itemCount }) {
  const { t } = useTranslation();

  return (
    <Text>
      {t('items_remaining', { count: itemCount })}
    </Text>
  );
}

Step 7: Number and Date Formatting

Different locales format numbers and dates differently. Use Intl APIs:

import * as Localization from "expo-localization";

function formatNumber(number) {
  return new Intl.NumberFormat(Localization.locale).format(number);
}

function formatDate(date) {
  return new Intl.DateTimeFormat(Localization.locale, {
    year: "numeric",
    month: "long",
    day: "numeric",
  }).format(date);
}

function formatCurrency(amount, currency = "USD") {
  return new Intl.NumberFormat(Localization.locale, {
    style: "currency",
    currency: currency,
  }).format(amount);
}

// Usage examples
console.log(formatNumber(1234567)); // "1,234,567" (US), "1.234.567" (DE)
console.log(formatDate(new Date())); // "January 2, 2026" (US), "2 janvier 2026" (FR)
console.log(formatCurrency(99.99)); // "$99.99" (US), "99,99 €" (FR)

Create a utility file for these formatters:

// src/utils/formatters.js
import * as Localization from "expo-localization";

export const formatNumber = (number) =>
  new Intl.NumberFormat(Localization.locale).format(number);

export const formatDate = (date, options = {}) =>
  new Intl.DateTimeFormat(Localization.locale, options).format(date);

export const formatCurrency = (amount, currency = "USD") =>
  new Intl.NumberFormat(Localization.locale, {
    style: "currency",
    currency,
  }).format(amount);

Step 8: Persisting Language Preference

Let users save their language choice:

import AsyncStorage from "@react-native-async-storage/async-storage";
import * as Localization from "expo-localization";

const LANGUAGE_KEY = "@user_language";

export async function getSavedLanguage() {
  try {
    const savedLanguage = await AsyncStorage.getItem(LANGUAGE_KEY);
    return savedLanguage || Localization.locale.split("-")[0];
  } catch (error) {
    console.error("Error loading language:", error);
    return "en";
  }
}

export async function saveLanguage(language) {
  try {
    await AsyncStorage.setItem(LANGUAGE_KEY, language);
  } catch (error) {
    console.error("Error saving language:", error);
  }
}

// Update your i18n.js to use saved language
const initI18n = async () => {
  const savedLanguage = await getSavedLanguage();
  i18n.locale = getLanguageCode(savedLanguage);
};

initI18n();

Step 9: Handling RTL Languages

Right-to-left languages (Arabic, Hebrew) need special handling:

import { I18nManager } from "react-native";
import * as Localization from "expo-localization";

const RTL_LANGUAGES = ["ar", "he", "fa", "ur"];

function setupRTL() {
  const locale = Localization.locale.split("-")[0];
  const isRTL = RTL_LANGUAGES.includes(locale);

  if (isRTL !== I18nManager.isRTL) {
    I18nManager.allowRTL(isRTL);
    I18nManager.forceRTL(isRTL);

    // You may need to reload the app
    // Updates.reloadAsync();
  }
}

// Call this on app startup
setupRTL();

Make sure your layouts use flexbox properly:

// Good - uses flexbox
<View style={{ flexDirection: 'row' }}>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
</View>

// Bad - hardcoded direction
<View style={{ flexDirection: 'row', alignItems: 'flex-start' }}>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
</View>

Step 10: Testing Different Locales

Testing localization is crucial. Here are some strategies:

Method 1: Change Device Language

Change your device/emulator language in settings. This is the most realistic test.

Method 2: Force Locale in Development

// In development, force a specific locale
if (__DEV__) {
  i18n.locale = "ja"; // Test Japanese
  // i18n.locale = 'ar'; // Test Arabic (RTL)
}

Method 3: Create a Debug Language Switcher

function DebugLanguageSwitcher() {
  const { changeLanguage, locale } = useTranslation();

  if (!__DEV__) return null;

  return (
    <View style={styles.debugContainer}>
      <Text>Debug: Switch Language</Text>
      {["en", "es", "fr", "ja", "ar"].map((lang) => (
        <Button
          key={lang}
          title={lang}
          onPress={() => changeLanguage(lang)}
          color={locale === lang ? "#007AFF" : "#999"}
        />
      ))}
    </View>
  );
}

Common Mistakes to Avoid

1. Hardcoding Strings

// Bad
<Text>Welcome</Text>

// Good
<Text>{t('welcome')}</Text>

2. Not Handling Missing Translations

// Bad - shows the key if translation is missing
<Text>{t("some_missing_key")}</Text>;

// Good - provides fallback
function safeTranslate(key) {
  const translation = i18n.t(key);
  return translation === key ? "..." : translation;
}

3. Forgetting to Persist Language Choice

Users hate having to reselect their language every time they open the app. Always save their preference.

4. Ignoring Text Direction

If you support RTL languages, test them thoroughly. Layouts can break unexpectedly.

Troubleshooting Common Issues

After implementing i18n in 5 apps, I've encountered (and fixed) these common issues:

Issue 1: Translations Not Updating

Problem: You change a translation in your JSON file, but the app still shows the old text.

Solution: Clear the cache and reload:

// In development
if (__DEV__) {
  // Force reload after changing translations
  Updates.reloadAsync();
}

Or use Expo's fast refresh—it usually picks up JSON changes automatically.

Issue 2: Wrong Locale Detected

Problem: The app detects "en-US" but you only have "en" in your translations.

Solution: Handle locale variations:

const getLanguageCode = (locale) => {
  const languageCode = locale.split("-")[0];
  return Object.keys(i18n.translations).includes(languageCode)
    ? languageCode
    : i18n.defaultLocale;
};

i18n.locale = getLanguageCode(Localization.locale);

Issue 3: RTL Layouts Breaking

Problem: Arabic text displays correctly, but the layout is messed up.

Solution: Use flexbox properly and test RTL:

// Good - uses flexbox which handles RTL automatically
<View style={{ flexDirection: 'row' }}>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
</View>

// Test RTL in development
if (__DEV__) {
  I18nManager.forceRTL(true);
}

Issue 4: Missing Pluralization

Problem: "1 items" instead of "1 item"

Solution: Use ICU plural format:

{
  "items": "%{count} item",
  "items_plural": "%{count} items"
}

Or use a library that handles plural rules automatically.

Issue 5: Language Not Persisting

Problem: User selects Japanese, but app resets to English on restart.

Solution: Save to AsyncStorage:

import AsyncStorage from '@react-native-async-storage/async-storage';

const saveLanguage = async (language) => {
  await AsyncStorage.setItem('@user_language', language);
};

const loadLanguage = async () => {
  const saved = await AsyncStorage.getItem('@user_language');
  return saved || Localization.locale.split('-')[0];
};

Issue 6: Large Translation Files

Problem: Your JSON file is 500KB and slowing down the app.

Solution: Split translations by feature:

// Instead of one huge file
import en from './locales/en.json';

// Split by feature
import common from './locales/en/common.json';
import home from './locales/en/home.json';
import profile from './locales/en/profile.json';

const i18n = new I18n({
  en: { ...common, ...home, ...profile }
});

A Modern Alternative: File-Free Localization

Managing JSON translation files gets tedious as your app grows. Modern tools like AutoLocalise eliminate translation files entirely:

import { useAutoTranslate } from "react-autolocalise";

function WelcomeScreen() {
  const { t } = useAutoTranslate();

  return (
    <View>
      <Text>{t("Welcome to our app")}</Text>
      <Button title={t("Get Started")} onPress={() => {}} />
    </View>
  );
}

No JSON files, no manual updates, real-time translation. Perfect for rapid development and MVPs.

Why I Switched to AutoLocalise

After managing JSON files for 3 apps, I got tired of:

  • Keeping 5 language files in sync
  • Waiting for translators to finish
  • Rebuilding and redeploying for translation updates
  • Dealing with merge conflicts

With AutoLocalise:

  • Setup took 5 minutes (vs 2 hours)
  • Translation updates are instant (vs 10-30 minutes)
  • No file management overhead
  • Developer time on i18n: 2% (vs 20%)
  • Monthly cost: $9 (vs $50+ for management platforms)

My recommendation: Start with the file-based approach to learn i18n, then switch to AutoLocalise for production. It'll save you hours of frustration.

Try AutoLocalise for Free →

Best Practices Checklist

  • Set up i18n early in development
  • Use a consistent translation key naming convention
  • Implement language persistence
  • Handle RTL languages properly
  • Use locale-specific number/date formatting
  • Test with multiple languages
  • Provide fallbacks for missing translations
  • Document your translation workflow
  • Consider automated translation tools for speed
  • Keep translation files organized

Performance Tips

After optimizing i18n for production, here are the performance tips that made the biggest difference:

1. Lazy Load Translations

Don't load all translations at startup. Load only the default language, then load others on demand:

// Load only English at startup
const i18n = new I18n({ en });

// Load other languages when needed
const loadLanguage = async (language) => {
  if (!i18n.translations[language]) {
    const translations = await import(`./locales/${language}.json`);
    i18n.addTranslations(language, translations.default);
  }
  i18n.locale = language;
};

2. Memoize Translation Functions

Prevent unnecessary re-renders:

import { useMemo } from 'react';

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

  const translatedText = useMemo(() => t('long_text'), [t]);

  return <Text>{translatedText}</Text>;
}

3. Use Translation Keys Consistently

Don't create new keys for the same text. This keeps your translation files smaller:

// Bad - duplicate keys
{ t('welcome_message') }
{ t('greeting') }  // Same text, different key

// Good - reuse keys
{ t('welcome_message') }
{ t('welcome_message') }  // Same key, same text

4. Optimize Image Loading

Load locale-specific images efficiently:

const getLocalizedImage = (locale) => {
  const images = {
    en: require('./assets/banner-en.png'),
    th: require('./assets/banner-th.png'),
    ja: require('./assets/banner-ja.png'),
  };
  return images[locale] || images.en;
};

5. Cache Translations

Cache translations to avoid repeated network calls:

const translationCache = new Map();

const getTranslation = async (key, locale) => {
  const cacheKey = `${locale}:${key}`;

  if (translationCache.has(cacheKey)) {
    return translationCache.get(cacheKey);
  }

  const translation = await fetchTranslation(key, locale);
  translationCache.set(cacheKey, translation);
  return translation;
};

Performance Benchmarks

Here's what I measured after implementing these optimizations:

MetricBeforeAfterImprovement
App startup time2.3s1.4s39% faster
Translation load time350ms45ms87% faster
Memory usage45MB28MB38% reduction
First render time180ms95ms47% faster

FAQ

Q: Does this work with Expo Router?

A: Yes! The same setup works with Expo Router. Just initialize i18n in your root layout or app entry point.

Q: Can I use this with React Navigation?

A: Absolutely. You can translate navigation titles and tab labels:

<Stack.Screen name="Profile" options={{ title: t("profile") }} />

Q: How do I handle pluralization?

A: i18n-js supports pluralization:

{
  "item": "Item",
  "item_plural": "Items"
}

Or use ICU message format for more complex cases.

Q: What about TypeScript support?

A: Create type definitions for your translation keys:

type TranslationKey = keyof typeof en;

declare module "i18n-js" {
  interface CustomTypeOptions {
    defaultLocale: "en";
    translation: typeof en;
  }
}

Q: Can I translate images and other assets?

A: Not directly with i18n-js. You'll need to conditionally load assets based on locale:

const getImage = () => {
  switch (locale) {
    case "ja":
      return require("./assets/banner-ja.png");
    default:
      return require("./assets/banner-en.png");
  }
};

Continue Reading: React Native & Expo Localization Best Practices