Running your practice
Expo Localization: What Translators and Agencies Need to Know About expo-localization
Expo localization uses expo-localization to detect device locale and pair with i18n libraries like i18n-js — translators handle JSON keys, ICU plurals, and app
Expo projects reach a translator's desk as JSON resource bundles, not as native source — and the module deciding which bundle loads at runtime is expo-localization. This guide frames the module from the production desk inside the broader Application Localization: The Translator's and Agency's Guide workflow, so agencies can quote, scope, and QA Expo handoffs without surprises.
What is expo-localization and what does it actually do?
expo-localization is an Expo SDK module that exposes the device's locale, region, calendar, timezone, measurement system, and currency to a React Native app, so a paired i18n library — i18n-js, i18next, or Intlayer — can pick the right translated strings. It detects; it does not translate.
The module's scope matters for scoping a quote. These are the surfaces it covers and the surfaces it leaves to someone else:
| Surface | Handled by expo-localization | Handled elsewhere |
|---|---|---|
| Device locale detection | Yes — languageTag, regionCode | — |
| Calendar, timezone, first day of week | Yes | — |
| Measurement system, currency code | Yes — reported only | Intl.NumberFormat for rendering |
| UI string translation | No | i18n-js, i18next, next-intl, Intlayer |
| App name on home screen | No | app.json locales map |
| App Store / Play Store listings | No | Store Connect, Play Console |
| User-chosen language override | No | AsyncStorage or SecureStore |
What does expo-localization return at runtime?
Localization.getLocales() returns an array of locale objects with languageTag (for example, en-US), regionCode, textDirection, measurementSystem, and currencyCode. Localization.getCalendars() returns calendar, timezone, and first-day-of-week values. These feed the i18n library's locale selector.
- languageTag — the BCP-47 string the i18n library keys on.
- regionCode — the two-letter country code, useful for en-US vs. en-GB splits.
- textDirection — "ltr" or "rtl", reported only; mirroring is applied via I18nManager.
- measurementSystem — "metric", "us", or "uk".
- currencyCode — ISO 4217 string, consumed by Intl.NumberFormat.
What does expo-localization NOT do?
expo-localization does not translate strings, does not localize the app name, does not translate store listings, and does not persist a user-chosen language override. Each is a separate step the translator or developer must handle.
How is expo-localization installed and configured in an Expo project?
expo-localization is installed with npx expo install expo-localization, added to the plugins array in app.json, and imported as import * as Localization from 'expo-localization'. The config plugin wires native iOS and Android locale permissions at prebuild time, so translators receive a build that resolves device locale correctly.
- Run
npx expo install expo-localization. - Add
"expo-localization"to thepluginsarray in app.json. - Add a sibling
localesmap pointing each supported locale to a JSON file. - Import the module:
import * as Localization from 'expo-localization'. - Run
npx expo prebuildto generate native projects with locale assets in place.
What goes in app.json for expo-localization?
The plugins array takes "expo-localization" as a bare string entry. The locales map, a sibling of ios and android, points each supported locale to a JSON file containing CFBundleDisplayName, usage descriptions, and Android app_name overrides.
Which Expo SDK versions matter for translators?
Expo SDK 49+ ships the config-plugin pattern that most translator-facing documentation predates. Projects on older SDKs typically arrive with hard-coded app names and missing locale descriptions, which is why agencies keep seeing untranslated home-screen labels on test builds. SDK 33's upgrade also removed the legacy Localization.locale property, breaking code that was never migrated.
How does expo-localization fit into the multi-language translation stack?
expo-localization sits at the detection layer: it reports the user's locale. A string catalog library — i18n-js, i18next, next-intl, or Intlayer — sits at the rendering layer and looks up the matching key from a JSON resource file. Translators work exclusively on the JSON files, never on expo-localization itself.
| Library | Pairing pattern | Translator-side artifact |
|---|---|---|
| i18n-js | Translations object keyed by locale, assigned via i18n.locale | One JSON per locale, flat or shallow-nested |
| react-i18next | Namespaced JSON files, {{name}} interpolation, Trans component | Namespaced JSON per locale |
| next-intl | Shared with Next.js web code, ICU messages | JSON per locale, ICU syntax |
| Intlayer | Typed per-component content with Metro bundling | Per-component content files |
expo-localization + i18n-js: the common pairing
Many Expo projects pair expo-localization with i18n-js: expo-localization provides the languageTag, i18n-js loads a translations object keyed by locale, and i18n.locale = Localization.getLocales()[0].languageTag wires them together. The translator receives one JSON file per locale.
expo-localization + react-i18next or next-intl
Projects reusing a React web codebase typically swap i18n-js for react-i18next or next-intl, using JSON namespaces, double-curly interpolation {{name}}, and the Trans component for inline markup. The translator-side difference is segment granularity, not the detection layer. For the full engineering view, see React i18n: How Translators Fit Into a React Localization Pipeline, with cross-framework patterns covered in How to Add i18n to an Astro Site.
How does the agency choose a locale override at runtime?
A user-chosen locale override — the in-app language switcher — is stored in AsyncStorage or SecureStore, read at app launch, and used to seed the i18n library's locale before falling back to Localization.getLocales(). expo-localization has no built-in persistence.
What does the translator actually receive from an Expo project?
A translator working on an Expo app receives a resource bundle — JSON files, one per locale, keyed by string ID — plus a translation memory, a term base, a style guide, and ideally a pseudo-localized staging build. The expo-localization module itself is invisible to the translator; it only shapes which locale the test build loads at runtime. The module's job is device locale detection — surfacing values like languageTag, regionCode, textDirection, measurementSystem, currencyCode, calendar, and timezone — and none of those values are translatable strings. What becomes a translator artifact is the JSON catalog that a pairing library such as i18n-js or react-i18next loads based on the languageTag expo-localization reports.
| expo-localization produces (runtime) | Translator receives (artifact) |
|---|---|
| languageTag (en-US, ja-JP) | Filename or folder key: en-US.json, ja-JP.json |
| regionCode (US, JP) | Variant notes in style guide |
| calendar, timezone | No artifact — rendered by Intl APIs |
| textDirection (rtl) | RTL QA notes, mirrored screenshots |
| measurementSystem, currencyCode | Format notes, not strings |
| — (out of module scope) | JSON strings for app_name and CFBundleDisplayName via app.json locales |
One coverage gap that frequently surprises agencies is that expo-localization does not localize the app name — neither CFBundleDisplayName on iOS nor app_name on Android — and it does not touch App Store or Play Store listing copy. Those strings live in a separate locales map inside app.json, sibling to the ios and android keys, where each locale maps to a JSON file holding display names and usage descriptions. Translators must confirm this scope is explicitly included or excluded in the handoff package before work begins.
When a project uses a typed, per-component content approach with Metro bundling, the artifacts may be structured differently from a flat JSON catalog — but the translator-facing deliverable is still a set of locale-keyed content files that must be returned in the same structure. Regardless of the underlying library, co-locating content with components is a pattern that facilitates maintenance in large-scale applications, which means translators may receive many smaller files rather than one monolithic catalog. Agencies should confirm file count and directory structure during scope review.
What does a clean i18n handoff for Expo look like?
A clean Expo i18n handoff satisfies 5 conditions, all of which are verifiable before translation begins:
- Strings externalized — no literals in source files, all copy in JSON catalogs.
- ICU plural and gender rules declared — for every count and gendered noun, so that translators receive the correct message-format variants rather than a flat string.
- Localization.getLocales() wired — as the default locale, with a persisted override for testing.
- RTL mirroring verified —
I18nManager.forceRTLandI18nManager.allowRTLmust be wired for Arabic and Hebrew; expo-localization reportstextDirectionbut does not apply the mirroring itself, so this is an engineering responsibility that must be confirmed complete before RTL translation QA begins. - No baked copy in assets — PNGs, SVGs, and canvas elements carry no hard-coded text.
ICU MessageFormat plural and gender rules are part of this checklist because every count-bearing string — item counts, notification badges, quantity pickers — requires a separate plural form per language, and every gendered noun requires a gender variant. Receiving a catalog without these rules forces translators to raise queries that stall delivery.
Where does pseudo-localization fit in the Expo workflow?
Pseudo-localization fits between extraction and translation as a dev-side stress test on the Expo build. It inflates strings by 30–50% and swaps ASCII characters to expose hard-coded text and truncated UI before any human translation budget is spent. A clean upstream pseudo-localization pass delivers resource files with the full user-visible string set, UI containers already sized for 30–50% expansion, and file encoding verified as UTF-8. Agencies that receive a build that has not passed a pseudo-localization gate carry the risk of discovering layout regressions mid-translation — a cost that should be reflected in the quote or contractually placed back on the development team. CJK-specific QA, including Chinese rendering checks, belongs in the same gate as pseudo-localization sign-off.
How is the app name localized in Expo, and why do translators keep seeing it skipped?
The app name is localized in Expo through the locales map in app.json, not through expo-localization. Each supported locale points to a JSON file with CFBundleDisplayName for iOS and app_name for Android. expo-localization does not touch this surface, which is why in-app text translates correctly while the home-screen icon stays in English.
What does the app.json locales entry look like?
The locales entry is a sibling of ios and android:
"locales": { "ja": "./languages/japanese.json", "fr": "./languages/french.json" }
Each referenced JSON file contains native keys the launcher and store listing display:
- CFBundleDisplayName — iOS home-screen label.
- NSCameraUsageDescription — iOS permission prompt.
- NSLocationWhenInUseUsageDescription — iOS permission prompt.
- app_name — Android launcher label written into strings.xml at prebuild.
Why are most app-name localization tutorials outdated?
Most tutorials predate Expo SDK 49's config-plugin lifecycle and reference pre-prebuild native file edits that no longer apply to managed workflow projects. Translators receiving builds from those docs see the JSON picked up on iOS but silently dropped on Android — the broken handoff pattern agencies now flag on intake.
What goes wrong with expo-localization in production — and what should the agency flag?
Three recurring failures hit production Expo localization: the SDK 33-era Localization.locale is undefined crash after upgrades, a non-exhaustive switch over languageTag that throws for untested locales, and iOS Simulator returning a stale locale after a Settings → General → Language & Region change. Each has a documented fix.
Why is Localization.locale undefined after an SDK upgrade?
Localization.locale was removed from the module API in later Expo SDKs in favor of Localization.getLocales()[0].languageTag. Codebases carried from SDK 33–40 crash with undefined is not an object until the call site is migrated. Translators see this as a test build that never loads any locale.
What triggers the 'switch must be exhaustive' TypeScript error?
TypeScript treats languageTag as a string, so a switch (languageTag) statement with locale cases hits the exhaustiveness check and throws at compile time. The fix is a default branch that falls back to the source language, which also prevents runtime crashes for unshipped locales.
How do you refresh the simulator and emulator after a locale change?
- iOS Simulator — Settings → General → Language & Region; reload the app to refresh the session before expo-localization picks up the new locale.
- Android emulator — Settings → System → Languages; pseudo-locales en-XA and ar-XB appear in Developer Options when
pseudoLocalesEnabled trueis set in build.gradle.
Pricing
What does an Expo localization project cost at translator rates?
An Expo app with 10,000 source strings budgets at
What should translators and agencies ask the Expo dev team before quoting?
Before quoting an Expo project, ask 6 questions whose answers decide whether the handoff is translator-ready or a scope trap. Each question maps to a concrete risk: a wrong or missing answer indicates rework, delayed delivery, or a budget overrun that will fall on the agency unless it is contractually pre-empted.
- Which Expo SDK version is in production — 49+ or legacy? SDK 49 introduced the config-plugin prebuild pattern, and most translator-facing setup tutorials predate it. A project running a legacy SDK version may have locale detection wired differently, which affects how the translation catalog is loaded and which file-naming conventions apply. Known regressions have appeared in specific SDK patch releases, and confirming the team is on a stable, up-to-date patch is a prerequisite for reliable locale detection in test builds.
- Which i18n library is in use — i18n-js, react-i18next, or another? The library determines catalog format, interpolation syntax, and whether namespace-split JSON files or a single flat file are expected. React-i18next uses
{{name}}interpolation and JSON namespaces; i18n-js uses a translations object keyed by locale. Translators must receive format documentation alongside the files. - Is the
app.jsonlocales map populated for every target locale? The locales map is the mechanism for localizing the app name (CFBundleDisplayNameon iOS andapp_nameon Android) and usage description strings. Expo-localization does not handle this scope — if the map is absent or incomplete, those strings are untranslated regardless of how thorough the in-app catalog is. - Has pseudo-localization run, and are the expansion limits documented? A pseudo-localization pass inflates strings 30–50% to expose hard-coded text and UI truncation before human translation begins. If it has not run, the agency carries the risk of layout regressions discovered mid-project.
- Which locales are in scope, and are RTL locales (ar, he) included? Arabic and Hebrew require
I18nManager.forceRTLandI18nManager.allowRTLto be wired on the engineering side — expo-localization reportstextDirectionbut does not apply mirroring. RTL LQA requires a functional mirrored build, not just a string file, so confirming engineering readiness before translation begins avoids a blocked review phase. - Are App Store and Play Store listings in or out of scope? Store listing copy is managed outside expo-localization — through the
app.jsonlocales map and external store consoles — and has its own word count, review cycle, and character-limit constraints. It must be explicitly included or excluded in the statement of work.
A development team that can answer all six questions with documented evidence is ready for handoff. A team that cannot answer questions 1, 3, or 4 is presenting a project that will generate translator queries, revision rounds, and timeline risk that the quote does not cover.
Expo projects most often launch with a 5-locale set: English, Spanish, French, German, and Japanese. Right-to-left locales (Arabic, Hebrew) and CJK locales (Chinese, Korean) add QA passes but no module-level change — expo-localization reports them identically.
Frequently asked questions
What does expo-localization actually cover vs. what you still have to handle manually?
expo-localization handles device-level locale detection — reading the user's preferred language, region, currency symbol, decimal separator, and text direction — but it does not translate any strings for you. You still have to supply every translated string yourself, wire up a library like i18n-js or i18next to serve them, handle pluralization rules, format dates and numbers per locale, and manage fallback chains when a language is unsupported. For translators and agencies, this means the actual translation files (typically JSON or PO) remain a fully manual deliverable that no Expo package replaces.
How do I add internationalization to an Expo app using expo-localization and i18n-js?
You install expo-localization to read the device locale, then configure i18n-js to load the correct translation file for that locale. The typical setup is: install both packages, create one JSON translation file per language (e.g., en.json, fr.json, de.json), initialise i18n-js with those files and set its locale from Locale.getLocales()[0].languageTag. From a translation-production standpoint, each JSON file is the deliverable — the strings inside are what translators author, review, and certify before the file ships.
How do I localize the app name (not just in-app text) using expo-localization?
Localizing the app name shown on the device home screen requires platform-specific configuration that expo-localization does not touch. On iOS you add localized InfoPlist.strings files (CFBundleDisplayName per language) inside the native project; on Android you add strings.xml files under res/values-{locale}/ folders. In a managed Expo workflow this means using the expo-build-properties plugin or ejecting to a bare workflow. These localized app-name strings are short but still count as translated content — agencies should include them in scope alongside UI strings.
what is expo localization
expo-localization is an Expo SDK module that exposes the device's locale settings — language tag, region, currency code, decimal/grouping separators, and text direction — to a React Native app at runtime. It does not provide translations or a translation management system; it is purely a locale-detection utility. Developers use it as the input signal for an i18n library (i18n-js, i18next, LinguiJS, etc.) that then selects and renders the correct pre-translated strings. For translation teams, expo-localization defines which locales the app must support, directly driving the list of target languages that need certified translations.
what is product localization
Product localization is the process of adapting a software product — its text, UI layout, date/number formats, images, and cultural conventions — so it functions naturally for users in a specific locale. It goes beyond simple translation: a fully localized product handles right-to-left text, local currency and measurement systems, locale-appropriate imagery, and legal or regulatory copy. For translators and agencies, product localization means delivering not just translated strings but also locale-specific formatting rules, pluralization, and sometimes certified translations of legal notices or terms of service embedded in the product.
How do I implement localization in React Native?
The standard approach is to use expo-localization (or the community react-native-localize package) to detect the device locale, then pair it with an i18n library such as i18next, i18n-js, or LinguiJS to serve the right translated strings. Translation content is stored in resource files — typically JSON or PO — one file per target language, which is the artifact translators produce. Additional steps include handling RTL layout with React Native's I18nManager, formatting dates with a library like date-fns or Intl, and setting up a fallback locale for unsupported languages.
Related
- Go i18n: How Translators Handle Golang Localization Handoffs
- How Shopify Localization Works and What It Means for Your Agency
- How Webflow Localization Works and What Translators Need to Know
- Internationalization Strategies: How Translation Agencies Choose and Operationalize Them
- JS Localization: How Translators Fit Into a JavaScript i18n Pipeline
- Localisation Project: How Translators and Agencies Scope, Run, and Deliver One