From b2fa7a08003b1ca22d8d5f35a32c80e0e84f5d84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=A5=E6=B2=B3=E6=99=B4?= Date: Fri, 13 Mar 2026 00:54:51 +0900 Subject: [PATCH] docs: align crowdin workflow wording --- .../github-actions-crowdin-workflow-report.md | 219 ++++++++++++++++++ docs/i18n.md | 3 +- 2 files changed, 221 insertions(+), 1 deletion(-) create mode 100644 docs/github-actions-crowdin-workflow-report.md diff --git a/docs/github-actions-crowdin-workflow-report.md b/docs/github-actions-crowdin-workflow-report.md new file mode 100644 index 00000000..0e128d06 --- /dev/null +++ b/docs/github-actions-crowdin-workflow-report.md @@ -0,0 +1,219 @@ +# GitHub-Side Localization Workflow Report + +## Scope + +This document summarizes the current GitHub-side localization workflow in this repository. +It focuses on how GitHub Actions, branch conventions, pull requests, and validation gates work together around Crowdin. + +This is intentionally a repository-specific operational report, not a generic Crowdin or GitHub Actions tutorial. + +## Current Branch Model + +- Source branches covered by the localization workflow: + - `main` + - `r-dev` +- Crowdin return branches: + - `l10n_main` + - `l10n_r-dev` +- Merge strategy: + - translations do not go directly into `main` or `r-dev` + - Crowdin updates return through pull requests and can be reviewed before merge + +## Source of Truth + +- Source locale for JSON translations: `locales/zh-CN/*.json` +- Source locale for prompt templates: `prompts/zh-CN/**/*.prompt` +- Current prompt template extension in the repository: `.prompt` only + +GitHub Actions currently treat `zh-CN` assets as the source-language side of the workflow. +Translated target assets are not used to trigger source uploads back to Crowdin. + +## Workflows Involved + +### 1. `crowdin-sync.yml` + +Role: +- uploads source-language assets to Crowdin +- downloads currently available translations from Crowdin when the workflow runs +- creates or updates localization pull requests back to the matching base branch + +Current triggers: +- manual dispatch +- scheduled sync every 6 hours: `17 */6 * * *` UTC +- push to `main` or `r-dev` when one of these paths changes: + - `crowdin.yml` + - `locales/zh-CN/*.json` + - `prompts/zh-CN/**/*.prompt` + +Current branch behavior: +- push-triggered runs sync the current Git branch and use a matching localization branch name: + - `main -> l10n_main -> PR into main` + - `r-dev -> l10n_r-dev -> PR into r-dev` +- scheduled runs explicitly cover both `main` and `r-dev` + +Current permissions and credentials: +- `contents: write` +- `pull-requests: write` +- `GITHUB_TOKEN` +- `CROWDIN_PROJECT_ID` +- `CROWDIN_PERSONAL_TOKEN` + +Important boundary: +- the workflow keeps the PR-based return flow intact +- it does not directly push translated content into `main` or `r-dev` + +### 2. `i18n-validate.yml` + +Role: +- runs repository-side localization validation +- blocks structurally invalid or policy-breaking localization changes + +Current triggers: +- pull requests that touch: + - `locales/**/*.json` + - `prompts/**/*.prompt` + - `scripts/i18n_validate.py` + - `src/common/i18n/**/*.py` + - `src/common/prompt_i18n.py` + - `src/prompt/prompt_manager.py` +- pushes to `main` or `r-dev` for the same path set + +Current validation scope: +- JSON locale key alignment against `zh-CN` +- placeholder consistency +- plural structure consistency +- prompt placeholder consistency +- English locale protection against Chinese source-language leakage +- rejection of non-`zh-CN` entries that directly preserve Chinese source text + +Prompt behavior note: +- missing target prompt files currently produce warnings, not hard failures +- runtime still falls back to `zh-CN` prompt templates when localized prompt files are absent + +### 3. `precheck.yml` + +Role: +- checks whether a pull request conflicts with its real target branch +- preserves the existing conflict-label behavior + +Current triggers: +- all pull requests + +Current behavior: +- checks out the PR head commit +- fetches the actual PR base branch from `github.event.pull_request.base.ref` +- performs a merge simulation against that real base branch +- marks the PR as conflicted only if the merge simulation produces unmerged files + +This means: +- feature branches into `main` are checked against `main` +- feature branches into `r-dev` are checked against `r-dev` +- `l10n_main` PRs are checked against `main` +- `l10n_r-dev` PRs are checked against `r-dev` + +### 4. `ruff-pr.yml` + +Role: +- runs Ruff lint and format checks for pull requests that are relevant to Python code quality + +Current triggers: +- pull requests that touch: + - `*.py` + - `**/*.py` + - `pyproject.toml` + - `ruff.toml` + - `.ruff.toml` + - `setup.cfg` + - `tox.ini` + - `.pre-commit-config.yaml` + +Effect: +- translation-only localization pull requests do not run Ruff by default +- Python or Ruff-related pull requests still run the existing Ruff checks + +## End-to-End GitHub Flow + +### A. Source-language update on `r-dev` or `main` + +1. A source-language change is pushed to `main` or `r-dev`. +2. `crowdin-sync.yml` uploads source assets to Crowdin. +3. The same workflow may also download any translations currently available in Crowdin when that workflow run executes. +4. A localization PR is opened or updated: + - `l10n_main -> main` + - `l10n_r-dev -> r-dev` + +### B. Localization PR created by Crowdin branch + +1. A localization PR is opened from `l10n_${branch}` into its matching base branch. +2. `precheck.yml` validates conflicts against the real PR base branch. +3. `i18n-validate.yml` validates localization structure and repository-specific locale-content policy. +4. `ruff-pr.yml` does not run if the PR only changes translation assets. +5. Maintainers review and merge the localization PR in the normal PR flow. + +### C. Scheduled sync + +1. Every 6 hours, GitHub Actions runs a scheduled localization sync. +2. The workflow explicitly processes both `main` and `r-dev`. +3. If Crowdin currently has downloadable translation updates, GitHub updates or creates the corresponding `l10n_` PRs. + +## How the Current Setup Avoids Sync Loops + +- Crowdin source uploads are triggered only from source-language assets: + - `locales/zh-CN/*.json` + - `prompts/zh-CN/**/*.prompt` +- translated target files do not trigger another source upload cycle +- translations return through `l10n_` branches and PRs instead of direct pushes to base branches +- translation-only PRs do not trigger Ruff, which reduces unnecessary CI noise without weakening Python quality gates + +## Current Locale Content Policy on GitHub + +This section describes repository-specific validation policy layered on top of the baseline Crowdin PR workflow. +It is not a default Crowdin rule. + +The repository now enforces a stricter GitHub-side policy for committed target locale files: + +- `zh-CN` remains the source language +- non-`zh-CN` locale files must not carry over Chinese source text unchanged +- English locale files must not retain Chinese characters + +This policy is enforced by `scripts/i18n_validate.py` and therefore applies to localization pull requests on GitHub before merge. + +## What Was Verified Against Repository Reality + +- The repository currently uses `.prompt` as the only i18n-relevant prompt template extension. +- `i18n-validate.yml` already watches `prompts/**/*.prompt`, so no broader prompt-file trigger was needed. +- The only committed non-`zh-CN` locale directory currently present in the repository is `locales/en-US`. +- Chinese text previously found in `locales/en-US/startup.json` has been removed. + +## Practical Maintainer Expectations + +- A translation-only PR should normally trigger: + - precheck + - i18n validation +- A translation-only PR should normally not trigger: + - Ruff PR checks +- A Python code PR should normally trigger: + - precheck + - Ruff PR checks + - i18n validation if it touches i18n-related code or locale/prompt assets + +## Open Discussion Topics + +These are not current defects, but they may still be useful discussion topics for the team: + +- whether scheduled source uploads should remain enabled together with scheduled translation downloads +- whether GitHub-side workflow linting should be added explicitly in the future +- whether additional locale-specific content rules should be introduced once more target locales are committed in the repository + +## Bottom Line + +The current GitHub-side localization workflow is now centered on a stable model: + +- `zh-CN` is the source language +- `main` and `r-dev` are the source branches covered by Crowdin sync +- Crowdin returns through `l10n_${branch}` pull requests +- PR conflict checks now use the real base branch +- translation-only PRs no longer run Ruff by default +- GitHub-side i18n validation now also protects against source-language leakage in committed target locales + +This keeps the existing Crowdin branch strategy intact while making pull request validation more accurate and less noisy. diff --git a/docs/i18n.md b/docs/i18n.md index b7760358..ddec2abe 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -87,6 +87,7 @@ Prompt 加载规则： 对于非 `zh-CN` 的目标 locale： +- 下面这两条是当前仓库的额外校验策略，不是 Crowdin 默认行为。 - 不要手工把中文 source 文案直接复制进目标语言文件后提交。 - 英文 locale 文件中不应保留中文字符；这类残留会被校验脚本拦截。 @@ -129,7 +130,7 @@ python scripts/i18n_extract_candidates.py 项目根目录的 [`crowdin.yml`](../crowdin.yml) 使用 `locales/zh-CN/*.json` 作为 source。 现在也会把 `prompts/zh-CN/**/*.prompt` 作为单文件 Prompt 模板 source 上传到 Crowdin。 -GitHub Actions 中的 [`crowdin-sync.yml`](../.github/workflows/crowdin-sync.yml) 会负责和 Crowdin 同步。 +GitHub Actions 中的 [`crowdin-sync.yml`](../.github/workflows/crowdin-sync.yml) 会在 workflow 运行时上传 source，并下载当时 Crowdin 中当前可用的翻译结果。 常用命令：