feat(#332): add translation support by latin-panda · Pull Request #727 · getodk/web-forms

latin-panda · 2026-03-10T18:01:23Z

Closes #332

TODO

Add project in https://app.transifex.com/getodk/
Add more test coverage
Test more cases
Finish translations english, spanish, indonesian
Add changeset
Document translation guide and best practices

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Browsers with different default languages

See message in error banner translated

Why is this the best possible solution? Were any other approaches considered?

The objective is to implement a scalable, lightweight internationalization that:

Allows host applications to fetch (Transifex) and provide translation files.
Supports complex variables and plurals using standard syntax.
Keeps the Web Forms bundle size minimal for low-end devices.
Provides contextual information (developer_comment) to translators. Just as Central and Collect do.

Boundary definition:
Web Forms will manage its own internal locale state and browser detection, but it will remain agnostic to how translation files are retrieved (Transifex).

Web forms component
- Responsible for detecting the user's preferred language via standard browser APIs (navigator.language) upon initialization
- Owns the active locale state and the language-switcher UI dropdown (there's an open question about language-switcher below).
- Exposes a required prop/callback (e.g., fetchTranslations(localeCode)) that it triggers when it mounts or when the user switches languages.
The host app (Central)
- The data provider. It implements the fetchTranslations function passed to Web Forms, handling the actual network request to fetch the appropriate JSON translation file from the backend or Transifex.

Translation format:
Web Forms will utilize a nested JSON structure with strings and developer comments to align with Central and Collect, following ICU Message Format syntax for handling variables and plurals.

It will include TypeScript interfaces to ensure a valid structure and documentation to guide contributors.

Library:
To parse the ICU strings, Web Forms will use intl-messageformat (from FormatJS) rather than heavier frameworks.

It's lightweight, 9.6kB gzipped.
Strictly follows ECMA-402. It offloads the heavy lifting of pluralization rules to the browser's native Intl API.
Transifex natively understands ICU MessageFormat
It has a strong community that keeps it updated with the latest ECMA-402.

Other libraries considered

vue-i18n: Adds ~15-20kb to the bundle size. It uses block that embeds strings into the compiled component (like Central does), making components less readable (I'm not a fan)
typesafe-i18n: Fast and lightweight (~1.2kb), but translations must be in a custom syntax. It doesn't support Transifex natively; implementing that would require complex, custom intermediate parsers.
Native Intl.PluralRules Wrapper: Building custom code around browser APIs without dependencies places the burden of maintenance on us.

Implementation details:

Each component that needs translations will have a sibling file: <component>.i18n.ts
This separation maintains component readability and focus on code. It is also extensible; if additional languages need to be added in the future, the main component remains unaffected. And good for tree-shaking support (more on that below).

There's a script (package/web-forms/script/extract-translations.js) that dynamically gets all <component>.i18n.ts and compiles them into a single strings_en.json file for Transifex upload. Maybe the upload can be automated as part of the release step in Github Actions.

It uses one Vue composable to initialize the internalization and fetch the translation files from the Host app. Another Vue composable keeps the locale state and executes the intl-messageformat parser.

Components will access strings via dot-notation: <span>{{ t('errors.invalidInputs', { count: 3 }) }}</span>

Possible future considerations (not part of this delivery)

Have a destructure-translations.js script that takes the downloaded translated JSON from Transifex and maps the localized strings back to their respective component i18n, allowing the application to easily serve them on request (tree-shaking for all languages, not just the default language).
Path to PWA (If): No longer rely only on the host app's translations, but dynamically import the generated *.i18n.[locale].ts directly. The current structure ensures zero refactoring in the Vue templates/components.

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Do we need any specific form for testing your changes? If so, please attach one.

What's changed

Open Question:

If switching language from the dropdown

How to get the locale code if form definitions don't provide the standard:

changeset-bot · 2026-03-10T18:01:28Z

⚠️ No Changeset found

Latest commit: 36b5255

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

latin-panda · 2026-03-10T19:50:23Z

@garethbowen There's still plenty to do, but the PR is at a good point to share for feedback.
What are your thoughts on this approach? I've included an explanation in the description box.

latin-panda · 2026-03-10T19:54:37Z

packages/web-forms/src/demo/FormPreview.vue


 const formPreviewState = ref<FormPreviewState>();

+// TODO: REMOVE THIS MOCK. Temporal for testing translations


I will revert the changes once the task is completed.

garethbowen · 2026-03-10T23:05:35Z

packages/web-forms/scripts/extract-translations.js

+		return [namespace, module.defaultStrings];
+	});
+
+	const resolvedImports = await Promise.all(imports);


I don't think you need to do await Promise.all here because you're awaiting in the .map right?

garethbowen · 2026-03-10T23:07:23Z

packages/web-forms/scripts/extract-translations.js

+		const files = await findI18nFiles(srcDir);
+		const dictionary = await buildAggregatedDictionary(files);
+
+		await mkdir(outputDir, { recursive: true });


Will the outputdir be ignored or committed? If it's ignored, let's call it something more obvious, like build/locales or something?

garethbowen · 2026-03-10T23:09:57Z

packages/web-forms/scripts/extract-translations.js

+	}
+};
+
+void runExtraction();


Central has done a lot of work with scripts to do this too - is there any benefit in trying to reuse their effort?

Still different, this is a lot simpler

garethbowen · 2026-03-10T23:11:26Z

packages/web-forms/src/components/FormLoadFailureDialog.i18n.ts

+import type { TranslationDictionary } from '@/lib/i18n/i18n-context.ts';
+
+export const defaultStrings: TranslationDictionary = {
+	title: {


Probably not a good label for an error message.

garethbowen · 2026-03-10T23:12:25Z

packages/web-forms/src/components/OdkWebForm.vue

-	if (violationLength === 0) return '';
-	else if (violationLength === 1) return '1 question with error.';
-	else return `${violationLength} questions with errors.`;
+	if (violationLength === 0) {


Remove TODO :D

garethbowen · 2026-03-10T23:13:33Z

packages/web-forms/src/components/OdkWebForm.i18n.ts

+			developer_comment:
+				'Message shown in the error banner when multiple questions have validation errors. {count} is the number of errors.',
+		},
+	},


It'd be better to combine these into one message with logic to handle the plurals.

garethbowen · 2026-03-10T23:17:32Z

packages/web-forms/src/lib/i18n/useI18nSetup.ts

+) => Promise<Record<string, TranslationDictionary>>;
+
+export function useI18nSetup(fetchTranslations?: FetchTranslationsCallback) {
+	const browserLocale = navigator.language?.split('-')[0];


It feels like we're having to implement things that a property translation lib should do for us. This is one example, where maybe it's good enough, but we're missing out on features you get for free using a library directly.

The vue-i18n doesn't determine the language, instead, Central retrieves it from navigator.language as we do here, and also from localStorage when their app language dropdown is changed.

Right but it does do proper locale fallback so you (a) don't need to split the language from the navigator, and (b) get the flexibility of being able to use the second part for more flexibility, (eg: en-NZ: "initialising" vs en-US: "initializing").

garethbowen · 2026-03-11T00:00:56Z

packages/web-forms/src/lib/i18n/useTranslation.ts

+	};
+
+	return { t };
+}


I'm nervous about providing custom code and caching, and would lean towards a more complete library such as vue-i18n which does more for us. Plus we have the benefit of standardisation with central and benefiting from things they've learned and tools they've built.

Yes, I understand the concern about the code and caching (I can improve the implementation to make it more robust).

I have two takes on the vue-i18n vs. intl-messageformat choice:

1. WF as a separate project using standard ICU MessageFormat
(This was my initial assumption for the design explained in the PR description)

The deeper I look into vue-i18n integration with Transifex, the less it makes sense for this project. Central uses a massive custom build script (~750 lines) to make it work with Transifex and ICU plurals (+ other utils around the code). They had to write a custom parser to rip apart ICU strings and convert them into vue-i18n’s pipe syntax. Even though that code is mature, I’m uncomfortable importing that complexity into the Web Forms repo. Plus, since we fetch translations dynamically, using vue-i18n with ICU would mean shipping that compiler code to the browser (I need to test this).

Our bundle size is already big. The vue-i18n plus the custom scripts adds >20kb, while intl-messageformat is only 9kb. We could save that space for other features :)

If this works well, Central might even be able to adopt this approach later to align better with native APIs and remove a lot of the custom code they need to maintain.

2. WF has a strong dependency on Central and WF uses the vue-i18n format

In this case, Central would handle the conversion of ICU MessageFormat and send the vue-i18n format directly to Web Forms. But we’d still have a larger bundle size than intl-messageformat, and we'd be "locked in" to Central's decisions on format.

I’m going to set up a meeting with the Central team to understand their struggles with Transifex and how it impacts their vue-i18n usage. Let me know if you still feel strongly about aligning with Central on this specific library and we can plan how to share code, etc.

garethbowen · 2026-03-11T00:06:44Z

The open question is really interesting. We could add to the spec to make this deterministic, eg: label::English::en but that'll take a while to gain traction. Maybe make a best guess by splitting the lang by whitespace/punctuation and looking for a code that matches?

lognaturel · 2026-03-11T18:36:34Z

Great to see this moving forward! I appreciate the thought given to keeping the default bundle small and leaving open the possibility of Central users supplying their own translations.

I haven't given any thought to vue-i18n vs. intl-messageformat.

add to the spec to make this deterministic

https://docs.getodk.org/form-language/ -- we do document adding the IANA language code in parentheses and XLSForm warns when it's not included.

enketo/enketo#1082 has the algorithm we had come up with for determining form and UI language in Enketo. I think eventually we would like the same in Web Forms but it can be a follow-up issue to refine (e.g. if form-level default language is currently ignored).

latin-panda added 2 commits March 10, 2026 00:37

makes translation composable

2fe2c84

fetches translations from host app

36b5255

latin-panda changed the title ~~feat(#332): Add translations webforms~~ feat(#332): add translation support Mar 10, 2026

latin-panda requested a review from garethbowen March 10, 2026 19:47

latin-panda commented Mar 10, 2026

View reviewed changes

garethbowen reviewed Mar 10, 2026

View reviewed changes

garethbowen reviewed Mar 11, 2026

View reviewed changes


		const formPreviewState = ref<FormPreviewState>();

		// TODO: REMOVE THIS MOCK. Temporal for testing translations

Conversation

latin-panda commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Why is this the best possible solution? Were any other approaches considered?

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Do we need any specific form for testing your changes? If so, please attach one.

What's changed

Open Question:

Uh oh!

changeset-bot bot commented Mar 10, 2026

⚠️ No Changeset found

Uh oh!

latin-panda commented Mar 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

latin-panda Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

garethbowen commented Mar 11, 2026

Uh oh!

lognaturel commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

latin-panda commented Mar 10, 2026 •

edited

Loading

latin-panda Mar 11, 2026 •

edited

Loading