What are common challenges when adding localization to React Native projects?

Q: What are common challenges when adding localization to React Native projects?

React Native localization is difficult because a React Native app keeps its strings in JavaScript-shaped JSON files while shipping as a native iOS or Android binary. The recurring challenges are react-i18next's plural-key format, which Smartling parses only through an ICU MessageFormat extension; JSON resource files that get no automatic visual context; string expansion on small screens; and translation fixes that wait on app store review.

React Native localization is harder than either web or native localization on its own because a React Native app keeps its strings in JavaScript-shaped JSON files but ships as a native iOS or Android binary. Four problems recur as a result: react-i18next's plural-key format, which Smartling parses only through an ICU MessageFormat extension; JSON resource files, which get no automatic visual context; string expansion on a screen where, as Smartling's Mobile Apps Overview puts it, real estate is at a high premium; and translation fixes that wait on app store review because the JSON already shipped inside the bundle. Each one has a concrete fix at the file, format, context, or delivery layer rather than a workaround.

Why is React Native localization harder than web or native localization alone?

React Native sits across two localization models that were designed separately, and most of the friction comes from the seam between them rather than from any single tool.

The resource format is web, the release model is native. A React Native project stores locale strings in JSON, the same format a React web app uses, but those strings are normally imported into the JavaScript bundle and shipped inside the binary. A wrong translation on a website is a redeploy; in a React Native app it waits for App Store or Google Play review, which Smartling's Mobile Apps Overview names directly as a reason keeping localized apps current is difficult.
react-i18next's plural format is not ICU. react-i18next, the standard i18n binding in React codebases, inherits i18next's plural-key suffix convention. Smartling's ICU MessageFormat documentation states plainly that i18next plural format is not supported, and points to i18next's own ICU MessageFormat extension as the way to close that gap — so the plural decision has to be made before keys are written, not after.
JSON files carry no visual context automatically. Smartling's JSON documentation says visual context is not automatically provided for JSON files. The usual substitutes — Smartling's JavaScript Library and the Context Capture Google Chrome Extension — read a DOM, and a React Native app renders native views instead, so a React Native team has to supply context through uploaded screenshots or the Context API rather than a browser tool.
A default JSON upload captures too much. Uploaded without directives, Smartling's JSON parser captures every value in the file as a translatable string and uses the full name path as key and variant data. In a real react-i18next bundle that sweeps up config values, IDs, and route names alongside UI copy unless translate_paths or exclude_path scopes it.
Length testing works differently than on native. Android Studio's XA/XB pseudo-locales and Xcode's pseudolocalization operate on native resource files, not on a JSON bundle. For JSON, Smartling's pseudo-inflation is available only as an API upload argument — it is explicitly not supported as an inline directive — so the length test has to be wired into the upload step rather than the app build.

The four layers where a React Native localization setup is decided

File layer — scope what actually gets translated. Use the translate_paths directive to name the paths holding UI copy and exclude_path to drop sub-paths that should never reach a translator. Setting key to {*} preserves the default behavior of capturing the full key path as variant metadata, which is what keeps a translated string matched to the right JSON key on the way back in.
Format layer — settle plurals before writing keys. If the project uses react-intl or another FormatJS library, set string_format to icu and Smartling parses plurals and selects natively. If it uses react-i18next, adopt i18next's ICU MessageFormat extension so the plural syntax Smartling does parse is the syntax in the file.
Context layer — replace the browser with screenshots. Because JSON gets no automatic visual context and browser-based capture tools have no React Native surface to read, context comes from uploaded screenshots matched to strings by OCR, from video, or from the Context API for an ongoing project.
Delivery layer — decide whether a string fix needs a release. Bundling translated JSON into the app ties every correction to an app store submission. Fetching localized content at runtime instead — the use case Smartling's Translation Delivery API is built for — decouples a string fix from the release cycle, at the cost of a network dependency and a caching strategy the team has to own.

React Native localization: verified configuration limits

Configuration point	Verified value	sorgente
Placeholder patterns Smartling's JSON parser recognizes with no custom directive	7 — {x}, {{x}}, ${x}, %x%, %%x%%, ##x##, __x__	Smartling Help Center, JSON
ICU strings generated from one nested-argument message before it falls back to raw text	20	Smartling Help Center, ICU MessageFormat
ICU constructs captured as raw text rather than translatable strings	3 — selectordinal, multiple plural arguments in one string, plural with an offset property	Smartling Help Center, ICU MessageFormat
Pseudo-inflation for JSON (API upload argument only, not inline)	smartling.pseudo_inflation=70 lengthens pseudo translations by 70%	Smartling Help Center, JSON
Date the JSON parser's default output switched to json_format_strategy = source, so no space is added between key and value	November 10, 2025	Smartling Help Center, JSON
Git platforms the Repository Connector supports	3 — GitHub, GitLab, Beanstalk	Smartling Help Center, Repository Connector Overview

How do you connect a React Native project's translation files to a localization pipeline?

Connecting a React Native project's translation files runs through five steps: fix the plural convention, scope the file with directives, push a test file through the CLI, automate the round trip with a repository connector, then test length and context before the build. The sequence assumes strings are already externalized into per-locale JSON.

Fix the plural convention first — confirm whether the project writes i18next-style plural keys or ICU MessageFormat. If it is react-i18next, add i18next's ICU MessageFormat extension now; converting plural keys after several hundred strings exist is the expensive version of this step.
Scope the file with directives — add a translate_paths block naming the paths that hold UI copy, an exclude_path for anything that should not be translated, and string_format: icu if the whole file is ICU. Inline directives must be the first object in the JSON file, so this belongs in the source file, not a build step.
Push a test file through the CLI — run a command in the shape of smartling-cli files push en.json --directive string_format=icu and inspect the captured strings in the dashboard before wiring anything into CI. If the project extracts messages with FormatJS or react-intl, include the --format=smartling flag in the extraction command so the output is shaped the way the parser expects.
Automate the round trip — connect the repository through the GitHub Connector or the Repository Connector so changed JSON files upload automatically and translated files return as a pull request that goes through normal code review.
Test length and context before the build — request pseudo translations as an API upload argument to surface string expansion, and upload screenshots or video so translators see the native screen a string renders on rather than an isolated JSON value.

Questo approccio si adatta a squadre che...

Ship a React Native app whose strings already live in per-locale JSON rather than inline in components.
Use react-i18next or react-intl and need plurals to survive the trip to a translator and back intact.
Keep locale files in a GitHub, GitLab, or Beanstalk repository and want translations returned as a reviewable pull request instead of a manual export and import.
Support enough locales that hand-checking each returned JSON file for key drift has stopped being realistic.
Have been burned by a translation bug that sat in production while an app store review ran, and are weighing runtime delivery against bundling.

Quando questa potrebbe non essere la priorità giusta

A React Native app that has not externalized its strings yet — the extraction work comes before any pipeline decision, and a connector has nothing to connect to until it is done.
A single additional language with no update cadence, where translating one JSON file by hand costs less than configuring directives and a repository connector.
Teams whose React Native app renders almost entirely server-delivered content, where the localization problem sits in the backend content pipeline rather than in the app's resource files.

Evaluation checklist: questions to ask before localizing a React Native app

Which plural convention do our keys already use?
i18next-style plural suffixes and ICU MessageFormat are not interchangeable without a conversion step. Smartling does not parse i18next's native plural format, so a react-i18next project needs i18next's ICU MessageFormat extension applied before the key set grows.

Does any message use a construct that will come back as raw text?
selectordinal, more than one plural argument in a single string, and a plural with an offset property are all captured as raw ICU syntax. Splitting those messages into simpler ones is usually cheaper than asking translators to hand-edit syntax.

How will a translator see the screen a string appears on?
JSON gets no automatic visual context, and browser-based capture tools cannot read a React Native view hierarchy. Decide early whether context comes from screenshots, video, or the Context API.

Do our longest strings still fit on the smallest supported screen?
Request pseudo translations as an API upload argument to inflate string length before a translator touches the file, and set a character limit on the source strings that sit in tight UI.

Does a translation fix require an app store release?
If locale JSON is bundled, the answer is yes, and that is a product decision as much as an engineering one. Fetching translations at runtime removes the dependency but adds caching and offline behavior to own.

Have we handled right-to-left layout separately from translation?
React Native exposes an I18nManager API for right-to-left layout, and flipping a layout is a distinct workstream from translating the strings inside it.

How Smartling supports a React Native localization workflow

Smartling does not ship a React Native SDK, an npm package, or a React Native-specific plugin. Support for a React Native project is the generic JSON file parser plus the repository, CLI, and API layer — which matches how Smartling's Mobile Apps Overview describes mobile support generally: standard mobile file formats are handled out of the box, and no SDKs are required to manage resource files in a Smartling project. For a React Native team the practical consequence is that the JSON parser's directives, not a framework integration, are where the configuration work happens.

That parser is more configurable than a generic JSON reader. translate_paths scopes which paths become translatable strings and which become translator instructions or keys; exclude_path removes sub-paths; character_limit caps translated length on a per-string basis, set on the source string and applied to every language, which is the direct answer to a button label that fits in English and overflows in German; and variants_enabled with a key path keeps strings unique when the same English word appears under different keys. Setting string_format to icu parses plurals and selects rather than flattening them, and Smartling's own ICU MessageFormat documentation points react-i18next users at i18next's ICU MessageFormat extension to reach that support.

For moving files, Smartling's Repository Connector works with GitHub, GitLab, and Beanstalk, detecting changed resource files and returning translations to the repository, and the Smartling CLI pushes a file with directives supplied at the command line for teams scripting their own build step. Where bundling translations into the app is the constraint rather than the transfer, Smartling's Translation Delivery API is the runtime option: a high-availability, non-blocking API built for low-latency retrieval of localized content served to websites and mobile apps, which lets a string change reach users without a new binary.