OpenDataEnsemble · najuna-brian · Jul 15, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,26 @@
+# EditorConfig — https://editorconfig.org
+# Aligns with .gitattributes (LF in repo). Cursor/VS Code apply this on save when
+# the EditorConfig extension is enabled (built into Cursor/VS Code by default).
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.go]
+indent_style = tab
+indent_size = 4
+
+[*.{bat,cmd}]
+end_of_line = crlf
+
+[Makefile]
+indent_style = tab
diff --git a/AGENTS.md b/AGENTS.md
@@ -39,7 +39,7 @@ flowchart LR
 | Profile | Typical focus | Where to work |
 |--------|----------------|---------------|
 | **Platform developer** | You are editing **this repo**: RN, Go, React, shared packages, CI. | Package `AGENTS.md` below. |
-| **Custom app author** | You ship an **HTML/JS/CSS** app bundle and JSON forms for Formulus; you may **not** clone this monorepo. | [Custom app template (AI + author context)](https://github.com/OpenDataEnsemble/custom_app) and [documentation](https://opendataensemble.org/docs/). |
+| **Custom app author** | You ship an **HTML/JS/CSS** app bundle and JSON forms for Formulus; you may **not** clone this monorepo. | [Custom app template (AI + author context)](https://github.com/OpenDataEnsemble/custom_app), [documentation](https://opendataensemble.org/docs/), and [FORM_LOCALIZATION_GUIDE.md](FORM_LOCALIZATION_GUIDE.md) for form i18n. |
 
 Do not assume custom app authors have local checkouts of **ODE** or internal example repos.
 
@@ -135,13 +135,14 @@ git push origin v1.1.1-alpha.3
 - **Custom app bridge (v1.1.0+):** `persistObservation` (headless write), `sync`, `getConnectivityStatus`, `getCurrentDataRevisionCount`, and `openFormplayer` options `skipFinalize` / `skipDraftSelection` — contract in [`FormulusInterfaceDefinition.ts`](formulus/src/webview/FormulusInterfaceDefinition.ts); run `pnpm run sync-interface` in formplayer after changes.
 - **Sub-observations:** Each nested Formplayer session validates its own schema; `skipFinalize` only skips the Finalize page. Custom validators are per-session — see [Custom Extensions — nested sessions](https://opendataensemble.org/docs/guides/custom-extensions#nested-sessions-and-custom-validators) (docs site).
 - **Shared UI tokens:** Install **tokens** before **components** / **formplayer** where the docs require it (see package READMEs and formplayer AGENTS).
+- **i18n (two layers):** ODE-owned locales (`en`/`pt`/`fr`) for Formulus + Formplayer chrome via Settings → Language; form-owned copy via optional `translations` on `ui.json` elements (preprocessed at form init). See [FORM_LOCALIZATION_GUIDE.md](FORM_LOCALIZATION_GUIDE.md) (monorepo) and [form translations guide](https://opendataensemble.org/docs/guides/form-translations) (published).
 
 ---
 
 ## CI and code quality
 
 - **Pipelines:** [.github/CICD.md](.github/CICD.md).
-- **Lint/format:** Run the relevant scripts in the **package you touch** (see root [README.md](README.md) and each package).
+- **Lint/format:** Run the relevant scripts in the **package you touch** (see root [README.md](README.md) and each package). On Windows, use LF line endings — root [`.editorconfig`](.editorconfig) and [`.gitattributes`](.gitattributes) match Prettier/CI; run `pnpm run format` in the package if you see `Delete ␍` lint errors.
 - **Pre-flight before opening a PR:** each package `AGENTS.md` lists the local `lint` / `format` / `format:check` / `test` / `build` commands that match CI — run them in every package you changed (e.g. [formulus-formplayer/AGENTS.md](formulus-formplayer/AGENTS.md#pre-flight-before-a-pr)).
 - **Commits/PRs:** Conventional Commits and PR expectations are documented in [formulus-formplayer/AGENTS.md](formulus-formplayer/AGENTS.md) (project-wide convention).
 
@@ -157,4 +158,6 @@ ODE Desktop ships in [`desktop/`](desktop/) (see [desktop/AGENTS.md](desktop/AGE
 
 Authoritative **public** documentation: [opendataensemble.org](https://opendataensemble.org/docs/).
 
+Form localization (embedded `ui.json` translations): [FORM_LOCALIZATION_GUIDE.md](FORM_LOCALIZATION_GUIDE.md).
+
 Optional **AI-focused** context (no ODE clone required): [custom_app](https://github.com/OpenDataEnsemble/custom_app) on GitHub (`README.md`, `AGENTS.md`, `CONTEXT_*.md`).
diff --git a/FORM_LOCALIZATION_GUIDE.md b/FORM_LOCALIZATION_GUIDE.md
@@ -0,0 +1,247 @@
+# Form localization guide
+
+How **user-defined forms** (JSON Schema + `ui.json` in custom app bundles) support multiple languages in ODE.
+
+**Audience:** platform developers editing Formplayer/Formulus, and custom app authors shipping forms in app bundles.
+
+**Published user guide:** [Form translations](https://opendataensemble.org/docs/guides/form-translations) on opendataensemble.org (kept in sync conceptually; this file is the monorepo implementation reference).
+
+---
+
+## Two i18n layers (do not mix them up)
+
+| Layer | Who owns it | Where strings live | When it applies |
+|-------|-------------|-------------------|-----------------|
+| **ODE chrome** | ODE platform | `formulus-formplayer/src/locales/{en,pt,fr}.json`, Formulus i18n catalogs | Next/Back, validation errors, sub-obs “+ Add …” template, loading text |
+| **Form copy** | Form / app author | `ui.json` base fields + optional `translations` blocks | Field labels, descriptions, SwipeLayout headers, custom widget copy |
+
+Form authors **do not** edit ODE locale JSON. They embed translations in each form’s `ui.json`. ODE developers extend chrome strings when adding new platform UI.
+
+---
+
+## How form locale is chosen
+
+1. User setting in Formulus **Settings → Language** (`auto`, `en`, `pt`, `fr`)
+2. **Auto** → device language; if unsupported, bundle `defaultLocale` from `app.config.json`
+3. Fallback `en`
+
+The host passes the resolved tag as **`params.locale`** when opening Formplayer. Formplayer merges form translations **once at init** (`applyFormUiTranslations()` in `formulus-formplayer/src/i18n/applyFormUiTranslations.ts`).
+
+```json
+// app/public/app.config.json (custom app bundle)
+{
+  "defaultLocale": "pt"
+}
+```
+
+Use `defaultLocale` when the study’s primary language is not English so **Auto** prefers the right default on devices whose language ODE does not ship.
+
+---
+
+## Authoring pattern: base string + `translations`
+
+Put the **default** copy on the element (`label`, `description`, `text`, …). Add **`translations.<locale>`** only for locales that differ.
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/participant_name",
+  "label": "Participant name",
+  "description": "Full legal name",
+  "translations": {
+    "pt": {
+      "label": "Nome do participante",
+      "description": "Nome legal completo"
+    },
+    "fr": {
+      "label": "Nom du participant"
+    }
+  }
+}
+```
+
+**Rules:**
+
+- Base `label` is required for every user-visible control — do not rely on `schema.json` `title` for display text in multi-locale forms.
+- `translations` keys are **partial**; missing keys fall back to the base string.
+- Locale lookup tries the full BCP-47 tag then the language subtag (`pt-BR` → `pt`).
+- `translations.<locale>.title` is accepted as an alias for `label` in that block (legacy convenience).
+
+### Portuguese-primary study with English override
+
+Base language can be anything; merge logic is symmetric.
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/codigo",
+  "label": "Digitalizar código do envelope",
+  "translations": {
+    "en": { "label": "Scan the envelope code" }
+  }
+}
+```
+
+| Active UI locale | Shown label |
+|------------------|-------------|
+| `pt` | Base (`label`) |
+| `en` | `translations.en.label` |
+| `fr` (no block) | Base (`label`) |
+
+---
+
+## `schema.title` vs `ui.json` `label`
+
+| | `schema.json` → `properties.*.title` | `ui.json` → `Control.label` |
+|---|--------------------------------------|-----------------------------|
+| Translated at runtime? | No | Yes |
+| Primary on-screen label? | Fallback only | Yes |
+
+```json
+// schema.json — keep for validation / exports; not your i18n source of truth
+{
+  "properties": {
+    "codigo": { "type": "string", "title": "Código" }
+  }
+}
+```
+
+```json
+// ui.json — what the user actually reads
+{
+  "type": "Control",
+  "scope": "#/properties/codigo",
+  "label": "Digitalizar código do envelope",
+  "translations": { "en": { "label": "Scan the envelope code" } }
+}
+```
+
+Formplayer resolves labels in order: **`Control.label`** (after translation merge) → JsonForms default → **`schema.title`** → field key. All built-in renderers, SwipeLayout header chips, Finalize summaries, and sub-observation column headers use this path (`controlDisplayText.ts`).
+
+---
+
+## SwipeLayout chrome
+
+Put button and header copy in **`options`**. Override per locale via top-level keys in the translation block (merged into `options`) or nested `translations.<locale>.options`:
+
+```json
+{
+  "type": "SwipeLayout",
+  "elements": [],
+  "options": {
+    "headerTitle": "Household interview",
+    "nextButtonLabel": "Next",
+    "finalizeButtonLabel": "Finish"
+  },
+  "translations": {
+    "pt": {
+      "headerTitle": "Entrevista ao agregado",
+      "nextButtonLabel": "Seguinte",
+      "finalizeButtonLabel": "Concluir"
+    }
+  }
+}
+```
+
+---
+
+## Sub-observations
+
+**Add button:** if `options.addButtonLabel` is omitted, Formplayer composes `+ Add {itemLabel}` from schema `itemLabel` using ODE chrome strings (`subObservation.addItem`). Override when you need custom wording:
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/quartos",
+  "label": "Quartos",
+  "options": {
+    "addButtonLabel": "+ Adicionar quarto"
+  },
+  "translations": {
+    "en": {
+      "addButtonLabel": "+ Add room"
+    }
+  }
+}
+```
+
+**Table columns:** list columns by **`key` only** in `schema.json`. Headers come from the **linked child form**’s `ui.json` labels (after translation), not from hardcoded schema column titles:
+
+```json
+"x-subObservation": {
+  "formType": "censo_milda_quarto",
+  "itemLabel": "quarto",
+  "columns": [{ "key": "quarto_num" }, { "key": "quarto_display" }]
+}
+```
+
+Child forms need their own `Control.label` + `translations` for those fields. Optional static `column.label` / `options.columns[].label` overrides all locales.
+
+---
+
+## Custom question types
+
+Widget-specific copy belongs in **`Control.options`**, not hardcoded in `question_types/.../renderer.js`:
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/confidence",
+  "label": "How confident are you?",
+  "options": {
+    "lowLabel": "Not at all",
+    "highLabel": "Very",
+    "oneOf": [{ "const": "yes", "title": "Yes" }]
+  },
+  "translations": {
+    "pt": {
+      "label": "Qual é a sua confiança?",
+      "options": {
+        "lowLabel": "Nada",
+        "highLabel": "Muito",
+        "oneOf": [{ "const": "yes", "title": "Sim" }]
+      }
+    }
+  }
+}
+```
+
+Behavioral config (`maxStars`, filters, …) stays in **`schema.json`** (`config` / validation), not in translated UI copy.
+
+---
+
+## Translatable properties (v1)
+
+| Element | Properties |
+|---------|------------|
+| `Control` | `label`, `description`; nested `options.*` |
+| `Group`, `Category` | `label` |
+| `Label` | `text` |
+| `SwipeLayout` (root) | `options.headerTitle`, `options.nextButtonLabel`, `options.finalizeButtonLabel` |
+| Sub-observation | `options.addButtonLabel`; optional `options.columns[].label` |
+
+---
+
+## Platform implementation map
+
+| Concern | Location |
+|---------|----------|
+| Merge `translations` into UI schema at init | `formulus-formplayer/src/i18n/applyFormUiTranslations.ts` |
+| Label resolution at render time | `formulus-formplayer/src/utils/controlDisplayText.ts` |
+| Form init + `params.locale` | `formulus-formplayer/src/App.tsx` |
+| ODE chrome catalogs | `formulus-formplayer/src/locales/*.json` |
+| UI locale preference (host) | `formulus/src/lib/locale.ts`, Settings → Language |
+| Linked child specs for sub-obs columns | `FormInitData.linkedFormSpecs` (built in Formulus / ODE Desktop) |
+
+When changing merge rules or label resolution, update **`applyFormUiTranslations.test.ts`**, affected renderers, and the [published form translations guide](https://opendataensemble.org/docs/guides/form-translations) in **ode-docs**.
+
+---
+
+## Author checklist
+
+- [ ] Every visible field has `Control.label` in `ui.json` (not only `schema.title`)
+- [ ] Base `label` set; `translations` added for other ODE UI locales you ship (`en`, `pt`, `fr`)
+- [ ] SwipeLayout headers/buttons translated where needed
+- [ ] Sub-obs columns use `key` only; labels live on linked child forms
+- [ ] Custom question type strings in `options`, not in renderer JS
+- [ ] `defaultLocale` in `app.config.json` when the study default is not English
diff --git a/desktop/AGENTS.md b/desktop/AGENTS.md
@@ -41,7 +41,9 @@ Persisted per profile via `upsertProfileRemote` / Rust `ServerProfile`.
 | Off  | `bundles/active/app/`             | `bundles/active/forms/`                                        |
 | On   | `bundles/dev-local/app/` (mirror) | `bundles/dev-local/forms/` (mirror if `<folder>/forms` exists) |
 
-Synk downloads and **Refresh from server** on the Bundles page only touch `bundles/active/`. The source folder on disk is **never** modified.
+Synk downloads and **Download & apply** on the Bundles page only touch `bundles/active/`. The source folder on disk is **never** modified.
+
+**Bundle download:** `download_and_apply_app_bundle` (TS: `tauriClient.downloadAndApplyAppBundle()`) — native Rust HTTP download; no zip bytes over IPC. Progress events: `bundle/apply-progress`, `bundle/index-rebuild`. Observation index rebuild runs in the background after apply.
 
 ### UI
 
@@ -64,13 +66,15 @@ On success, Zustand bumps `devMirrorGeneration` so embeds and form lists reload.
 - `src/hooks/useDeveloperMode.ts` — profile read/write, refresh, generation counter from store.
 - `src/components/DeveloperModePanel.tsx` — full vs banner UI; auto-mirror `useEffect` only on `variant="full"`.
 - `src/lib/bundleLayout.ts` — `bundleSegment()`, `bundleFormsRel()`.
-- `src/store/useCustodianStore.ts` — `devMirrorGeneration`, `devBusy`, `devError`, `refreshDevMirror`.
+- `src/store/useCustodianStore.ts` — `devMirrorGeneration`, `devBusy`, `devError`, `refreshDevMirror`, `bundleActivity`.
+- `src/lib/bundleTauriEvents.ts` — bundle apply progress listeners.
 
 ### Key Rust
 
 - `profile_developer_mode`, `bundle_segment`, `bundle_form_roots_for_ctx`
 - Dev-aware: `list_active_bundle_forms`, `read_bundle_form_spec`, `get_active_bundle_forms_file_base_url`, `scan_bundle_custom_question_types`, `bundle_app_config_path`
-- Tests: `validate_custom_app_dev_source_requires_index_html`, `mirror_custom_app_dev_folder_copies_tree`
+- `download_and_apply_app_bundle` — streamed Synkronus zip download + apply (never pass large binaries through WebView IPC as `number[]`)
+- Tests: `validate_custom_app_dev_source_requires_index_html`, `mirror_custom_app_dev_folder_copies_tree`, `apply_app_bundle_zip_at_workspace_writes_state_and_active`
 
 ### Errors
 
@@ -81,7 +85,7 @@ Developer mode on with missing/invalid folder → blocking error in UI; no silen
 ## Bridge and bundles
 
 - **Contract source of truth:** [`formulus/src/webview/FormulusInterfaceDefinition.ts`](../formulus/src/webview/FormulusInterfaceDefinition.ts).
-- **Form preview:** `formPreviewBridge.ts` handles injection `postMessage` types; device APIs stubbed; observations/attachments use Tauri.
+- **Form preview:** `formPreviewBridge.ts` handles injection `postMessage` types; device APIs stubbed; observations/attachments use Tauri. **`linkedFormSpecs`** on `FormInitData` is populated via `buildLinkedFormSpecs` (see `buildFormPreviewInit.ts`) so sub-observation column headers match Formulus.
 - **Extensions:** `bundleExtensionLoader.ts` merges `forms/ext.json` like Formulus `ExtensionService`; pass `developerMode` for path prefix.
 
 ---

diff --git a/desktop/docs/UI_FEEDBACK.md b/desktop/docs/UI_FEEDBACK.md
@@ -4,11 +4,13 @@ Single source of truth for how the shell surfaces status, errors, and confirmati
 
 ## Progress banner (full-width)
 
-**Use for:** long-running sync and import jobs only.
+**Use for:** long-running sync, import, and **app bundle download/apply** jobs.
 
 - Renders below the mode switch / dev bar in `Shell`.
-- Shows spinner + status text; dismissible but reappears on next activity.
-- Do not use for quick actions (save, auth, bundle download).
+- Shows spinner + status text; optional determinate progress bar when `bundleActivity.total > 0`.
+- Dismissible but reappears on next activity.
+- Bundle apply: Rust emits `bundle/apply-progress` and `bundle/index-rebuild`; `bundleActivity` in `useCustodianStore` drives the banner.
+- Do not use for quick actions (save, auth, dev mirror refresh).
 
 ## Toasts (bottom-right stack)
 
@@ -32,7 +34,7 @@ Single source of truth for how the shell surfaces status, errors, and confirmati
 
 **Use for:** destructive actions, import-with-issues, closing unsaved observation tabs.
 
-- `confirmDestructiveAction()` for destructive flows (always strict production-tier wording).
+- `confirmDestructiveAction()` for destructive flows (clear, profile-scoped wording).
 - `confirm()` from `@tauri-apps/plugin-dialog` for save-anyway / import-anyway / tab discard (Save / Don't save / Cancel via separate flows).
 
 ## Retired patterns

diff --git a/desktop/docs/screens/import.md b/desktop/docs/screens/import.md
@@ -29,3 +29,11 @@ Bring external JSON observation files into the active profile’s local reposito
 
 - Store: `import` flow via `tauriClient.importObservations`, refresh `loadObservations` / `loadHealth` after import
 - Active profile determines target SQLite repository
+
+## Observation indexes
+
+When the active app bundle declares `observationIndexes` in `app.config.json`:
+
+1. Import writes observations in batches (default 2000 rows per IPC call); intermediate batches skip index work.
+2. After the final batch commits, Rust schedules **one** coalesced background full index rebuild (`bundle/index-rebuild` progress events). Overlapping rebuild requests while one is running are merged into a single follow-up pass.
+3. Sync pull uses incremental indexing per page instead (no full rebuild after each pull).