Stage 1 – MVP Bundled translation files in the app build

Localized UI via in-repo locale JSON files

Translation content lives in the codebase (Git). Developers update JSON files on request, then ship a new build. Language switching is instant because all locale files are packaged inside the final artifact.

Source of truth

Repo folder with locale files

Git
/locale/en.json Default
/locale/fr.json Few locales
/locale/es.json Optional

Ownership

Product Owner requests a copy change → developers update JSON files.

Product Owner Developers

Update lifecycle

Translation changes go through the normal release pipeline.

  1. 1
    Request
    PO asks for new / updated copy
  2. 2
    Developer edits locale files
    Modify /locale/*.json and commit
  3. 3
    CI/CD build
    New artifact includes updated translations
  4. 4
    Deploy
    Users see new copy after release

Runtime behavior

No network calls required for translations.

App launch device locale
i18n.t("feed.like") → "J’aime" / "Me gusta" / "Like"

All locales are available locally, so switching language is instant.

App build artifact

Translations are packaged into the build

Fast at runtime
Bundle contains local files
en.json ✅
fr.json ✅
es.json ✅

Pros

  • Instant language switch (no network)
  • Simple, MVP-friendly approach

Cons

  • Every copy change requires a new production build
  • Engineering becomes a bottleneck for wording updates
  • Scaling to many locales increases app size and maintenance cost

Reason to evolve to Stage 2

Translation updates are too slow because they depend on release cycles. Next step is to decouple translations from builds (host remotely + CDN).