Skip to content

feat(i18n): follow the OS language when no language is selected - #168

Open
devs-rootstrap wants to merge 2 commits into
masterfrom
feat/sync-language-with-os
Open

devs-rootstrap wants to merge 2 commits into
masterfrom
feat/sync-language-with-os

Conversation

@devs-rootstrap

Copy link
Copy Markdown
Collaborator

Jira board reference:


What does this do?

The app language now follows the OS language unless a language was selected in the app.

  • At startup, i18n is initialized with the stored language first and falls back to the OS locale (getLanguage() ?? getLocales()[0]?.languageTag). Before this change src/lib/i18n/index.tsx only used the OS locale and ignored the stored selection.
  • New helpers in src/lib/i18n/utils.tsx: getDeviceLanguage(), resolveLanguage() and syncLanguageWithOS().
  • New useSyncLanguageWithOS() hook, mounted once in src/app/_layout.tsx. It listens to AppState changes and, when the app becomes active and no language was selected in the app, re-reads the OS locale with expo-localization and calls i18next's changeLanguage if it differs from the current language. The app's own changeLanguage util (which reloads/restarts the app) is not used here.
  • When a language was explicitly selected in the app, nothing changes.
  • Short note added to the Internationalization docs page.

Follows up on the discussion in #77.


Why did you do this?

As raised in #77, i18n is only initialized once, so if the OS language changes while the app is in the background, the app keeps the old language until it is restarted. Expo recommends listening to app state changes and reading the locales again (docs). Changing the language through i18next directly re-renders the translated UI without restarting the app.

Who/what does this impact?

  • Users who never picked a language in the app: the UI follows the OS language when they come back to the app.
  • Users who picked a language in the app: that language is now also respected at startup (it was previously overridden by the OS locale).
  • No new dependencies.

Layer 2: Risk Classification

Author applies a risk label when opening the PR. When in doubt, escalate.

Label When to use
risk:low Config, copy, minor UI tweaks. Low blast radius.
risk:medium Feature work, refactors touching multiple files.
risk:high Auth, payments, migrations, security-sensitive code.

Setup

  • Create risk:low, risk:medium, risk:high labels in the repo
  • Add risk criteria to contributing guide or PR template
  • Add reminder in PR template to apply the label before requesting review
  • Define who can override/escalate (suggested: tech lead)

How did you test this?

  • Tested on iOS
  • Tested on Android
  • Tested on a small device
  • Tested on a real device
  • Tested all flows related with this PR changes
  • Tested accessibility
  • Added tests

Unit tests added in __tests__/lib/i18n/:

  • index.test.ts: the stored language wins at startup; the OS locale is used when nothing is stored.
  • sync-language-with-os.test.ts: resolveLanguage precedence; the foreground update only happens when nothing is stored and the OS locale changed; no update on background; the AppState listener is removed on unmount.

How to test locally

  1. git checkout feat/sync-language-with-os
  2. pnpm install
  3. pnpm test
  4. Run the app (pnpm ios or pnpm android) without selecting a language in Settings.
  5. Send the app to the background, change the OS language in the device settings, and return to the app: translated strings should follow the new OS language (only languages present in src/lib/i18n/resources.ts have translations; others fall back to en).
  6. Select a language in Settings and repeat step 5: the selected language should stay.

Notes:

Assumptions

  • The language tag of the first OS locale (e.g. en-US) is passed to i18next as is, matching the previous startup behavior; i18next resolves it to the closest available resource with en as fallback.
  • The sync is done with a hook mounted in the root layout instead of a module-level listener, so the subscription is cleaned up with the component lifecycle.

Known limitations

  • RTL handling is unchanged: I18nManager is only configured at startup, so switching between LTR and RTL OS languages while the app is running takes effect after a restart.
  • Strings resolved with the memoized translate() helper are cached per key and are not refreshed when the language changes at runtime; components using useTranslation() or the Text tx prop update immediately.

Verification

  • pnpm lint: passed
  • pnpm type-check: passed
  • pnpm lint:translations: passed
  • pnpm test: 30 suites, 151 tests passed
  • Not verified on a device or emulator yet; please check switching the OS language with the app in the background on iOS and Android.

Screenshots / Previews

Not applicable (no UI changes).

@devs-rootstrap
devs-rootstrap requested a review from a team as a code owner November 9, 2026 12:07
@devs-rootstrap
devs-rootstrap requested review from amaury901130, asdolo and fernandatoledo and a balanced review from Copilot November 9, 2026 12:07
@devs-rootstrap devs-rootstrap added the risk:low Config, copy, minor UI tweaks. Low blast radius. label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown

💯 Test Coverage

Lines Statements Branches Functions
Coverage: 57%
56.98% (359/630) 60.52% (184/304) 50.2% (125/249)

😎 Tests Results

Tests Skipped Failures Errors Time
151 0 💤 0 ❌ 0 🔥 26.447s ⏱️
👀 Tests Details • (57%)
File% Stmts% Branch% Funcs% LinesUncovered Line #s
All files56.9860.5250.257.59 
src/app0000 
   _layout.tsx000028–125
src/lib/i18n63.1554.5476.9261.11 
   index.tsx100100100100 
   utils.tsx57.5754.5476.9254.8363–93

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Foreground language synchronization leaves existing labels in the previous language because Text does not react to language changes and its translation cache is not language-scoped.

1 open issue
What changed in this PR

Overall Review: ai:serious

This PR extends the template’s localization support to follow OS language changes while preserving explicit in-app language selections.

Changes:

  • Prioritizes the saved language at startup, falling back to the OS locale.
  • Adds foreground language synchronization with lifecycle-managed listener cleanup.
  • Adds initialization and synchronization tests, plus documentation of the behavior and RTL limitation.
File Description
src/​lib/​i18n/​utils.tsx Adds language resolution and foreground synchronization helpers.
src/​lib/​i18n/​index.tsx Uses saved-language precedence during initialization.
src/​app/​_layout.tsx Mounts the synchronization hook once at the root.
docs/​src/​content/​docs/​guides/​internationalization.mdx Documents OS language tracking and the RTL restart requirement.
__tests__/​lib/​i18n/​sync-language-with-os.test.ts Tests language precedence, foreground updates, and listener cleanup.
__tests__/​lib/​i18n/​index.test.ts Tests startup language selection.

Review effort: Balanced

Comment thread src/lib/i18n/utils.tsx Resolved

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:low Config, copy, minor UI tweaks. Low blast radius.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants