@intlayer/docs 9.4.2 → 9.4.3

package/blog/en/list_i18n_technologies/frameworks/react-native.md

@@ -1,16 +1,16 @@
 ---
 createdAt: 2025-01-16
-updatedAt: 2026-05-31
-title: "React Native i18n 2026: Best Tools for Expo & TypeScript"
-description: Best solution for bundle size, SEO, performances & maintainability. Make your React Native mobile app multilingual in 2026, LLM translation, Agent Skills & MCP.
+updatedAt: 2026-09-02
+title: "React Native i18n: device locale, RTL and Intl gaps"
+description: Mobile i18n is not web i18n. Device locale detection, persisting the user override, the Android RTL restart, Intl polyfills on Hermes, and the library options.
 keywords:
-  - React Native
-  - i18n
-  - multilingual
-  - SEO
-  - Internationalization
-  - Blog
-  - JavaScript
+  - react native i18n
+  - expo localization
+  - react native rtl
+  - I18nManager
+  - expo-localization
+  - Intl polyfill
+  - Hermes
 slugs:
   - blog
   - i18n-technologies
@@ -19,200 +19,179 @@ slugs:
 author: aymericzip
 ---
 
-# Exploring i18n Solutions to Translate Your React Native App
+# React Native i18n: what changes once there is no URL
 
-In an increasingly global market, delivering your React Native app in multiple languages can significantly enhance accessibility and user satisfaction. Internationalization (i18n) is central to managing translations effectively allowing you to display language-specific text, date and time formats, currency, and more without complicating your codebase. In this article, we’ll dive into various i18n approaches ranging from dedicated libraries to more general solutions and help you find the one that best fits your React Native project.
+Most i18n advice is written for the web, and about half of it stops applying the moment you ship a mobile app. There is no URL to carry the locale, no crawler to satisfy, and no server render to get right. What you get instead is a device setting, a user override you have to persist yourself, and a layout direction that will not flip without a reload.
 
----
-
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
-## What is Internationalization (i18n)?
-
-Internationalization, or i18n, involves structuring an application so it can easily adapt to different languages, regional formats, and cultural norms. In React Native, i18n includes handling strings for buttons and labels, as well as formatting dates, times, currencies, and more according to a user’s locale. Properly prepared React Native apps let you seamlessly integrate additional languages and locale-specific behavior later on without massive refactors.
-
-For a deeper dive into internationalization concepts, check out our article:  
-[What is Internationalization (i18n)? Definition and Challenges](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md).
-
----
-
-## The Translation Challenge for React Native Applications
-
-Working with translations in React Native introduces its own unique considerations:
-
-- **Component-Based Architecture**  
-  Just like in React for the web, React Native’s modular design can scatter text across numerous components. It’s crucial to centralize these translations in a robust manner.
-
-- **Offline and Remote Data**  
-  While some strings can be embedded within the app, other content (e.g., newsfeeds, product data) may be fetched remotely. Handling translations for data that arrives asynchronously can be more complex on mobile.
-
-- **Platform-Specific Behaviors**  
-  iOS and Android each have their own locale settings and formatting quirks. Ensuring consistent rendering of dates, currencies, and numbers across both platforms requires thorough testing.
-
-- **State and Navigation Management**  
-  Maintaining the user’s selected language across screens, deep links, or tab-based navigations means tying i18n into your Redux, Context API, or other state management solution.
-
-- **App Updates & Over-the-Air (OTA)**  
-  If you use CodePush or another OTA update mechanism, you need to plan how translation updates or new languages will be delivered without requiring a full app store release.
-
----
-
-## Leading i18n Solutions for React Native
-
-Below are several popular approaches to managing multilingual content in React Native. Each aims to simplify your translation workflow in different ways.
-
-### 1. Intlayer
+## Table of Contents
 
-> Website: [https://intlayer.org/](https://intlayer.org/)
+<TOC/>
 
-**Overview**  
-**Intlayer** is an innovative, open-source internationalization library designed to streamline multilingual support in modern JavaScript apps including React Native. It offers a declarative approach to translation, allowing you to define dictionaries directly alongside components.
+## The four things that are actually different
 
-**Key Features**
+| Web                                | React Native                                           |
+| :--------------------------------- | :----------------------------------------------------- |
+| Locale lives in the URL            | Locale lives in device settings plus a stored override |
+| Crawlers need server-rendered copy | Nobody crawls your app                                 |
+| Catalogs are fetched per route     | Everything ships inside the binary                     |
+| `dir="rtl"` applies immediately    | Full RTL flip needs an app reload                      |
 
-- **Translation Declaration**  
-  Store translations in a single file or at a component level, making it straightforward to locate and modify text.
+The third and fourth rows are where the time goes.
 
-- **TypeScript & Autocompletion**  
-  Automatically generates type definitions for translation keys, providing both developer-friendly autocompletion and robust error checking.
+## Reading the device locale
 
-- **Lightweight & Flexible**  
-  Works gracefully in React Native environments, without unnecessary overhead. Easy to integrate and keep efficient on mobile devices.
+`expo-localization` exposes the device's preferred locales, already sorted by user preference.
 
-- **Platform-Specific Considerations**  
-  You can adapt or separate platform-specific strings for iOS vs. Android, if needed.
+```tsx fileName="src/getDeviceLocale.ts"
+import { getLocales } from "expo-localization";
 
-- **Asynchronous Loading**  
-  Dynamically load translation dictionaries, which can be useful for large apps or incremental language rollout.
+export const getDeviceLocale = () => getLocales()[0]?.languageTag ?? "en";
+```
 
-**Considerations**
+Two mistakes are common here. The first is reading only `languageCode` and losing the region, so `pt-BR` and `pt-PT` collapse into one. The second is trusting the device locale as final. It is a starting value, not a decision: a user whose phone is in German may still want your app in English, and that choice has to survive a restart.
 
-- **Community & Ecosystem**  
-  Still a relatively new solution, so you may find fewer community-driven examples or ready-made plugins compared to long-established libraries.
+So the order of precedence is: stored user override, then device locale, then your default.
 
----
-
-### 2. React-i18next
+```tsx
+const resolveLocale = async () => {
+  const stored = await AsyncStorage.getItem("locale");
+  return stored ?? getDeviceLocale();
+};
+```
 
-> Website: [https://react.i18next.com/](https://react.i18next.com/)
+Persist with `AsyncStorage` or MMKV. MMKV is synchronous, which matters here: an async read before first paint means the app renders once in the wrong language and then corrects itself.
 
-**Overview**  
-**React-i18next** builds on the popular **i18next** framework, offering a flexible, plugin-based architecture and robust feature set. It’s widely used in React Native apps as well, thanks to a well-documented setup process.
+## RTL is the part that surprises people
 
-**Key Features**
+React Native does not flip layout direction reactively. `I18nManager.forceRTL(true)` sets a native flag that only takes effect after the app reloads. On Android there is no way around this.
 
-- **Smooth React Native Integration**  
-  Provides hooks (`useTranslation`), higher-order components (HOCs), and more to integrate i18n seamlessly into your components.
+```tsx
+import { I18nManager } from "react-native";
 
-- **Asynchronous Loading**  
-  Load translations on demand beneficial for large apps or when adding new language packs over time.
+const applyDirection = (isRTL: boolean) => {
+  if (I18nManager.isRTL === isRTL) return;
+  I18nManager.allowRTL(isRTL);
+  I18nManager.forceRTL(isRTL);
+  // Layout will only flip after a reload.
+};
+```
 
-- **Rich Translation Capabilities**  
-  Handle nested translations, interpolation, pluralization, and variable replacements out of the box.
+The practical pattern is to prompt once: the user picks Arabic or Hebrew, you explain the app needs to restart, and you reload with `expo-updates`. Silently calling `forceRTL` and hoping is how you get a half-mirrored screen.
 
-- **TypeScript & Autocompletion**  
-  React-i18next supports typed translation keys, though initial setup may be more manual compared to solutions that autogenerate typings.
+Two follow-ups worth budgeting for. Use `start` and `end` instead of `left` and `right` in styles, or nothing mirrors. And check your icons: chevrons, back arrows and progress indicators need mirroring, while logos and media controls do not.
 
-- **Platform Agnostic**  
-  i18next is not tied to web or mobile specifically, so the same library can be used across different project types (e.g., if you share code between web and native).
+## Intl is not guaranteed
 
-**Considerations**
+Hermes ships `Intl` support now, but coverage depends on the Hermes version and the platform, and older Android builds are where it breaks. If you format plurals, dates, currencies or display names, verify on a real low-end Android device rather than on the simulator.
 
-- **Configuration Complexity**  
-  Setting up i18n with advanced features (plural forms, fallback locales, etc.) can require careful configuration.
+When coverage is missing, polyfill early, before anything reads `Intl`:
 
-- **Performance**  
-  While React-i18next generally performs well, you’ll want to pay attention to how you organize and load translation resources to avoid overhead on mobile devices.
+```ts fileName="index.js"
+import "intl";
+import "@formatjs/intl-getcanonicallocales/polyfill";
+import "@formatjs/intl-locale/polyfill";
+import "@formatjs/intl-pluralrules/polyfill";
+import "@formatjs/intl-numberformat/polyfill";
+```
 
----
+Each polyfill carries locale data, and that data ships in your binary. Import only the ones you use, and only the locales you support.
 
-### 3. React Intl (from FormatJS)
+## Bundle size counts differently
 
-> Website: [https://formatjs.io/docs/react-intl/](https://formatjs.io/docs/react-intl/)
+On the web an unused locale catalog is a chunk that never gets fetched. In an app, it is bytes in the download every user pays for, on every install and every update. App stores also surface the download size, and it affects install conversion on slow networks.
 
-**Overview**  
-**React Intl**, part of the **FormatJS** ecosystem, is built around standardizing message formatting for various locales. It emphasizes a message extraction workflow and is particularly strong in formatting dates, numbers, and times correctly for a wide range of locales.
+This is the strongest argument for a build-time approach on mobile: anything that lets the bundler drop unused keys and unused languages is worth more here than it is on the web. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) for how that works in practice, and the [benchmark reports](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md) for the web equivalents.
 
-**Key Features**
+## Do not forget the store listing
 
-- **Format-Focused Components**  
-  `<FormattedMessage>`, `<FormattedDate>`, `<FormattedTime>`, and others streamline formatting tasks across iOS and Android.
+Translating the app and shipping an English App Store page is a common miss. Both stores support localized metadata: title, subtitle, description, keywords and screenshots, per locale. That listing is the only part of a mobile app that behaves like a web page for discovery, so it is worth the same care as the app itself.
 
-- **Lightweight & Extensible**  
-  You can import just the parts of FormatJS you need, keeping your overall bundle lean crucial for mobile.
+## The options
 
-- **Polyfills for Unsupported Locales**  
-  Ensures consistent date/number formatting on older Android or iOS versions.
+| Library                         | Model                                    | Typed keys                     | Note                                                            |
+| :------------------------------ | :--------------------------------------- | :----------------------------- | :-------------------------------------------------------------- |
+| `react-i18next`                 | Runtime catalogs, context provider       | Opt-in via declaration merging | The default. Largest ecosystem, most examples, heaviest runtime |
+| `i18n-js` + `expo-localization` | Plain message objects                    | None                           | The historical pairing. Minimal and untyped                     |
+| `lingui`                        | Compiled catalogs via macro              | Yes                            | Good bundle profile, needs Babel config                         |
+| `intlayer`                      | Per-component declarations, Metro plugin | Generated                      | Build step required, smaller ecosystem                          |
 
-- **TypeScript Compatibility**  
-  Integrates with TypeScript, though you may need additional tooling to achieve fully typed message IDs.
+`react-i18next` remains the right default for most teams. If you already run it and it works, the reasons to move are bundle size and key typing, not correctness.
 
-**Considerations**
+## Intlayer on Expo
 
-- **Message Extraction**  
-  Requires an extraction workflow, which can add complexity to your build process. However, it’s powerful for large teams managing many translations.
+Content is declared next to the component that renders it, and a Metro plugin compiles those declarations.
 
-- **App Size & Deployments**  
-  If you rely on multiple polyfills or large translation files, watch your app’s overall size especially important in mobile contexts.
+```js fileName="metro.config.js"
+const { getDefaultConfig } = require("expo/metro-config");
+const { configMetroIntlayer } = require("react-native-intlayer/metro");
 
-- **Community Examples**  
-  While widely used, React Native-specific usage examples may be fewer than for React web. You’ll likely adapt existing docs and patterns to a native environment.
+module.exports = (async () => {
+  const defaultConfig = getDefaultConfig(__dirname);
+  return await configMetroIntlayer(defaultConfig);
+})();
+```
 
----
+Wrap the root with the provider, seeding it from the device locale:
 
-### 4. LinguiJS
+```tsx fileName="App.tsx"
+import { getLocales } from "expo-localization";
+import { IntlayerProvider } from "react-native-intlayer";
 
-> Website: [https://lingui.js.org/](https://lingui.js.org/)
+export default function App() {
+  return (
+    <IntlayerProvider defaultLocale={getLocales()[0]?.languageTag}>
+      <RootNavigator />
+    </IntlayerProvider>
+  );
+}
+```
 
-**Overview**  
-**LinguiJS** delivers a modern, developer-friendly approach to i18n for JavaScript and React (including React Native). With its CLI-based message extraction and compilation, it focuses on minimizing runtime overhead.
+Import from `react-native-intlayer`, not `react-intlayer`. It re-exports the same hooks and adds the web API polyfills Intlayer expects.
 
-**Key Features**
+```tsx fileName="src/screens/HomeScreen.tsx"
+import { useIntlayer, useLocale } from "react-native-intlayer";
 
-- **Automatic Message Extraction**  
-  Scans your code for translation strings, reducing the risk of missed or unused messages.
+export const HomeScreen = () => {
+  const { title, steps } = useIntlayer("home-screen");
+  const { setLocale, availableLocales } = useLocale();
 
-- **Minimal Runtime Overhead**  
-  Compiled translations keep your app performant and well-optimized for mobile devices.
+  return <Text>{title}</Text>;
+};
+```
 
-- **TypeScript & Autocompletion**  
-  Properly configured, you’ll get typed IDs for translations, making developer workflows safer and more intuitive.
-
-- **Integration with React Native**  
-  Straightforward to install and link in a React Native environment; you can also handle platform-specific translations if needed.
-
-**Considerations**
-
-- **Initial CLI Setup**  
-  Some extra steps are needed to configure the extraction and compilation pipeline for React Native projects.
-
-- **Community & Plugins**  
-  The library’s ecosystem is smaller than i18next, but it’s growing quickly, and the core CLI tools are robust.
-
-- **Code Organization**  
-  Deciding how to break up your message catalogs (by screen, feature, or language) is vital to maintain clarity in larger apps.
-
----
+Switching locale through `setLocale` re-renders the components reading content, so the language changes without a restart. RTL is the exception: `getHTMLTextDir` tells you whether the active locale is right to left, and you still have to hand that to `I18nManager` and reload.
 
-## Final Thoughts
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
 
-When selecting an i18n solution for your React Native application:
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-react-native-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
 
-1. **Assess Your Requirements**
-   - How many languages are needed now and in the future?
-   - Do you require on-demand loading for large apps?
+  </Tab>
+</Tabs>
 
-2. **Mind Platform Differences**
-   - Ensure any library supports iOS and Android locale variations, especially date/number/currency quirks.
-   - Consider offline usage some translations might need to be bundled with the app, while others can be fetched remotely.
+**What it costs you.** The Metro plugin is mandatory, so a bare `jest` or `tsc` run that bypasses Metro will not see the generated dictionaries without extra config. React Native tends to break on version drift more than the web does, so keep `intlayer` and `react-native-intlayer` aligned. The ecosystem is much smaller than i18next's, and ICU message format support is still incomplete. If your translators deliver ICU strings today, check [the i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md) or stay where you are.
 
-3. **Choose a Structure for Scalability**
-   - If you’re planning a large or long-lived application, a strong extraction workflow or typed keys can help keep translations well-organized.
+## Common mistakes
 
-4. **Performance & Bundle Size**
-   - Mobile data constraints mean you should keep a close eye on the size of your translation files and any polyfills.
+- **Reading the device locale once at module scope.** The user can change the system language while your app is backgrounded. Resolve on mount, and again on resume.
+- **Calling `forceRTL` without reloading.** The flag is set, the layout is not. You get a mixed screen and a bug report you cannot reproduce.
+- **Hardcoding `left` and `right` in styles.** Use `start` and `end` so RTL mirroring works at all.
+- **Shipping every Intl polyfill.** Each one carries CLDR data into the binary. Import what you use.
+- **Translating the app but not the store listing.** Discovery happens before install.
+- **Assuming the simulator represents devices.** Intl gaps and RTL behaviour both differ on real low-end Android.
 
-5. **Developer Experience (DX)**
-   - Look for libraries that align with your team’s skill set some solutions are more verbose but straightforward, while others offer more automation at the cost of setup complexity.
+## Going further
 
-Each solution Intlayer, React-i18next, React Intl, and LinguiJS has proven effective in React Native environments, though with slightly different priorities. Evaluating your project’s roadmap, developer preferences, and localization needs will guide you to the ideal fit for delivering a truly global React Native app.
+- [Set up Intlayer in a React Native and Expo app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_react_native+expo.md)
+- [Bundle optimization: what reaches the binary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)
+- [Benchmark reports across frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Drop-in i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md) and the [migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_i18next_to_intlayer.md)
+- [React i18n: how the provider model works](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/react.md)
+- [What internationalization actually covers](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)