Touli — Internationalization (i18n) Guide

All translation infrastructure lives in apps/mobile/src/lib/i18n/.
Default language: English (en) · Secondary language: Arabic (ar)

---

Table of Contents

1. Architecture Overview
2. File Structure
3. How Initialization Works
4. RTL Support
5. Using Translations in Components
6. Adding or Editing Translations
7. Adding a New Language
8. Language Switching at Runtime
9. Type Safety
10. Translation Key Conventions
11. Interpolation & Pluralization
12. Common Patterns
13. Troubleshooting

---

1. Architecture Overview

i18next  ──▶  react-i18next  ──▶  Components (useTranslation / translate)
   │
   ├── resources (en.json + ar.json loaded at build time, no network)
   ├── MMKV storage (persists user language choice across sessions)
   └── RTL module (I18nManager + direction style on root view)

The app ships all locales as bundled JSON — no CDN fetch, no cold-start delay. Language preference is stored in MMKV so it survives restarts.

---

2. File Structure

src/lib/i18n/
├── index.tsx            # Entry point — initialises i18next, calls setupRTL
├── resources.ts         # Imports JSONs and exports typed resources object
├── utils.tsx            # translate(), useSelectedLanguage(), changeLanguage()
├── rtl.ts               # isRTL flag, dir() helper, setupRTL()
├── types.ts             # RecursiveKeyOf utility type for dot-path inference
├── react-i18next.d.ts   # Module augmentation — wires types into react-i18next
└── locales/
    ├── en.json          # English strings (used as the source-of-truth type)
    └── ar.json          # Arabic strings (must mirror every key in en.json)

---

3. How Initialization Works

index.tsx runs once when the module is first imported (typically from _layout.tsx):

1. i18n.init()  ←  resources: { en, ar }
                    lng: MMKV value ?? 'en'   (English is the default)
                    fallbackLng: 'en'
                    compatibilityJSON: 'v4'

2. setupRTL(i18n)
   ├── reads i18n.dir()  →  'rtl' | 'ltr'
   ├── sets isRTL (JS flag, effective immediately)
   ├── calls I18nManager.forceRTL()  (native layer — needs restart)
   └── if native state changed → RNRestart.restart()

_layout.tsx imports { isRTL } from @/lib/i18n which guarantees the module runs before the first render. The GestureHandlerRootView then receives direction: isRTL ? 'rtl' : 'ltr' which mirrors the entire flex tree immediately, even on first launch before the native restart fires.

---

4. RTL Support

Two-layer approach

Layer	Mechanism	Takes effect
JS layout	direction: 'rtl' on root GestureHandlerRootView	Immediately on first render
Native layout	I18nManager.forceRTL(true) + RNRestart.restart()	After one restart

isRTL flag

import { isRTL } from '@/lib/i18n';

// In JSX — evaluated at render time (live value)
<View style={isRTL ? styles.wrapperRTL : styles.wrapperLTR} />

isRTL is a module-level let that setupRTL writes before the first component renders. Babel compiles named imports as live getter accesses, so every component always reads the current value.

dir() helper — inline directional values

import { dir } from '@/lib/i18n';

// Returns the second argument when RTL, the first when LTR
const marginStart = dir(0, 16); // 0 in LTR, 16 in RTL
const position = dir('left', 'right');

Directional styles — always prefer logical properties

// ✅ Correct — mirrors automatically with layout direction
paddingStart: 12, paddingEnd: 8
marginStart: 4,   marginEnd: 4

// ❌ Avoid — fixed side, doesn't mirror
paddingLeft: 12, paddingRight: 8

Use left / right only when the position must be physically fixed (e.g. a toast that always appears at the device's physical right edge).

---

5. Using Translations in Components

Option A — useTranslation hook (recommended for functional components)

import { useTranslation } from 'react-i18next';

export function MyComponent() {
  const { t } = useTranslation();

  return <Text>{t('home.greeting', { name: 'Ahmad' })}</Text>;
}

Option B — translate() function (outside components / callbacks)

import { translate } from '@/lib/i18n';

const label = translate('settings.title');

translate is memoized with lodash.memoize. The cache key includes serialised options so interpolated strings are cached per unique argument set.

Option C — tx prop on the Text atom

The custom Text component accepts a tx prop that calls translate internally:

import { Text } from '@/lib/components/ui';

<Text tx="common.view_all" />;

---

6. Adding or Editing Translations

Step 1 — Edit en.json first (source of truth)

en.json drives the TypeScript types. Add your key, then TypeScript will flag any component that tries to use a key that doesn't exist.

// locales/en.json
{
  "home": {
    "new_section": {
      "title": "My New Section",
      "description": "This is a description with a {{variable}}.",
    },
  },
}

Step 2 — Mirror the key in ar.json

Every key that exists in en.json must exist in ar.json. Missing keys fall back to ar (the fallbackLng), which means users see Arabic even when English is selected — keep them in sync.

// locales/ar.json
{
  "home": {
    "new_section": {
      "title": "قسمي الجديد",
      "description": "هذا وصف مع {{variable}}.",
    },
  },
}

Step 3 — Use in a component

const { t } = useTranslation();
t('home.new_section.title');
t('home.new_section.description', { variable: 'value' });

TypeScript will auto-complete the key path and show an error for typos. ✓

---

7. Adding a New Language

1. Create the locale file — copy en.json to locales/fr.json and translate all values.

2. Register in resources.ts

import ar from './locales/ar.json';
import en from './locales/en.json';
import fr from './locales/fr.json'; // ← add

export const resources = {
  en: { translation: en },
  ar: { translation: ar },
  fr: { translation: fr }, // ← add
};

export type Language = keyof typeof resources; // 'en' | 'ar' | 'fr'

3. Update RTL list in rtl.ts if the language is RTL

export const RTL_LANGUAGES = ['ar', 'he'] as const; // add 'he' for Hebrew

4. Add UI strings in both en.json and ar.json for the language name:

// en.json
"settings": { "french": "French" }

// ar.json
"settings": { "french": "الفرنسية" }

5. Expose the option in the language picker (language-item.tsx).

---

8. Language Switching at Runtime

import { useSelectedLanguage } from '@/lib/i18n';

export function LanguagePicker() {
  const { language, setLanguage } = useSelectedLanguage();

  return (
    <Pressable onPress={() => setLanguage('ar')}>
      <Text>{language === 'ar' ? 'العربية' : 'Arabic'}</Text>
    </Pressable>
  );
}

What happens when setLanguage is called

setLanguage('ar')
  ├── MMKV.set('local', 'ar')       saves choice so next launch picks it up
  └── changeLanguage('ar')
        ├── i18n.changeLanguage()   updates react-i18next state
        ├── translate.cache.clear() flushes memoized translations
        ├── I18nManager.allowRTL()
        ├── I18nManager.forceRTL()  writes RTL pref to native storage
        └── RNRestart.restart()     full native restart — RTL layout applies

The restart is required because React Native's flex mirroring (I18nManager.isRTL) can only change at the native process level. The restart is near-instant (~300 ms).

---

9. Type Safety

The whole key path tree is inferred automatically from en.json.

// react-i18next.d.ts
declare module 'react-i18next' {
  type CustomTypeOptions = {
    resources: (typeof resources)['en']; // ← locks types to en.json shape
  };
}

This gives you:

• Auto-complete on every t('...') call
• Compile-time errors for misspelled or missing keys
• Hover documentation showing the English string value

t('home.greeting'); // ✅ resolves to "Hello, {{name}}!"
t('home.greetting'); // ❌ TypeScript error: key does not exist
t('home.badges.unknownKey'); // ❌ TypeScript error

TxKeyPath (exported from utils.tsx) is the union of all valid dot-path strings. Use it when passing translation keys as props:

type Props = { labelKey: TxKeyPath };
<Text tx={props.labelKey} />;

---

10. Translation Key Conventions

Rule	Example
Use snake_case for all keys	view_all, next_level, heart_of_gold
Group by feature namespace	home.*, settings.*, common.*
Keep common.* for truly shared strings	common.view_all
Use descriptive names, not positions	home.points.label not home.card1.text2
Interpolation variables in	, ,
Plural forms use _one / _other suffix	tasks_one, tasks_other (see §11)

---

11. Interpolation & Pluralization

Interpolation

// en.json
"greeting": "Hello, {{name}}!"

t('home.greeting', { name: user.displayName });
// → "Hello, Ahmad!"

Pluralization (i18next v4 format)

i18next resolves plural keys automatically based on the count option.

// en.json
"tasks_to_complete_one":   "{{count}} Task to Complete",
"tasks_to_complete_other": "{{count}} Tasks to Complete"

t('home.challenges.tasks_to_complete', { count: 3 });
// → "3 Tasks to Complete"

t('home.challenges.tasks_to_complete', { count: 1 });
// → "1 Task to Complete"

Arabic has six plural forms. i18next handles them with the suffixes _zero, _one, _two, _few, _many, _other:

// ar.json
"tasks_to_complete_zero":  "لا توجد مهام",
"tasks_to_complete_one":   "مهمة واحدة للإنجاز",
"tasks_to_complete_two":   "مهمتان للإنجاز",
"tasks_to_complete_few":   "{{count}} مهام للإنجاز",
"tasks_to_complete_many":  "{{count}} مهمة للإنجاز",
"tasks_to_complete_other": "{{count}} مهام للإنجاز"

---

12. Common Patterns

Conditional text based on direction

import { dir, isRTL } from '@/lib/i18n';

// Flip a unidirectional arrow glyph
const arrow = dir('→', '←');

// Flip an absolute-positioned element
const badgeStyle = isRTL ? styles.badgeRTL : styles.badgeLTR;

Reading current language

import i18n from '@/lib/i18n';

const lang = i18n.language; // 'ar' | 'en'
const dir = i18n.dir(); // 'rtl' | 'ltr'

Watching language changes reactively

import { useTranslation } from 'react-i18next';

const { i18n } = useTranslation();
// i18n.language updates when changeLanguage() is called
// (before restart — useful for web)

---

13. Troubleshooting

Text still shows LTR after switching to Arabic

The app requires a full native restart for I18nManager.isRTL to flip. This happens automatically via RNRestart.restart() in changeLanguage() and setupRTL(). If it looks like the restart isn't firing:

• Check that react-native-restart is installed and linked.
• In Expo, ensure you are running a dev client build (expo-dev-client), not Expo Go — Expo Go does not support all native modules.

Layout mirrors but text is still left-aligned

The Text atom sets writingDirection and textAlign from isRTL, not I18nManager.isRTL. If you bypassed the Text atom and used React Native's raw <Text>, add these styles manually:

<RNText style={{ writingDirection: 'rtl', textAlign: 'right' }}>النص العربي</RNText>

TypeScript error: "key does not exist"

The key is missing from en.json. Add it there first — the type is derived from en.json, not ar.json.

Stale translations after changeLanguage()

translate() is memoized. changeLanguage() calls translate.cache.clear?.() to flush the cache before restarting. If you call i18n.changeLanguage() directly (bypassing the wrapper), call translate.cache.clear?.() yourself.

fallbackLng showing Arabic in English mode

A key exists in en.json but is missing from ar.json. Keep both files in sync. Use a tool like i18next-parser in CI to catch missing keys automatically.