feat(i18n): add translator context for AI message catalog by riderx · Pull Request #2983 · Cap-go/capgo.app

riderx · 2026-08-10T12:05:57Z

Summary (AI generated)

Added messages/en.context.json with usage context for every English i18n key (2717 keys).
Updated the Cloudflare translation worker and API translation path to send { text, context } to Workers AI and instruct it to use context for disambiguation.
Included contexts in the catalog checksum so translations refresh when context changes.
Added bun run i18n:contexts to regenerate contexts from code usages.
Made context generation deterministic and folder-based so file renames do not churn translation caches.
Fixed pre-existing backend typecheck failure in email preferences unit mocks so CI can pass.

Motivation (AI generated)

Short UI strings like "Current", "Access", or "Filters" were being mistranslated because the automation worker only saw bare English text. Inlang message-format cannot store translator notes inside en.json (values must be strings), so a companion context file is required.

Business Impact (AI generated)

Better non-English console UX with fewer wrong word senses, without changing the public Vue i18n API or requiring manual per-locale catalogs.

Test Plan (AI generated)

bunx vitest run tests/translation-queue.unit.test.ts
bun run typecheck:backend
bunx vitest run tests/email-preferences-public.unit.test.ts
Deterministic bun run i18n:contexts regen
Confirm a non-English language request regenerates with the new checksum
Spot-check ambiguous keys (e.g. Current, Filters, MAU) in a translated catalog

Generated with AI

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

New Features
- Added contextual information to translation requests to improve handling of ambiguous messages.
- Added a command to generate translation contexts from source usage.
- Translation caching now accounts for both English messages and their contexts.
- Improved translation processing by excluding invalid catalog entries.
Documentation
- Updated internationalization documentation with context-file guidance and generation instructions.
Tests
- Added validation for complete, non-empty message contexts and context-aware translation payloads.

Add en.context.json with usage context for every English key and pass it to the translation worker prompt so Workers AI can disambiguate short UI labels. Checksum now includes contexts so catalog refreshes pick this up. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

coderabbitai · 2026-08-10T12:06:13Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0a89d248-4501-4de8-a16f-bcc02edfbfde

📥 Commits

Reviewing files that changed from the base of the PR and between 3283e99 and 1c9818f.

📒 Files selected for processing (2)

messages/en.context.json
scripts/generate-translation-contexts.mjs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Cap-go/capacitor-updater (manual)

📝 Walkthrough

Walkthrough

The PR generates English translation contexts from source usage, stores them separately, includes them in translation checksums and batches, and sends structured text/context payloads to Workers AI. Tests validate context coverage, payload serialization, and prompt instructions.

Changes

Translation context pipeline

Layer / File(s)	Summary
Context catalog generation `scripts/generate-translation-contexts.mjs`, `package.json`, `messages/README.md`	The repository scans translation-key usage, infers context, writes `messages/en.context.json`, and documents context generation and checksum usage.
Catalog normalization and checksum `cloudflare_workers/translation/index.ts`, `supabase/functions/_backend/public/translation.ts`	Both translation implementations load normalized message and context catalogs, exclude `$schema` and non-string values, and checksum both catalogs.
Contextual batching and AI payloads `cloudflare_workers/translation/index.ts`, `supabase/functions/_backend/public/translation.ts`	Batches retain optional context, count context characters toward limits, and send structured payloads. Prompts instruct Workers AI to use context for disambiguation and translate only text.
Context and typing validation `tests/translation-queue.unit.test.ts`, `tests/email-preferences-public.unit.test.ts`	Tests validate context coverage and payload behavior. Email preference mocks now use explicit asynchronous result types.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SourceFiles
  participant ContextGenerator
  participant TranslationWorker
  participant WorkersAI
  ContextGenerator->>SourceFiles: discover translation-key usage
  SourceFiles-->>ContextGenerator: return keys and source locations
  ContextGenerator->>TranslationWorker: provide generated context catalog
  TranslationWorker->>WorkersAI: send structured text/context batches
  WorkersAI-->>TranslationWorker: return translated text

Possibly related PRs

Cap-go/Capgo.app#2978: Updates the same email preference test mocks with typed asynchronous return values.

Suggested labels: codex

Suggested reviewers: dalanir, wcaleniewolny

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding translator context for the AI message catalog.
Description check	✅ Passed	The description includes a clear summary, motivation, impact, and test plan, but omits the template checklist and screenshots section.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

_{Comment @coderabbitai help to get the list of available commands.}

codspeed-hq · 2026-08-10T12:08:10Z

Merging this PR will not alter performance

✅ 43 untouched benchmarks
⏩ 2 skipped benchmarks¹

_{Comparing cursor/i18n-translation-context-ed75 (1c9818f) with main (dea082a)}

2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

cursor

Stale comment

Risk: medium. Left a non-blocking comment — Bugbot passed with no findings, but this changes the Cloudflare and backend translation pipelines plus catalog checksum invalidation, so it is above the low-risk auto-approve threshold. Human review is needed; assigning reviewers.

_{Sent by Cursor Approval Agent: Pull Request Approver External}

Widen UsersQueryResult mocks so resolved user rows typecheck under tsgo. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

cursor

Stale comment

Risk: medium. Left a non-blocking comment — Bugbot passed with no findings, but this changes the Cloudflare and backend translation pipelines plus catalog checksum invalidation, so it is above the low-risk auto-approve threshold. Human review is needed; reviewers are already assigned.

_{Sent by Cursor Approval Agent: Pull Request Approver External}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@messages/README.md`:
- Around line 12-14: Update the documented translation-context generation
command near generate-translation-contexts.mjs to use the package script entry
point, bun run i18n:contexts, instead of invoking Node directly.

In `@scripts/generate-translation-contexts.mjs`:
- Line 11: In the directory traversal loop using readdirSync(dir), sort the
returned entries before iteration, and sort each filesForKey collection before
selecting its first five locations. Preserve the existing selection logic while
ensuring generated contexts and checksum-based cache inputs are deterministic.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9091d600-f189-4cb0-94f9-66dc9bf79776

📥 Commits

Reviewing files that changed from the base of the PR and between dea082a and f092ef1.

📒 Files selected for processing (8)

cloudflare_workers/translation/index.ts
messages/README.md
messages/en.context.json
package.json
scripts/generate-translation-contexts.mjs
supabase/functions/_backend/public/translation.ts
tests/email-preferences-public.unit.test.ts
tests/translation-queue.unit.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Cap-go/capacitor-updater (manual)

cubic-dev-ai

Review completed against the latest diff

Not reviewed (too large): messages/en.context.json (~2,719 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.

_{Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic}

Use bun run i18n:contexts in docs, make context generation deterministic, and store folder-based areas instead of file names so renames do not churn translation checksums. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/generate-translation-contexts.mjs`:
- Around line 73-78: Update the area derivation logic in the translation-context
generation flow so root-level files under src/ also remove their filename before
building the area. Ensure the resulting empty path uses the existing 'app'
fallback, keeping contexts stable when files such as App.vue are renamed.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 263eddb4-2a39-4152-9067-e8258e0a35ed

📥 Commits

Reviewing files that changed from the base of the PR and between f092ef1 and 3283e99.

📒 Files selected for processing (6)

cloudflare_workers/translation/index.ts
messages/README.md
messages/en.context.json
scripts/generate-translation-contexts.mjs
supabase/functions/_backend/public/translation.ts
tests/translation-queue.unit.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Cap-go/capacitor-updater (manual)

Map src root files to the app area fallback so renames like App.vue do not churn translation checksums. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

cursor

Risk: medium. Left a non-blocking comment — Bugbot passed with no findings, but this changes the Cloudflare and backend translation pipelines plus catalog checksum invalidation, so it is above the low-risk auto-approve threshold. Human review is needed; reviewers are already assigned.

_{Sent by Cursor Approval Agent: Pull Request Approver External}

sonarqubecloud · 2026-08-10T13:05:37Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

riderx temporarily deployed to deepsec-pr August 10, 2026 12:06 — with GitHub Actions Inactive

riderx marked this pull request as ready for review August 10, 2026 12:25

cursor Bot reviewed Aug 10, 2026

View reviewed changes

cursor Bot requested review from Dalanir and WcaleNieWolny August 10, 2026 12:27

fix(tests): type email preferences mocks for backend typecheck

f092ef1

Widen UsersQueryResult mocks so resolved user rows typecheck under tsgo. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

cursor Bot temporarily deployed to deepsec-pr August 10, 2026 12:36 Inactive

cursor Bot reviewed Aug 10, 2026

View reviewed changes

coderabbitai Bot added the codex label Aug 10, 2026

coderabbitai Bot requested changes Aug 10, 2026

View reviewed changes

Comment thread messages/README.md

Comment thread scripts/generate-translation-contexts.mjs Outdated

cubic-dev-ai Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread cloudflare_workers/translation/index.ts

cursor Bot temporarily deployed to deepsec-pr August 10, 2026 12:47 Inactive

coderabbitai Bot approved these changes Aug 10, 2026

View reviewed changes

coderabbitai Bot requested changes Aug 10, 2026

View reviewed changes

Comment thread scripts/generate-translation-contexts.mjs Outdated

fix(i18n): stabilize root-level translation context areas

1c9818f

Map src root files to the app area fallback so renames like App.vue do not churn translation checksums. Co-authored-by: Martin DONADIEU <martindonadieu@gmail.com>

cursor Bot temporarily deployed to deepsec-pr August 10, 2026 12:58 Inactive

cursor Bot reviewed Aug 10, 2026

View reviewed changes

coderabbitai Bot approved these changes Aug 10, 2026

View reviewed changes

riderx merged commit 01fbbe2 into main Aug 10, 2026
80 checks passed

riderx deleted the cursor/i18n-translation-context-ed75 branch August 10, 2026 14:06

Uh oh!

Uh oh!

Conversation

riderx commented Aug 10, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary (AI generated)

Motivation (AI generated)

Business Impact (AI generated)

Test Plan (AI generated)

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

codspeed-hq Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

cursor Bot left a comment • 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!

cursor Bot left a comment • 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!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • 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!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Aug 10, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

riderx commented Aug 10, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 10, 2026 •

edited

Loading

codspeed-hq Bot commented Aug 10, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading