feat(#332): add translation support

.changeset/solid-keys-matter.md

@@ -0,0 +1,6 @@
+---
+'@getodk/xforms-engine': minor
+'@getodk/web-forms': minor
+---
+
+Adds translation support.

.tx/config

@@ -0,0 +1,9 @@
+[main]
+host = https://app.transifex.com
+
+[o:getodk:p:web_forms:r:strings]
+file_filter  = packages/web-forms/locales/strings_<lang>.json
+source_file  = packages/web-forms/locales/strings_en.json
+source_lang  = en
+type         = STRUCTURED_JSON
+minimum_perc = 0

README.md

@@ -414,6 +414,12 @@ We will be adding color and more styling soon. We intend to expose a way to do b
 
 Thank you for contributing! Follow these guidelines for smooth collaboration.
 
+### Translations
+
+Translations are managed on Transifex. Translators can contribute at: https://app.transifex.com/getodk/web_forms
+
+For developers, see [TRANSLATIONS.md](./packages/web-forms/TRANSLATIONS.md) for details on how UI strings are managed and how to add or update translations.
+
 ### Requirements
 
 - [Volta](https://volta.sh/) to ensure consistent `node` and `yarn` versions.
@@ -510,9 +516,10 @@ If you'd like to try the functionality available on `main`, see the preview [on
 
 1. Run `yarn changeset version` to generate changelog files and version bumps from the changeset files.
 2. Run `yarn install` to update `yarn.lock` with the new versions.
-3. Verify that the changelogs look good, commit changes, open a PR, and merge the PR.
-4. Push tags for each package in the format `@getodk/<package>@x.x.x`. A GitHub action will publish the packages on NPM.
-5. Update dependencies to kick off the new release cycle.
+3. Update translations by running `yarn translations:pull` in the root directory.
+4. Verify that the changelogs look good, commit changes, open a PR, and merge the PR.
+5. Push tags for each package in the format `@getodk/<package>@x.x.x`. A GitHub action will publish the packages on NPM.
+6. Update dependencies to kick off the new release cycle.
 
 ### Patch release process
 

eslint.config.js

@@ -59,6 +59,7 @@ export default defineConfig(
 			'packages/tree-sitter-xpath/bindings/**/*',
 			'packages/tree-sitter-xpath/types/**/*',
 			'packages/web-forms/dist-demo/**/*',
+			'packages/web-forms/scripts/**/*',
 			'packages/xforms-engine/api-docs/**/*',
 			'**/vendor',
 		],

package.json

@@ -30,7 +30,8 @@
     "format:readme-only": "prettier -w README.md",
     "format:checkonly": "prettier -c \"**/*\" --ignore-unknown",
     "lint": "eslint . --report-unused-disable-directives --cache",
-    "feature-matrix": "node scripts/feature-matrix/render.js"
+    "feature-matrix": "node scripts/feature-matrix/render.js",
+    "translations:pull": "tx pull -a -f --mode translator"
   },
   "dependenciesMeta": {
     "tree-sitter": {
@@ -81,5 +82,8 @@
   "resolutions": {
     "tree-sitter": "0.22.1",
     "@asgerf/dts-tree-sitter/tree-sitter": "0.22.1"
+  },
+  "devDependencies": {
+    "@transifex/cli": "^7.1.5"
   }
 }

packages/common/src/fixtures/date-and-time/date-and-time.xml

@@ -41,6 +41,23 @@
             <value>À quelle heure prends-tu ton premier repas ?</value>
           </text>
         </translation>
+        <translation lang="Spanish (es)" default="true()">
+          <text id="/data/dates/survey_date:label">
+            <value>¿Cuando está completando este formulario?</value>
+          </text>
+          <text id="/data/dates/date_of_birth:label">
+            <value>¿Cuál es su fecha de nacimiento?</value>
+          </text>
+          <text id="/data/dates/fruits_date:label">
+            <value>¿Cuando fué la ultima vez que comió frutas?</value>
+          </text>
+          <text id="/data/dates/vegetables_date:label">
+            <value>¿Cuando fué la ultima vez que comió verduras?</value>
+          </text>
+          <text id="/data/dates/time:label">
+            <value>¿A que hora es su primera comida?</value>
+          </text>
+        </translation>
       </itext>
       <instance>
         <data id="date" version="2025020401">

packages/scenario/src/assertion/extensions/answers.ts

@@ -1,6 +1,6 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import { getBlobText } from '@getodk/common/lib/web-compat/blob.ts';
-import { constants, type ValidationCondition } from '@getodk/xforms-engine';
+import { type ValidationCondition } from '@getodk/xforms-engine';
 import { assert, expect } from 'vitest';
 import { ComparableAnswer } from '../../answer/ComparableAnswer.ts';
 import { ExpectedApproximateUOMAnswer } from '../../answer/ExpectedApproximateUOMAnswer.ts';
@@ -40,24 +40,16 @@ const assertAnswerResult: AssertAnswerResult = (value) => {
 };
 
 const matchDefaultMessage = (condition: ValidationCondition) => {
-	const expectedMessage = constants.VALIDATION_TEXT[`${condition}Msg`];
-
 	return {
 		node: {
 			validationState: {
 				[condition]: {
 					valid: false,
-					message: {
-						origin: 'engine',
-						asString: expectedMessage,
-					},
+					message: null,
 				},
 				violation: {
 					condition,
-					message: {
-						origin: 'engine',
-						asString: expectedMessage,
-					},
+					message: null,
 				},
 			},
 		},

packages/web-forms/TRANSLATIONS.md

@@ -0,0 +1,58 @@
+# Translations
+
+## How it works
+
+Translation strings are defined in `.i18n.json` files co-located with their components. At build time, these files are merged into `locales/strings_en.json`, which serves as the English baseline and is eagerly loaded at runtime. Translations for other locales are loaded lazily when the user switches language.
+
+Transifex automatically pulls the source strings from `locales/strings_en.json` daily. Translation files are synced back into the project just before each release.
+
+## Key naming convention
+
+Keys follow a 3-part dot-separated pattern:
+
+```
+component.feature.type
+```
+
+- **component**: camelCase name of the Vue component that owns the string (e.g. `odk_web_forms`)
+- **feature**: the feature or section within that component (e.g. `submit`, `validation`)
+- **type**: what kind of string it is. Use one of:
+  - `label`: button or field label
+  - `title`: heading or title
+  - `placeholder`: input placeholder
+  - `message`: informational message
+  - `error`: error message
+
+An easy way to remember: **who → where → kind** (which component? which feature? what type of string?).
+
+### Examples
+
+| Key (snake_case)                 | Description             |
+| -------------------------------- | ----------------------- |
+| `odk_web_forms.submit.label`     | Submit button label     |
+| `odk_web_forms.validation.error` | Validation error banner |
+
+## Adding a string
+
+1. Create or open the `.i18n.json` file next to the component.
+2. Add an entry using the `component.feature.type` key convention (snake_case):
+
+```json
+{
+  "my_component.some_feature.label": {
+    "string": "English text here",
+    "developer_comment": "Context for translators: when and where this string appears."
+  }
+}
+```
+
+3. Run `build:translations` to regenerate `locales/strings_en.json`. This also runs automatically as part of the build.
+4. Use the string in the component via `t('my_component.some_feature.label')`.
+
+## Developer comments
+
+The `developer_comment` optional field is for translators. Explain:
+
+- Where the string appears in the UI
+- Any placeholders (e.g. `{count}` is the number of violations)
+- Any constraints (e.g. keep it short, it appears on a button)

packages/web-forms/locales/README.md

@@ -0,0 +1,4 @@
+# Locales
+
+**Do not edit these files directly.** The `strings_en.json` file is auto-generated by `scripts/merge-translations.js`, and the other `strings_[locale].json` files are pulled from the Transifex project.
+The source strings are defined in `.i18n.json` files.