Ask your question and get a summary of the document by referencing this page and the AI provider of your choice
By integrating the Intlayer MCP Server to your favourite AI assistant can retrieve all the doc directly from ChatGPT, DeepSeek, Cursor, VSCode, etc.
See MCP Server docThe content of this page was translated using an AI.
See the last version of the original content in EnglishIf you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.
GitHub link to the documentationCopy doc Markdown to clipboard
Getting Started Internationalising (i18n) with Intlayer and React Native
See Application Template on GitHub.
What is Intlayer?
Intlayer is an innovative, open-source internationalisation (i18n) library that simplifies multilingual support in modern applications. It works in many JavaScript/TypeScript environments, including React Native (via the react-intlayer package).
With Intlayer, you can:
- Easily manage translations using declarative dictionaries at the component level.
- Ensure TypeScript support with autogenerated types.
- Dynamically localise content, including UI strings (and in React for web, it can also localise HTML metadata, etc.).
- Benefit from advanced features, like dynamic locale detection and switching.
Step 1: Install Dependencies
From your React Native project, install the following packages:
Copy the code to the clipboard
npm install intlayer react-intlayernpm install --save-dev react-native-intlayer
Packages
intlayer
The core i18n toolkit for configuration, dictionary content, types generation, and CLI commands.react-intlayer
React integration that provides the context providers and React hooks you’ll use in React Native for obtaining and switching locales.react-native-intlayer
React Native integration that provides the Metro plugin for integrating Intlayer with the React Native bundler.
Step 2: Create an Intlayer Config
In your project root (or anywhere convenient), create an Intlayer config file. It might look like this:
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.
Step 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:
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);})();
Step 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-intlayer.
Additionally, you need to add the intlayerPolyfill function to your index.js file to ensure that Intlayer functions correctly.
Copy the code to the clipboard
import { Stack } from "expo-router";import { getLocales } from "expo-localization";import { IntlayerProviderContent } from "react-intlayer";import { intlayerPolyfill } from "react-native-intlayer";import { type FC } from "react";intlayerPolyfill();const getDeviceLocale = () => getLocales()[0]?.languageTag;const RootLayout: FC = () => { return ( <IntlayerProviderContent defaultLocale={getDeviceLocale()}> <Stack> <Stack.Screen name="(tabs)" options={{ headerShown: false }} /> </Stack> </IntlayerProviderContent> );};export default RootLayout;
Step 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.ts
- .content.tsx
- .content.js
- .content.jsx
- .content.mjs
- .content.mjx
- .content.cjs
- .content.cjx
- etc.
Example (TypeScript with TSX nodes for React Native):
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.
Step 4: Use Intlayer in Your Components
Use the useIntlayer hook in child components to obtain localised content.
Example
Copy the code to the clipboard
import { Image, StyleSheet, Platform } from "react-native";import { useIntlayer } from "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.
(Optional) Step 5: Change the App Locale
To switch locales from within your components, you can use the useLocale hook’s setLocale method:
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-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 displaying 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:
Copy the code to the clipboard
// 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:
Copy the code to the clipboard
# 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!
Doc History
- 5.5.10 - 2025-06-29: Init history