Expo Preset

Use-case guide: See the Expo translation workflow → for a step-by-step setup focused on shipping faster.

The Expo preset helps you set up internationalization (i18n) in your Expo project with minimal configuration. It integrates with Expo's localization system and sets up all necessary files and configurations for managing translations.

Prerequisites

  • ◇An Expo project
  • ◇Git initialized repository
  • ◇Node.js and npm/yarn/pnpm

Getting Started

  1. ◇Navigate to your Expo project root and run:
Terminal
npx @babely/cli@latest init --preset expo
  1. ◇Configure your source and target languages when prompted, or create a babely.json file:
babely.json
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr"]
  }
}

What Gets Set Up

The preset will:

  1. ◇

    Install required dependencies:

    • ◇i18n-js - For handling translations
    • ◇expo-localization - For detecting device locale
  2. ◇

    Create the following directory structure:

    Structure
    locales/
├── i18n.ts           # i18n configuration
├── en.json           # Source language translations
├── [lang].json       # Target language translations
├── native/          # App metadata translations
│   ├── en.json
│   └── [lang].json
└── README.md        # Usage instructions
  3. ◇

    Configure your app.json for localization support:

    • ◇Enables mixed localizations for iOS
    • ◇Adds expo-localization plugin
    • ◇Sets up native localization paths

Usage

Basic Translation

Import the i18n instance in your components:

src/components/MyComponent.tsx
import i18n from './locales/i18n';

function Welcome() {
  return <Text>{i18n.t('welcome')}</Text>;
}

Translation Files

The preset creates two types of translation files:

  1. ◇

    Regular translations (locales/[lang].json):

    locales/[lang].json
    {
  "welcome": "Welcome to my app",
  "hello": "Hello",
  "settings": "Settings"
}
  2. ◇

    Native translations (locales/native/[lang].json):

    locales/native/[lang].json
    {
  "CFBundleDisplayName": "My App",
  "NSContactsUsageDescription": "We need access to contacts..."
}

Managing Translations

  1. ◇Add new translation keys to your source language file (locales/[source].json)
  2. ◇Run the translation command:
    Terminal
    npx @babely/cli@latest translate

Best Practices

  1. ◇Always use translation keys in your code instead of hardcoded strings
  2. ◇Keep translation keys organized and descriptive
  3. ◇Use the native translations for app store metadata and system permissions
  4. ◇Commit translation files to version control

Troubleshooting

  • ◇

    If you see missing translations, check that:

    • ◇The translation key exists in the source language file
    • ◇You've run babely translate after adding new keys
    • ◇The i18n.locale is set correctly
  • ◇

    If native translations aren't working:

    • ◇Verify your app.json configuration
    • ◇Rebuild your app after making changes to native translation files

Additional Configuration

The preset supports customization through the babely.json file:

babely.json
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr"]
  },
  "files": {
    "json": {
      "include": [
        "locales/native/[locale].json",
        "locales/[locale].json"
      ]
    }
  }
}

For more advanced configuration options, refer to the Babely configuration documentation.

VercelJSON