[#368] 🤖 - featlocalization add generic repository message catalogs

[efraespada]

📌 Summary

Introduces generic repository localization for GitHub-facing communication while keeping English as the default. Issue and pull-request locales can inherit the repository locale or use explicit overrides.

---

🎯 Related Issues / Tickets

• Closes [#368] 🤖 - featlocalization add generic repository message catalogs #368

---

🧩 Scope of Changes

• Added:
  • Provider-neutral locale and message-catalog models.
  • Bundled catalog resolution and validated dynamic localization.
  • Localization for GitHub comments, summaries, status messages, setup, doctor, and CLI output.
  • Catalog caching and atomic English fallback.
• Updated:
  • Repository locale configuration, inheritance, workflows, documentation, specifications, and coverage budgets.
  • Translation publication while preserving human-authored comments.
  • Generated action and CLI bundles.
• Removed:
  • Feature-local English/Spanish presentation branching.
• Refactored:
  • Publication workflows to consume localized message catalogs and expose resolution evidence.

---

🛠️ Technical Details

• Canonicalizes valid BCP-47 locale tags, including one-time underscore migration support.
• Resolves bundled English and Spanish catalogs by exact locale or compatible base language.
• Uses one schema-constrained, cached language-agent request for other valid locales.
• Falls back atomically to English when dynamic localization fails or returns invalid content.
• Validates placeholders, plural forms, identifiers, Markdown, HTML, URLs, commands, mentions, and bidirectional-control characters.
• Preserves original comments and places translated interpretation plus escaped original content only in bot-owned responses.
• Setup, doctor, and Job Summaries report canonical locales and catalog-resolution evidence.

---

🔍 How to Test

1. Run pnpm test and verify all test suites pass.
2. Run pnpm run test:coverage and verify the localization coverage budget passes.
3. Run pnpm run typecheck and pnpm run lint.
4. Test en-US, bundled exact locales, base locales, and unsupported valid BCP-47 locales.
5. Verify locale inheritance, dynamic localization, caching, and atomic English fallback.
6. Exercise addressed comments in matching and differing languages; verify the source comment remains unchanged and the bot response contains safe translation context.
7. Run the documentation, workflow, specification, build, npm-package, smoke, and generated-bundle validation scripts.

---

🧪 Test Coverage

• Unit tests
• Integration tests
• End-to-end (E2E) tests
• Manual testing only

3,739 tests pass across 426 suites. Localization code meets the defined 100% pure-policy coverage budgets and changed-path coverage thresholds.

---

📸 Screenshots / Recordings (UI changes only)

Not applicable.

---

⚠️ Breaking Changes

• None

---

🚀 Deployment Notes

• Requires database migration
• Requires environment variable changes
• Requires feature flag toggle
• No special deployment steps

Details:

Generated action and CLI bundles are included and should be published with the source changes.

---

🔒 Security Considerations

• No security impact
• Input validation changes
• Authentication / authorization changes
• Sensitive data handling changes

Dynamic catalogs and translated originals are bounded and validated. Human-authored comments remain unchanged, and escaped original content is protected against Markdown control, HTML, commands, mentions, URLs, and bidirectional-text injection.

---

📈 Performance Impact

• No performance impact
• Improves performance
• Potential performance regression (explain)

Dynamic catalog requests are strictly limited and cached by locale, configuration, and message descriptors. Bundled catalogs avoid agent calls entirely.

---

📝 Notes for Reviewers

Please pay particular attention to catalog validation, fallback behavior, comment ownership, and preservation of machine-readable commands and contracts.

---

✅ Checklist

• I have self-reviewed my code
• Code follows project standards and conventions
• Tests have been added or updated
• Documentation has been updated
• No new warnings or lint errors
• Breaking contract changes and required consumer updates are documented

---

📚 Additional Context

The repository-locale specification and catalog index were updated alongside the implementation. Validation coverage includes typecheck, ESLint, documentation, workflow, specification, npm package, smoke, build, and generated-bundle checks.

[docs-page]

To preview the documentation for this pull request, visit the following URL:

docs.page/vypdev/copilot~368

Documentation is deployed and generated using docs.page

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.69737% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.05%. Comparing base (274db40) to head (1bff06b).
⚠️ Report is 697 commits behind head on develop.

Files with missing lines	Patch %	Lines
src/actions/github_action_completion.ts	66.66%	1 Missing and 3 partials ⚠️
src/actions/github_action_execution.ts	0.00%	0 Missing and 1 partial ⚠️
src/application/policies/action_summary_policy.ts	91.66%	0 Missing and 1 partial ⚠️
...ps/common/comment_language_translation_workflow.ts	85.71%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #368      +/-   ##
===========================================
+ Coverage    90.94%   92.05%   +1.10%     
===========================================
  Files          135      639     +504     
  Lines         6251    16383   +10132     
  Branches      1338     4233    +2895     
===========================================
+ Hits          5685    15081    +9396     
- Misses         172      528     +356     
- Partials       394      774     +380     

Files with missing lines	Coverage Δ
src/actions/github_action.ts	94.59% <100.00%> (+12.66%)	⬆️
src/application/policies/agent_response_schemas.ts	100.00% <ø> (ø)
...application/policies/comment_translation_policy.ts	100.00% <100.00%> (ø)
...application/policies/copilot_interaction_policy.ts	100.00% <100.00%> (ø)
...pplication/policies/publication_message_catalog.ts	100.00% <100.00%> (ø)
...ion/policies/semantic_result_publication_policy.ts	98.80% <100.00%> (ø)
...plication/policies/setup_configuration_defaults.ts	97.82% <100.00%> (ø)
...c/application/policies/setup_configuration_plan.ts	97.87% <100.00%> (ø)
...application/policies/setup_doctor_report_policy.ts	100.00% <100.00%> (ø)
src/application/policies/status_command_policy.ts	95.74% <100.00%> (ø)
... and 20 more

... and 670 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vypbot]

Bugbot: review incomplete

Current status: The review of 1bff06b has partial coverage and cannot declare the whole pull request clean.

Action: Inspect the omitted items or reduce the PR scope. Rerun the review only after changing the scope, limits, or access.

Incomplete coverage

• selection: complete; retained=1
• issue-comments: complete; retained=3
• pull-request-comments: complete; retained=1
• review-threads: complete; retained=1
• diff: partial; retained=28, omitted=47, truncated=2
• previous-findings: complete; retained=1
• human-conversation: partial; retained=2, truncated=1
• rules: complete; retained=0

Pull request · Verified commit · Workflow run

[vypbot]

Current status: Overall coverage is partial; this snapshot does not prove that all of its findings are resolved.
Last reconciled on 1bff06b. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem(s) when commit 50ea892 was analyzed. This snapshot is historical; use the status block above for current state. 1 finding(s) are linked to changed code.

Findings

• medium: Fallback welcome message ignores the configured issue locale — src/application/usecases/issue_workflow_context.ts:331