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
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.
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}.jsonformulus/src/lib/locale.tsformulus/src/lib/locale.test.tsformulus/src/i18n/bootstrap.tsformulus/src/services/LocaleSettingsService.tsformulus/src/components/common/LocalePicker.tsxformulus/AGENTS.mdFormplayer
formulus-formplayer/src/locales/{en,pt,fr}.jsonformulus-formplayer/src/i18n/localeUtils.tsformulus-formplayer/src/i18n/createOdeI18n.tsformulus-formplayer/src/i18n/useOdeT.tsformulus-formplayer/AGENTS.mdWhat to change
formulus/src/locales/sw.json.formulus-formplayer/src/locales/sw.json.swas an ODE UI locale in both packages.Kiswahili, in every Formulus shell catalog.swto be loaded from and saved to Formulus locale preferences.catalog map.
swselection resolves to Swahili;sw-KEandsw-TZresolve tosw;sw-KEto its Swahili catalog;Formplayer string come from the Swahili files rather than falling back to
English.
Translation requirements
corresponding Swahili catalog.
{{count}},{{name}},{{page}}, and similar values.Synkronus unchanged unless the surrounding sentence naturally needs a
different grammatical form.
terminology when a familiar phrase is available.
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 notadd guessed Swahili form content or change the form-translation contract as part
of this issue.
Done when
Kiswahiliappears as a selectable Formulus interface language.swtoFormplayer.
sw-KEorsw-TZselects Swahili while thepreference is
auto.catalogs.
path.
request is clearly marked as waiting for language review.
Verify it
From
formulus/:pnpm run lint pnpm run format:check pnpm run test --ci --watchAll=falseFrom
formulus-formplayer/:pnpm run lint pnpm run format:check pnpm test run pnpm run buildAlso 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.