Translate your Expo and React Native app | Internationalisation (i18n)

Table of Contents

Why Intlayer over alternatives?

Compared to main solutions like react-native-localize or i18next, Intlayer is a solution that comes with integrated optimisations such as:

1. 1

   Install Dependencies

   See Application Template on GitHub.

   From your React Native project, install the following packages:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npx intlayer@canary init --interactive    # v9# npx intlayer init                       # v8

   the --interactive flag is optional. Use intlayer-cli init if you're an AI agent.

   This command will detect your environment and install the required packages. For example:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer react-native-intlayer

   Packages

   • intlayer
     The core i18n toolkit for configuration, dictionary content, types generation, and CLI commands.

   • react-native-intlayer
     React Native integration that provides the context providers and React hooks you'll use to obtain and switch locales, the React Native polyfills, and the Metro plugin for integrating Intlayer with the React Native bundler. It re-exports everything from react-intlayer, so you only need this single package in a React Native app.

   ---

2. 2

   Create an Intlayer Config

   In your project root (or anywhere convenient), create an Intlayer config file. It might look like this:

   intlayer.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   /**
    * If Locales types is not available, try to set moduleResolution to "bundler" in your tsconfig.json
    */
   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // ... Add any other locales you need
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Within this config, you can:

   • Configure your list of supported locales.
   • Set a default locale.
   • Later, you may add more advanced options (e.g., logs, custom content directories, etc.).
   • See the Intlayer configuration docs for more.
3. 3

   Add the Metro plugin

   Metro is a bundler for React Native. It is the default bundler for React Native projects created with the react-native init command. To use Intlayer with Metro, you need to add the plugin to your metro.config.js file:

   metro.config.js

   Copy content

   Copy code

   Copy the code to the clipboard

   const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => {  const defaultConfig = getDefaultConfig(__dirname);  return await configMetroIntlayer(defaultConfig);})();

   Note: configMetroIntlayer is a promise function. Use configMetroIntlayerSync instead if you want to use it synchronously, or avoid IFFE (Immediately Invoked Function Expression). Note: configMetroIntlayerSync does not allow building intlayer dictionaries on server start.

4. 4

   Add the Intlayer provider

   To keep the user language synchronised across your application, you need to wrap your root component with the IntlayerProvider component from react-native-intlayer.

   Always import from react-native-intlayer. Its IntlayerProvider includes polyfills for the web API used by Intlayer, and the package re-exports all the hooks and utilities from react-intlayer.

   Also, you need to add the intlayerPolyfill function to your index.js file to ensure that Intlayer can work properly.

   app/_layout.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Stack } from "expo-router";
   import { getLocales } from "expo-localization";
   import { IntlayerProvider } from "react-native-intlayer";
   import { type FC } from "react";
   
   const getDeviceLocale = () => getLocales()[0]?.languageTag;
   
   const RootLayout: FC = () => {
     return (
       <IntlayerProvider defaultLocale={getDeviceLocale()}>
         <Stack>
           <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
         </Stack>
       </IntlayerProvider>
     );
   };
   
   export default RootLayout;

5. 5

   Declare Your Content

   Create content declaration files anywhere in your project (commonly within src/), using any of the extension formats that Intlayer supports:

   • .content.json
   • .content.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • etc.

   Expo Router (web): keep .content.* files out of the app/ directory. Expo Router treats every JavaScript/TypeScript file inside app/ as a route. On web, its route discovery scans the filesystem directly and does not honour Metro's resolver.blockList, so a co-located *.content.ts is registered as a route. A file such as app/(tabs)/_layout.content.ts is even parsed as a layout (the .content part is read as a platform suffix), which collides with the real _layout.tsx and throws:

   plaintext

   Copy content

   Copy code

   Copy the code to the clipboard

   The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.

   Place your declarations in a directory outside app/ (for example content/ or src/content/). Intlayer discovers .content.* files anywhere in the project and dictionaries are referenced by their key, so no import changes are needed. On native this is not required (Metro's blockList already hides them), but using a non-app/ directory keeps both platforms working.

   Example (TypeScript with TSX nodes for React Native):

   src/app.content.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   /**
    * Content dictionary for our "app" domain
    */
   import { t, type Dictionary } from "intlayer";
   
   const homeScreenContent = {
     key: "home-screen",
     content: {
       title: t({
         "en-GB": "Welcome!",
         en: "Welcome!",
         fr: "Bienvenue!",
         es: "¡Bienvenido!",
       }),
     },
   } satisfies Dictionary;
   
   export default homeScreenContent;

   For details on content declarations, see Intlayer's content docs.

   ---

6. 6

   Use Intlayer in Your Components

   Use the useIntlayer hook in child components to obtain localised content.

   Example

   app/(tabs)/index.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Image, StyleSheet, Platform } from "react-native";
   import { useIntlayer } from "react-native-intlayer";
   import { HelloWave } from "@/components/HelloWave";
   import ParallaxScrollView from "@/components/ParallaxScrollView";
   import { ThemedText } from "@/components/ThemedText";
   import { ThemedView } from "@/components/ThemedView";
   import { type FC } from "react";
   
   const HomeScreen = (): FC => {
     const { title, steps } = useIntlayer("home-screen");
   
     return (
       <ParallaxScrollView
         headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
         headerImage={
           <Image
             source={require("@/assets/images/partial-react-logo.png")}
             style={styles.reactLogo}
           />
         }
       >
         <ThemedView style={styles.titleContainer}>
           <ThemedText type="title">{title}</ThemedText>
           <HelloWave />
         </ThemedView>
       </ParallaxScrollView>
     );
   };
   
   const styles = StyleSheet.create({
     titleContainer: {
       flexDirection: "row",
       alignItems: "centre",
       gap: 8,
     },
   });
   
   export default HomeScreen;

   When using content.someKey in string-based props (e.g., a button's title or a Text component's children), call content.someKey.value to obtain the actual string.

   If your app already exists, you can use the Intlayer Compiler, as well as the extract command, to transform thousands of components in a second.

   ---

7. 7

   Change the App Locale

   Optional

   To switch locales from within your components, you can use the useLocale hook's setLocale method:

   src/components/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { type FC } from "react";
   import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-native-intlayer";
   
   export const LocaleSwitcher: FC = () => {
     const { setLocale, availableLocales } = useLocale();
   
     return (
       <View style={styles.container}>
         {availableLocales.map((locale) => (
           <TouchableOpacity
             key={locale}
             style={styles.button}
             onPress={() => setLocale(locale)}
           >
             <Text style={styles.text}>{getLocaleName(locale)}</Text>
           </TouchableOpacity>
         ))}
       </View>
     );
   };
   
   const styles = StyleSheet.create({
     container: {
       flexDirection: "row",
       justifyContent: "center",
       alignItems: "center",
       gap: 8,
     },
     button: {
       paddingVertical: 6,
       paddingHorizontal: 12,
       borderRadius: 6,
       backgroundColor: "#ddd",
     },
     text: {
       fontSize: 14,
       fontWeight: "500",
       colour: "#333",
     },
   });

   This triggers a re-render of all components that use Intlayer content, now showing translations for the new locale.

   See useLocale docs for more details.

Configure TypeScript (if you use TypeScript)

Intlayer generates type definitions in a hidden folder (by default .intlayer) to improve autocompletion and catch translation errors:

// tsconfig.json{  // ... your existing TS config  "include": [    "src", // your source code    ".intlayer/types/**/*.ts", // <-- ensure the auto-generated types are included    // ... anything else you already include  ],}

This enables features such as:

• Autocompletion for your dictionary keys.
• Type checking that warns if you access a non-existent key or have a type mismatch.

Git Configuration

To prevent committing auto-generated files by Intlayer, add the following to your .gitignore:

# Ignore the files generated by Intlayer.intlayer

VS Code Extension

To enhance your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

• Visual Editor: Use the Intlayer Visual Editor to manage translations visually.
• CMS Integration: You can also externalise and fetch your dictionary content from a CMS.
• CLI Commands: Explore the Intlayer CLI for tasks like extracting translations or checking missing keys.

Enjoy building your React Native apps with fully powered i18n through Intlayer!

Debug

React Native can be less stable than React Web, so pay extra attention to version alignment.

Intlayer primarily targets the Web Intl API; on React Native you must include the appropriate polyfills.

Checklist:

• Use the latest versions of intlayer and react-native-intlayer.
• Enable the Intlayer polyfill.
• If you use getLocaleName or other Intl-API-based utilities, import these polyfills early (for example in index.js or App.tsx):

import "intl";import "@formatjs/intl-getcanonicallocales/polyfill";import "@formatjs/intl-locale/polyfill";import "@formatjs/intl-pluralrules/polyfill";import "@formatjs/intl-displaynames/polyfill";import "@formatjs/intl-listformat/polyfill";import "@formatjs/intl-numberformat/polyfill";import "@formatjs/intl-relativetimeformat/polyfill";import "@formatjs/intl-datetimeformat/polyfill";

• Verify your Metro configuration (resolver aliases, asset plugins, tsconfig paths) if modules fail to resolve.