# Coding Agent Alignment Brief: GitHub-Side Crowdin Workflow for MaiBot

## Purpose

Use this document as the authoritative implementation and maintenance guide for the repository's GitHub-side Crowdin workflow.

Its purpose is to keep Coding Agent aligned with the agreed operating model and prevent drift from the intended localization strategy.

This document is normative for:
- GitHub Actions changes related to Crowdin sync and localization PR flow
- branch and PR behavior for localization updates
- repository-side validation behavior for localization assets
- boundaries between baseline workflow logic and repository-specific policy

This document is **not** a generic Crowdin tutorial.
It describes the expected behavior for this repository specifically.

---

## Core Operating Model

The repository uses a **PR-based localization return flow**.

### Source branches covered by localization sync
- `main`
- `r-dev`

### Localization return branches
- `l10n_main`
- `l10n_r-dev`

### Return path
- Crowdin translations must **not** be pushed directly into `main` or `r-dev`.
- Translations must return through `l10n_${branch}` branches.
- Localization changes must reach `main` or `r-dev` through pull requests.

### Source-language assets
The source language is `zh-CN`.
Only source-language assets should trigger source uploads to Crowdin.

Current source-language assets:
- `locales/zh-CN/*.json`
- `prompts/zh-CN/**/*.prompt`
- `dashboard/src/i18n/locales/zh.json`
- `crowdin.yml`

### Prompt template extension
The repository currently treats `.prompt` as the only i18n-relevant prompt template extension.
Do not broaden prompt-related workflow triggers unless repository reality changes.

---

## Mandatory Interpretation Rules

Coding Agent must follow these interpretation rules exactly.

### Rule 1: Do not reinterpret `l10n_` branches
`l10n_main` and `l10n_r-dev` are service/localization return branches.
They are not feature branches and they are not alternate long-lived development branches.

### Rule 2: Do not bypass the PR model
Do not change the workflow so that translated assets are committed directly to `main` or `r-dev`.
The agreed model is:
- source branch sync
- Crowdin-side translation availability
- localization return branch update
- PR into the matching base branch
- maintainer review and merge

### Rule 3: Do not claim approval in Crowdin means immediate GitHub update
A translation being reviewed or approved in Crowdin does **not** mean GitHub is updated instantly.
GitHub reflects Crowdin-side updates only when the sync workflow runs.

That can happen via:
- push-triggered sync
- scheduled sync
- manual dispatch

Any documentation, comments, or workflow descriptions produced by Coding Agent must preserve this distinction.

### Rule 4: Treat GitHub-side content policy as repository-specific, not as a universal Crowdin rule
If the repository enforces extra validation rules on committed target locale content, those rules must be described as **repository-specific policy**.
They must not be described as an inherent or standard requirement of Crowdin's branch model.

### Rule 5: Preserve source-upload loop prevention
Do not modify the workflow in a way that allows translated target files to trigger a new source upload cycle to Crowdin.
Only source-language assets should trigger source uploads.

---

## Required GitHub Workflow Behavior

### 1. `crowdin-sync.yml`

This workflow must remain responsible for:
- uploading source-language assets to Crowdin
- downloading available translations from Crowdin
- creating or updating localization return branches
- creating or updating localization PRs into the matching source branch

#### Required triggers
The workflow may be triggered by:
- manual dispatch
- schedule
- push to `main` or `r-dev` when source-language assets change

#### Required branch mapping
The workflow must preserve this mapping:
- `main -> l10n_main -> PR into main`
- `r-dev -> l10n_r-dev -> PR into r-dev`

#### Required boundary
The workflow must preserve the PR-based return flow.
It must not be converted into direct translation pushes into `main` or `r-dev`.

#### Required wording discipline
When describing this workflow, Coding Agent must say that it downloads **currently available** Crowdin translations when the workflow runs.
Coding Agent must not imply that source-language pushes and translation return are a single synchronous transaction.

---

### 2. `precheck.yml`

This workflow must:
- run on pull requests
- check merge/conflict state against the **real PR base branch**

#### Required base-branch logic
For every PR, conflict simulation must use the actual PR target branch.
Examples:
- feature branch into `main` -> compare against `main`
- feature branch into `r-dev` -> compare against `r-dev`
- `l10n_main` PR -> compare against `main`
- `l10n_r-dev` PR -> compare against `r-dev`

#### Forbidden behavior
Coding Agent must not reintroduce any logic that hardcodes `main` as the comparison base for all PRs.

#### Label behavior
If the repository already uses a conflict label, that behavior should remain intact unless there is a clearly documented reason to change it.

---

### 3. `ruff-pr.yml`

This workflow must remain focused on Python code quality.

#### Required path discipline
Translation-only localization PRs must not trigger Ruff by default.
Ruff should run only when files relevant to Python code quality or Ruff configuration are changed.

#### Practical intent
The goal is to reduce CI noise on localization PRs without weakening Python quality checks.

#### Forbidden behavior
Do not expand Ruff triggers so broadly that translation-only localization PRs start running Ruff again by default.

---

### 4. `i18n-validate.yml`

This workflow must remain the repository-side structural validation layer for localization changes.

#### Required validation role
It should validate localization assets and i18n-relevant code changes.
That includes both:
- backend locale JSON under `locales/`
- dashboard locale JSON under `dashboard/src/i18n/locales/`

#### Prompt trigger scope
It must cover the actual prompt template extension used in the repository.
At present, that means `.prompt`.
Do not broaden the watched prompt-file patterns unless repository reality changes.

#### Missing prompt behavior
If localized prompt files are intentionally allowed to fall back to `zh-CN` at runtime, workflow and documentation should represent that accurately.
Do not silently convert warning-only behavior into hard-failure behavior unless explicitly instructed.

---

## Repository-Specific Policy Layer

The repository may enforce extra policy rules on committed target locale files.
Examples may include:
- forbidding unchanged source-language carry-over in target locale files
- forbidding Chinese characters in `en-US` locale files
- placeholder consistency checks
- plural structure checks

These rules are allowed.
However, Coding Agent must always describe them as:
- repository-specific validation policy
- layered on top of the baseline Crowdin PR workflow

They must **not** be described as:
- a standard Crowdin requirement
- an inherent property of `l10n_` branches
- something every Crowdin GitHub integration does by default

---

## Documentation Guardrails for Coding Agent

Whenever Coding Agent writes or updates repository documentation about localization workflow, it must obey the following rules.

### Always state these facts clearly
- `zh-CN` is the source language
- `main` and `r-dev` are the source branches covered by Crowdin sync
- translations return via `l10n_${branch}` branches
- localization changes reach `main` or `r-dev` through PRs
- GitHub receives translation updates when the sync workflow runs, not necessarily immediately when approval happens in Crowdin

### Never blur these concepts
Do not conflate:
- Crowdin approval state
- GitHub sync timing
- PR creation/update timing
- PR merge timing

These are related but distinct steps.

### Always distinguish baseline workflow from extra repository policy
If describing validation rules beyond branch flow and sync behavior, explicitly mark them as repository-specific policy.

### Keep statements operational and repository-specific
Do not write generic platform marketing language.
Do not convert this repository's workflow report into a generic localization tutorial.

---

## Change Control Rules

Coding Agent may adjust workflows only within the following boundaries.

### Allowed changes
Coding Agent may:
- fix PR base-branch detection bugs
- reduce CI noise for translation-only PRs
- tighten path filters to better match repository reality
- improve workflow descriptions so they do not misrepresent sync timing
- improve documentation clarity around repository-specific validation policy

### Allowed changes with explicit justification
Coding Agent may change repository-side i18n validation rules only if:
- the change is clearly labeled as repository-specific policy
- the justification is documented
- the change does not misrepresent itself as standard Crowdin behavior

### Forbidden changes
Coding Agent must not:
- replace the `l10n_${branch}` PR model with direct pushes into source branches
- make translated target files trigger source uploads back to Crowdin
- hardcode `main` as the merge-check target for all PRs
- broaden prompt-file watchers without confirming actual repository usage
- present repository-specific locale policy as if it were part of Crowdin's default model
- imply that approved translations automatically and immediately appear in GitHub without a sync run

---

## Expected End-to-End Flow

### Flow A: Source-language update
1. A source-language asset change is pushed to `main` or `r-dev`.
2. The Crowdin sync workflow runs.
3. The workflow uploads source-language assets to Crowdin.
4. The workflow may also download any translations currently available in Crowdin.
5. The workflow creates or updates the matching localization return branch.
6. A PR is created or updated from `l10n_${branch}` into the matching base branch.

### Flow B: Localization PR validation
1. A PR from `l10n_${branch}` into its matching base branch exists.
2. `precheck.yml` validates merge/conflict state against the real PR base branch.
3. `i18n-validate.yml` validates localization structure and repository-specific i18n policy.
4. `ruff-pr.yml` does not run unless the PR touches Python/Ruff-relevant files.
5. Maintainers review and merge the PR.

### Flow C: Scheduled synchronization
1. The scheduled Crowdin sync workflow runs.
2. It processes the supported source branches.
3. If Crowdin currently has downloadable translation updates, GitHub updates or creates the corresponding `l10n_` branch PRs.

---

## Coding Agent Self-Check Before Making Any Workflow or Docs Change

Before changing localization-related workflows or documentation, Coding Agent must confirm all of the following:

1. Am I preserving the `l10n_${branch}` PR-based return model?
2. Am I avoiding any claim that Crowdin approval instantly updates GitHub?
3. Am I keeping source-upload triggers limited to source-language assets?
4. Am I using the real PR base branch for conflict checks?
5. Am I keeping Ruff out of translation-only PRs by default?
6. Am I limiting prompt-file trigger patterns to what the repository actually uses?
7. If I describe extra locale-content rules, did I label them as repository-specific policy rather than standard Crowdin behavior?

If any answer is no, the change is not aligned and must be revised.

---

## Bottom Line

The correct GitHub-side localization model for this repository is:
- `zh-CN` is the source language
- `main` and `r-dev` are the source branches
- Crowdin returns translations through `l10n_${branch}` branches
- localization changes reach source branches through PRs
- sync timing depends on GitHub-side workflow execution
- repository-specific locale validation policy may exist, but it must be described as extra policy, not as the default Crowdin model

Coding Agent must preserve this model and must not drift into a direct-push workflow, a misleading sync description, or an over-generalized explanation of repository-specific validation rules.