Skip to content

feat(i18n): Add Swahili translations to Formulus and Formplayer #913

Description

@Mishael-2584

The small adventure

ODE is built for data collection in many places, by many communities, often
away from a dependable internet connection. Let us make the mobile shell and
form experience available in Swahili (sw) too.

This is more than dropping two JSON files into the repository. The new locale
must travel all the way from a device or Settings selection, through Formulus,
and into the embedded Formplayer. In other words: teach the whole path a new
language, not just the dictionary shelf.

Where to start

Formulus

  • formulus/src/locales/{en,pt,fr}.json
  • formulus/src/lib/locale.ts
  • formulus/src/lib/locale.test.ts
  • formulus/src/i18n/bootstrap.ts
  • formulus/src/services/LocaleSettingsService.ts
  • formulus/src/components/common/LocalePicker.tsx
  • formulus/AGENTS.md

Formplayer

  • formulus-formplayer/src/locales/{en,pt,fr}.json
  • formulus-formplayer/src/i18n/localeUtils.ts
  • formulus-formplayer/src/i18n/createOdeI18n.ts
  • formulus-formplayer/src/i18n/useOdeT.ts
  • formulus-formplayer/AGENTS.md

What to change

  • Add a complete Swahili catalog at formulus/src/locales/sw.json.
  • Add a complete Swahili catalog at
    formulus-formplayer/src/locales/sw.json.
  • Register sw as an ODE UI locale in both packages.
  • Add Swahili to the Formulus language picker, using the language's own name,
    Kiswahili, in every Formulus shell catalog.
  • Allow sw to be loaded from and saved to Formulus locale preferences.
  • Register the new resources in Formulus's i18next bootstrap and Formplayer's
    catalog map.
  • Add tests showing that:
    • explicit sw selection resolves to Swahili;
    • device/regional tags such as sw-KE and sw-TZ resolve to sw;
    • Formplayer resolves sw-KE to its Swahili catalog;
    • at least one representative Formulus string and one representative
      Formplayer string come from the Swahili files rather than falling back to
      English.
  • Update nearby documentation that lists the supported ODE UI locales.

Translation requirements

  • Every key in each English catalog must have a matching key in the
    corresponding Swahili catalog.
  • Preserve interpolation placeholders exactly, including {{count}},
    {{name}}, {{page}}, and similar values.
  • Preserve newline escapes and JSON syntax.
  • Keep ODE product names such as ODE, Formulus, Formplayer, and
    Synkronus unchanged unless the surrounding sentence naturally needs a
    different grammatical form.
  • Use clear, broadly understandable standard Swahili. Avoid inventing technical
    terminology when a familiar phrase is available.
  • Have a Swahili speaker review the wording before merging. Machine translation
    can be a starting point, but it is not the language review.

If a source string is ambiguous or difficult to translate without knowing the
screen, ask in the issue. Context is part of translation quality.

Important boundary

This issue translates ODE-owned interface text: menus, sync status, form
navigation, validation messages, and similar chrome.

It does not automatically translate the questions and labels authored inside a
form's ui.json. Form authors control that separate translation layer. Do not
add guessed Swahili form content or change the form-translation contract as part
of this issue.

Done when

  • Kiswahili appears as a selectable Formulus interface language.
  • Selecting it translates the Formulus shell and passes sw to
    Formplayer.
  • A device locale such as sw-KE or sw-TZ selects Swahili while the
    preference is auto.
  • Formplayer renders its ODE-owned interface from the Swahili catalog.
  • Both Swahili catalogs have exactly the same keys as their English source
    catalogs.
  • Placeholders and plural-related keys are preserved.
  • Locale-resolution and representative translation tests cover the new
    path.
  • A Swahili-speaking reviewer has checked the translation, or the pull
    request is clearly marked as waiting for language review.
  • Lint, formatting, tests, and builds pass in both packages.

Verify it

From formulus/:

pnpm run lint
pnpm run format:check
pnpm run test --ci --watchAll=false

From formulus-formplayer/:

pnpm run lint
pnpm run format:check
pnpm test run
pnpm run build

Also manually select Kiswahili in Formulus Settings and open a form. Check
both the surrounding mobile interface and Formplayer navigation/validation
text. A screenshot or short recording in the pull request would be lovely.

What you will meet along the way

This issue follows a setting across package boundaries: native device locale,
persisted Formulus preference, React Native i18next resources, WebView init
parameters, and Formplayer's lightweight catalog. It is a practical tour of why
Formulus and Formplayer are separate, and how they still behave as one field
tool.

AI tools are welcome, not required

AI can help compare catalog keys, preserve placeholders, identify hookup points,
or offer a first translation draft. Please do not treat fluent-looking output
as proof of a good translation. Read the code path, run the app, and involve a
Swahili speaker for the words people will actually rely on in the field.

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions