Skip to content

Internationalization (i18n)

This app supports multiple languages using a hybrid approach:

  • Resource strings in res/values*/strings.xml for all UI text.
  • Excel-driven, per-language content in app/src/main/assets/questions/{lang}.xlsx for questions.
  • Per-language user guide HTML in app/src/main/assets/userguide/{lang}.html.
  • Runtime language switching via LocaleHelper.

Resource Strings (UI)

  • Location: app/src/main/res/values/strings.xml, values-<lang>/strings.xml (e.g., values-hi, values-ml).
  • Usage:
  • XML: @string/app_name
  • Kotlin: getString(R.string.app_name) or with args getString(R.string.score_fmt, score)
  • Conventions:
  • Use meaningful names: title_home, action_retry, msg_correct_answer.
  • Prefer placeholders over string concatenation: "Score: %1$d".
  • Add plurals when needed:
<plurals name="questions_count">
    <item quantity="one">%d question</item>
    <item quantity="other">%d questions</item>
</plurals>

Runtime Locale Switching

  • Manager: presentation/features/setting/util/LocaleHelper.kt.
  • Behavior:
  • Applies the chosen language at app startup and when changed in Settings.
  • Persists selection in preferences and updates configuration/context.
  • UI should re-read strings after configuration update (activities/fragments recreated by helper as needed).

Localized Content (Excel + HTML)

  • Questions Excel per language: app/src/main/assets/questions/{lang}.xlsx
  • Loaded by core/utility/excel/ExcelQuestionLoader.kt (with cache in QuestionCache).
  • Filtered by Mode and Difficulty. Column layout summarized in dev/structure.md.

  • Keep column structure identical across languages; only localize question templates and literals.

  • User guide per language: app/src/main/assets/userguide/{lang}.html

  • Served by data/repository/userguide/UserGuideRepositoryImpl.kt and consumed via GetUserGuideHtmlUseCase.

Text‑to‑Speech (TTS)

  • TTS follows the current app locale via core/utility/common/TTSUtility.java.
  • Ensure the device has a voice installed for the selected language; otherwise Android may fall back.

Add a New Language (Checklist)

  1. Strings resources
  2. Create app/src/main/res/values-<lang>/strings.xml.

  3. Translate all keys from base values/strings.xml.

  4. Questions Excel

  5. Add app/src/main/assets/questions/<lang>.xlsx.

  6. Match the same sheet/columns as other languages (see dev/structure.md).

  7. User guide (optional but recommended)

  8. Add app/src/main/assets/userguide/<lang>.html.

  9. LocaleHelper

  10. Add the language to the supported list and settings options handled by LocaleHelper.kt.

  11. Verify

  12. Launch, switch language in Settings, confirm:
    • All screens show translated strings.
    • Questions load from the new Excel.
    • User guide opens in the selected language.
    • TTS pronounces texts appropriately (install voice if needed).

Tips & Pitfalls

  • Keep placeholders identical across translations (%1$d, %1$s, etc.).
  • Avoid embedding numbers or punctuation that vary by locale; prefer placeholders.
  • For right-to-left languages, verify layout mirroring and content descriptions.
  • If a translation is missing, Android falls back to values/strings.xml; Excel does not—ensure the {lang}.xlsx exists.