Skip to main content

Add New Languages to a React Native App

Instamobile React Native apps include a localization layer so you can translate the app into the languages your product needs. This guide explains where translations live, how to add a new language, how to verify fallback behavior, and what to test before release.

Quick Answer​

Duplicate the default English translation file, rename it using the language code, translate the values, register the new language in the translations index, restart Metro, rebuild the app, and test the app with the device language set to the new locale.

When To Use This Guide​

Use this guide when you want to:

  • add a new supported language;
  • translate a purchased app package for a market or client;
  • add RTL support for Arabic, Hebrew, Persian, Urdu, or another RTL language;
  • verify localization before publishing a white-labeled app.

Translation Files​

Most app packages keep translations under:

src/translations/

Common files:

src/translations/
  en.json
  es.json
  fr.json
  index.ts

The exact files can vary by app. Search before editing:

find src -path "*translations*" -maxdepth 4

Step 1: Create The New Language File​

Copy the English file:

cp src/translations/en.json src/translations/es.json

Use the ISO 639-1 language code when possible:

LanguageFile
Spanishes.json
Frenchfr.json
Germande.json
Arabicar.json
Hebrewhe.json

Step 2: Translate Values, Not Keys​

Translation files usually work as dictionaries. Keep the keys stable and translate the values.

{
  "Welcome": "Bienvenido",
  "Sign In": "Iniciar sesion",
  "Create Account": "Crear cuenta"
}

Do not rename keys unless you update every call site that uses the key.

Step 3: Register The Language​

Open the translations index file, commonly:

src/translations/index.ts

Register the new translation file in the same pattern used by the app package:

import en from './en.json'
import es from './es.json'

export default {
  en,
  es,
}

Some app packages use a slightly different structure. Follow the existing file pattern rather than replacing the localization system.

Step 4: Restart And Rebuild​

Restart Metro so the new JSON file is picked up:

corepack yarn start --reset-cache

Then rebuild the app:

corepack yarn ios

or:

corepack yarn android

Step 5: Test The Locale​

Change the simulator or device language to the new language and relaunch the app.

Verify:

  • onboarding screens;
  • sign-in and sign-up screens;
  • tab labels;
  • empty states;
  • settings screens;
  • form validation messages;
  • push notification text if generated locally;
  • any app-specific screens such as feeds, products, bookings, listings, or chat.

RTL Checklist​

For RTL languages, also verify:

  • text alignment;
  • row direction;
  • icons that imply direction, such as arrows;
  • chat bubbles;
  • form inputs;
  • navigation headers;
  • product/listing cards;
  • map and location screens.

If a screen has layout problems in RTL, fix the component layout instead of hard-coding a language-specific exception.

Troubleshooting​

The app still shows English​

Check that the new JSON file is registered in src/translations/index.ts, the device locale matches the language code, and Metro was restarted with a clean cache.

The app crashes after adding a translation file​

Validate the JSON syntax. A missing comma or quote can break the bundle.

node -e "JSON.parse(require('fs').readFileSync('src/translations/es.json', 'utf8'))"

Some strings are still missing​

Search for hard-coded strings and convert them to localized strings. Then add the same key to every supported language file.

Next Steps​