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

.github/workflows/copilot_commit.yml

@@ -44,6 +44,9 @@ jobs:
 
       - uses: ./
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           debug: ${{ vars.DEBUG }}
           bugbot-severity: ${{ vars.BUGBOT_SEVERITY || 'low' }}
           bugbot-comment-limit: ${{ vars.BUGBOT_COMMENT_LIMIT || '20' }}

.github/workflows/copilot_issue.yml

@@ -25,6 +25,9 @@ jobs:
 
       - uses: ./
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: build/*
           bugbot-dry-run: ${{ vars.BUGBOT_DRY_RUN || 'false' }}
           bugbot-effort: ${{ vars.BUGBOT_EFFORT || 'smart' }}

.github/workflows/copilot_issue_comment.yml

@@ -26,6 +26,9 @@ jobs:
 
       - uses: ./
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: build/*
           debug: ${{ vars.DEBUG }}
           agent-provider: ${{ vars.AGENT_PROVIDER || 'codex' }}

.github/workflows/copilot_pull_request.yml

@@ -58,6 +58,9 @@ jobs:
       # Exercise the Action implementation from this PR so regressions are caught before merge.
       - uses: ./
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: build/*
           bugbot-severity: ${{ vars.BUGBOT_SEVERITY || 'low' }}
           bugbot-comment-limit: ${{ vars.BUGBOT_COMMENT_LIMIT || '20' }}

.github/workflows/copilot_pull_request_comment.yml

@@ -26,6 +26,9 @@ jobs:
 
       - uses: ./
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: build/*
           debug: ${{ vars.DEBUG }}
           agent-provider: ${{ vars.AGENT_PROVIDER || 'codex' }}

docs/configuration-checklist.mdx

@@ -35,6 +35,11 @@ description: Required checks before enabling Copilot automation.
 
 ## Setup and diagnosis
 
+- [ ] `repository-locale` is a canonical BCP-47 target or intentionally omitted for the `en-US` default.
+- [ ] Empty `issues-locale` and `pull-requests-locale` values intentionally inherit the repository locale; explicit overrides are documented.
+- [ ] Every non-bundled target locale has an available planner/language agent, or operators accept the observable atomic English fallback.
+- [ ] `copilot doctor` reports the effective repository, issue, and pull-request locales plus `exact`, `base`, `dynamic`, or `fallback` catalog paths.
+- [ ] Legacy underscore tags such as `pt_BR` have been rewritten to canonical tags such as `pt-BR` after the one-time setup warning.
 - [ ] Unattended setup uses `--non-interactive --yes` plus every required external credential; `--yes` is treated only as plan approval.
 - [ ] Cancellation (`Ctrl-C` or EOF) has been observed to exit 130 with no writes; declining the final plan exits 0 with no writes.
 - [ ] Setup review lists Secret names only and no secret value appears in config, plan, logs, errors, reports, fixtures, or backups.

docs/development/architecture.mdx

@@ -15,6 +15,25 @@ identity, and semantic digests before creating or updating a comment. The
 checked-in publication mutation inventory fails CI if a new application use
 case writes a comment or review without an explicit architectural decision.
 
+Repository-facing language follows the same boundary. Entrypoints build one
+canonical, frozen locale profile: `repository-locale` defaults to `en-US`, and
+empty issue or pull-request overrides inherit it. Presentation policies request
+stable message IDs from a versioned catalog instead of branching on language.
+Reviewed English and Spanish catalogs resolve by exact locale or compatible base
+language; any other valid BCP-47 locale uses one schema-constrained, per-run
+cached language-agent request. A missing or invalid dynamic slice falls back
+atomically to English and records only locale, source, descriptor count, and a
+stable reason in the Job Summary.
+
+Language adaptation is separate from catalog resolution. Comment admission,
+command parsing, and authorization establish trusted command identity before at
+most one prose adaptation. The language port has no comment-update capability:
+human source comments remain unchanged, while a translated bot response may add
+one collapsed, escaped context block. Commands, flags, refs, URLs, markers,
+Check names, log codes, and machine-readable fields never localize. Architecture
+tests reject feature-local `en`/`es` branches in common presentation and any
+source-comment mutation dependency in the adaptation path.
+
 - Application: use cases, pure policies (agent configuration, reviewer/assignee
   selection, and result publication), and semantic ports.
 - Data/repository: external adapters for agent execution, authentication, provisioning, GitHub, and Git.

docs/issues/configuration.mdx

@@ -11,6 +11,18 @@ The following parameters can be configured in the workflow:
 
 ### Optional Parameters
 
+#### Language
+
+- `repository-locale`: Repository-wide BCP-47 target locale (default: `en-US`).
+- `issues-locale`: Optional issue-surface override; empty inherits `repository-locale`.
+
+Setup canonicalizes legacy underscore values such as `pt_BR` to `pt-BR` with a
+one-time migration warning. English and Spanish are reviewed bundled catalogs;
+other valid locales use one schema-constrained dynamic catalog when the language
+agent is available, otherwise the complete artifact falls back to English. The
+Job Summary records the requested locale, resolved locale, resolution path, and
+stable fallback reason without storing message bodies.
+
 #### Action Control
 - `single-action`: Launch single actions
 - `single-action-issue`: Issue target for executing single action

scripts/coverage-budgets.json

@@ -193,6 +193,52 @@
         }
       ],
       "successMessage": "execution-boundary closure coverage: PASS (changed path 95% lines/statements, 90% branches/functions)"
+    },
+    {
+      "name": "Repository localization",
+      "missingEntryLabel": "repository localization",
+      "rules": [
+        {
+          "files": [
+            "src/domain/locale.ts",
+            "src/domain/message_catalog.ts",
+            "src/application/policies/comment_translation_policy.ts",
+            "src/application/policies/publication_message_catalog.ts",
+            "src/application/usecases/localization/resolve_message_catalog_use_case.ts"
+          ],
+          "mode": "each",
+          "thresholdProfile": "exhaustive"
+        },
+        {
+          "files": [
+            "src/actions/github_action.ts",
+            "src/actions/github_action_completion.ts",
+            "src/actions/github_action_execution.ts",
+            "src/application/policies/action_summary_policy.ts",
+            "src/application/policies/comment_translation_policy.ts",
+            "src/application/policies/copilot_interaction_policy.ts",
+            "src/application/policies/publication_message_catalog.ts",
+            "src/application/policies/semantic_result_publication_policy.ts",
+            "src/application/policies/setup_configuration_defaults.ts",
+            "src/application/policies/setup_configuration_plan.ts",
+            "src/application/policies/setup_doctor_report_policy.ts",
+            "src/application/policies/status_command_policy.ts",
+            "src/application/usecases/localization/resolve_message_catalog_use_case.ts",
+            "src/application/usecases/setup/doctor_use_case.ts",
+            "src/application/usecases/setup/setup_wizard_use_case.ts",
+            "src/application/usecases/steps/common/comment_language_translation_workflow.ts",
+            "src/application/usecases/steps/common/publish_resume_use_case.ts",
+            "src/application/usecases/steps/common/publish_resume_workflow.ts",
+            "src/application/usecases/steps/common/reply_publication_workflow.ts",
+            "src/application/usecases/steps/common/status_card_publication_workflow.ts",
+            "src/domain/locale.ts",
+            "src/domain/message_catalog.ts"
+          ],
+          "mode": "aggregate",
+          "thresholdProfile": "default"
+        }
+      ],
+      "successMessage": "repository localization coverage: PASS (pure policies 100%; changed path 95% lines/statements, 90% branches/functions)"
     }
   ]
 }

scripts/validate-workflow-contract.cjs

@@ -94,6 +94,11 @@ const WORKFLOW_AGENT_ROLES = Object.freeze({
   'copilot_issue_comment.yml': ['findings', 'fixer', 'planner', 'reviewer', 'tester'],
   'copilot_pull_request_comment.yml': ['findings', 'fixer', 'planner', 'reviewer', 'tester'],
 });
+const REPOSITORY_LOCALE_INPUTS = Object.freeze({
+  'repository-locale': "${{ vars.REPOSITORY_LOCALE || 'en-US' }}",
+  'issues-locale': "${{ vars.ISSUES_LOCALE || '' }}",
+  'pull-requests-locale': "${{ vars.PULL_REQUESTS_LOCALE || '' }}",
+});
 
 function workflowFiles(directory) {
   return readdirSync(directory)
@@ -207,6 +212,22 @@ function assertAgentInputs(file, workflow) {
   }
 }
 
+function assertRepositoryLocaleInputs(file, workflow) {
+  const relativeFile = relativeWorkflow(file);
+  if (!WORKFLOW_AGENT_ROLES[path.basename(file)]) return;
+  for (const [jobId, job] of Object.entries(workflow.jobs ?? {})) {
+    for (const [stepIndex, step] of (job.steps ?? []).entries()) {
+      if (!isCopilotAction(step)) continue;
+      const invalid = Object.entries(REPOSITORY_LOCALE_INPUTS)
+        .filter(([input, value]) => step.with?.[input] !== value)
+        .map(([input]) => input);
+      if (invalid.length > 0) {
+        throw new Error(`${relativeFile} job ${jobId} step ${stepIndex + 1} must pass the repository locale and inheriting empty scope overrides exactly; invalid: ${invalid.join(', ')}.`);
+      }
+    }
+  }
+}
+
 function assertAgentInstallationPrerequisites(file, workflow) {
   const manifestFile = path.basename(file);
   if (!WORKFLOW_AGENT_ROLES[manifestFile] && manifestFile !== 'agent-cli-provisioning.yml') return;
@@ -837,6 +858,7 @@ function validateWorkflow(file, workflow) {
   assertRunner(file, workflow);
   assertSequentialMutationWorkflow(file, workflow);
   assertAgentInputs(file, workflow);
+  assertRepositoryLocaleInputs(file, workflow);
   assertAgentInstallationPrerequisites(file, workflow);
   assertNoJobLevelSecrets(file, workflow);
   assertAgentWorkflowPermissions(file, workflow);
@@ -887,6 +909,7 @@ module.exports = {
   assertMajorActionReferences,
   assertCopilotActionInputs,
   assertAgentInputs,
+  assertRepositoryLocaleInputs,
   assertAgentInstallationPrerequisites,
   assertNoJobLevelSecrets,
   assertAgentWorkflowPermissions,

setup/workflows/copilot_commit.yml

@@ -44,6 +44,9 @@ jobs:
 
       - uses: vypdev/copilot@v3
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: ${{ vars.AI_IGNORE_FILES || 'build/*' }}
           debug: ${{ vars.DEBUG }}
           main-branch: ${{ vars.MAIN_BRANCH || 'master' }}
@@ -58,8 +61,6 @@ jobs:
           reopen-issue-on-push: ${{ vars.REOPEN_ISSUE_ON_PUSH || 'true' }}
           desired-assignees-count: ${{ vars.DESIRED_ASSIGNEES_COUNT || '1' }}
           desired-reviewers-count: ${{ vars.DESIRED_REVIEWERS_COUNT || '1' }}
-          issues-locale: ${{ vars.ISSUES_LOCALE || 'en-US' }}
-          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || 'en-US' }}
           commit-prefix-transforms: ${{ vars.COMMIT_PREFIX_TRANSFORMS || 'replace-slash' }}
           ai-pull-request-description-mode: ${{ vars.AI_PULL_REQUEST_DESCRIPTION_MODE || 'replace' }}
           ai-members-only: ${{ vars.AI_MEMBERS_ONLY || 'false' }}

setup/workflows/copilot_issue.yml

@@ -25,6 +25,9 @@ jobs:
 
       - uses: vypdev/copilot@v3
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: ${{ vars.AI_IGNORE_FILES || 'build/*' }}
           debug: ${{ vars.DEBUG }}
           main-branch: ${{ vars.MAIN_BRANCH || 'master' }}
@@ -39,8 +42,6 @@ jobs:
           reopen-issue-on-push: ${{ vars.REOPEN_ISSUE_ON_PUSH || 'true' }}
           desired-assignees-count: ${{ vars.DESIRED_ASSIGNEES_COUNT || '1' }}
           desired-reviewers-count: ${{ vars.DESIRED_REVIEWERS_COUNT || '1' }}
-          issues-locale: ${{ vars.ISSUES_LOCALE || 'en-US' }}
-          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || 'en-US' }}
           commit-prefix-transforms: ${{ vars.COMMIT_PREFIX_TRANSFORMS || 'replace-slash' }}
           ai-pull-request-description-mode: ${{ vars.AI_PULL_REQUEST_DESCRIPTION_MODE || 'replace' }}
           ai-members-only: ${{ vars.AI_MEMBERS_ONLY || 'false' }}

setup/workflows/copilot_issue_comment.yml

@@ -26,6 +26,9 @@ jobs:
 
       - uses: vypdev/copilot@v3
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: ${{ vars.AI_IGNORE_FILES || 'build/*' }}
           debug: ${{ vars.DEBUG }}
           main-branch: ${{ vars.MAIN_BRANCH || 'master' }}
@@ -40,8 +43,6 @@ jobs:
           reopen-issue-on-push: ${{ vars.REOPEN_ISSUE_ON_PUSH || 'true' }}
           desired-assignees-count: ${{ vars.DESIRED_ASSIGNEES_COUNT || '1' }}
           desired-reviewers-count: ${{ vars.DESIRED_REVIEWERS_COUNT || '1' }}
-          issues-locale: ${{ vars.ISSUES_LOCALE || 'en-US' }}
-          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || 'en-US' }}
           commit-prefix-transforms: ${{ vars.COMMIT_PREFIX_TRANSFORMS || 'replace-slash' }}
           ai-pull-request-description-mode: ${{ vars.AI_PULL_REQUEST_DESCRIPTION_MODE || 'replace' }}
           ai-members-only: ${{ vars.AI_MEMBERS_ONLY || 'false' }}

setup/workflows/copilot_pull_request.yml

@@ -57,6 +57,9 @@ jobs:
 
       - uses: vypdev/copilot@v3
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: ${{ vars.AI_IGNORE_FILES || 'build/*' }}
           debug: ${{ vars.DEBUG }}
           main-branch: ${{ vars.MAIN_BRANCH || 'master' }}
@@ -71,8 +74,6 @@ jobs:
           reopen-issue-on-push: ${{ vars.REOPEN_ISSUE_ON_PUSH || 'true' }}
           desired-assignees-count: ${{ vars.DESIRED_ASSIGNEES_COUNT || '1' }}
           desired-reviewers-count: ${{ vars.DESIRED_REVIEWERS_COUNT || '1' }}
-          issues-locale: ${{ vars.ISSUES_LOCALE || 'en-US' }}
-          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || 'en-US' }}
           commit-prefix-transforms: ${{ vars.COMMIT_PREFIX_TRANSFORMS || 'replace-slash' }}
           ai-pull-request-description-mode: ${{ vars.AI_PULL_REQUEST_DESCRIPTION_MODE || 'replace' }}
           ai-members-only: ${{ vars.AI_MEMBERS_ONLY || 'false' }}

setup/workflows/copilot_pull_request_comment.yml

@@ -26,6 +26,9 @@ jobs:
 
       - uses: vypdev/copilot@v3
         with:
+          repository-locale: ${{ vars.REPOSITORY_LOCALE || 'en-US' }}
+          issues-locale: ${{ vars.ISSUES_LOCALE || '' }}
+          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || '' }}
           ai-ignore-files: ${{ vars.AI_IGNORE_FILES || 'build/*' }}
           debug: ${{ vars.DEBUG }}
           main-branch: ${{ vars.MAIN_BRANCH || 'master' }}
@@ -40,8 +43,6 @@ jobs:
           reopen-issue-on-push: ${{ vars.REOPEN_ISSUE_ON_PUSH || 'true' }}
           desired-assignees-count: ${{ vars.DESIRED_ASSIGNEES_COUNT || '1' }}
           desired-reviewers-count: ${{ vars.DESIRED_REVIEWERS_COUNT || '1' }}
-          issues-locale: ${{ vars.ISSUES_LOCALE || 'en-US' }}
-          pull-requests-locale: ${{ vars.PULL_REQUESTS_LOCALE || 'en-US' }}
           commit-prefix-transforms: ${{ vars.COMMIT_PREFIX_TRANSFORMS || 'replace-slash' }}
           ai-pull-request-description-mode: ${{ vars.AI_PULL_REQUEST_DESCRIPTION_MODE || 'replace' }}
           ai-members-only: ${{ vars.AI_MEMBERS_ONLY || 'false' }}