From e21ea5f9cff1c0349613bb4bb411ce234862cbf9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=98=A5=E6=B2=B3=E6=99=B4?= <bbleae@outlook.com>
Date: Fri, 13 Mar 2026 19:33:36 +0900
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E4=BB=A5=E8=AF=B4=E6=98=8E=E5=B7=A5=E4=BD=9C=E6=B5=81=E5=8F=AF?=
 =?UTF-8?q?=E8=A7=81=E6=80=A7=E8=A6=81=E6=B1=82=E5=92=8C=20GitHub=20CLI=20?=
 =?UTF-8?q?=E4=BD=BF=E7=94=A8=E6=96=B9=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/github-actions-crowdin-workflow-report.md | 11 +++++++++--
 docs/i18n.md                                   |  5 +++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/docs/github-actions-crowdin-workflow-report.md b/docs/github-actions-crowdin-workflow-report.md
index 8346cff8..f98ecc6e 100644
--- a/docs/github-actions-crowdin-workflow-report.md
+++ b/docs/github-actions-crowdin-workflow-report.md
@@ -56,6 +56,11 @@ Triggers:
 
 - manual dispatch only
 
+Visibility requirement:
+
+- because this workflow uses `workflow_dispatch`, GitHub only exposes it after the workflow file exists on the repository default branch
+- in this repository, maintainers should merge the workflow file into `main` before expecting it to appear in the Actions UI or be runnable through `gh workflow run`
+
 Inputs:
 
 - `base_branch`: `main` or `r-dev`
@@ -225,6 +230,7 @@ Effect:
 GitHub UI:
 
 - Actions -> `Crowdin Bootstrap Target Translations`
+- if it does not appear yet, first make sure the workflow file has already landed on the default branch (`main`)
 - choose `main` or `r-dev`
 - set `confirm_bootstrap` to `yes-bootstrap-current-target-translations`
 
@@ -232,7 +238,7 @@ GitHub CLI:
 
 ```bash
 gh workflow run crowdin-bootstrap.yml \
-  --ref r-dev \
+  --ref main \
   -f base_branch=r-dev \
   -f confirm_bootstrap=yes-bootstrap-current-target-translations
 ```
@@ -244,12 +250,13 @@ Use this only when seeding Crowdin from already-committed target translations, o
 GitHub UI:
 
 - Actions -> `Crowdin Sync`
+- if a newly added manual workflow does not appear, confirm that workflow file is already on the default branch
 - run the workflow on `main` or `r-dev`
 
 GitHub CLI:
 
 ```bash
-gh workflow run crowdin-sync.yml --ref r-dev
+gh workflow run crowdin-sync.yml --ref main
 ```
 
 ### Inspect workflow runs
diff --git a/docs/i18n.md b/docs/i18n.md
index 62363cc4..92d555b9 100644
--- a/docs/i18n.md
+++ b/docs/i18n.md
@@ -160,13 +160,14 @@ GitHub Actions 中的 [`crowdin-sync.yml`](../.github/workflows/crowdin-sync.yml
 - 只能手动触发。
 - 会把仓库当前已提交的目标语言文件上传到 Crowdin，用来保留历史翻译。
 - 不会作为日常 workflow 持续上传 GitHub 中的目标语言改动。
+- 这个 workflow 必须先存在于仓库默认分支后，才会在 GitHub 网页端出现，也才能被 `gh workflow run` 调用。
 
 常用命令：
 
 ```bash
 python scripts/i18n_validate.py
-gh workflow run crowdin-sync.yml --ref r-dev
-gh workflow run crowdin-bootstrap.yml --ref r-dev -f base_branch=r-dev -f confirm_bootstrap=yes-bootstrap-current-target-translations
+gh workflow run crowdin-sync.yml --ref main
+gh workflow run crowdin-bootstrap.yml --ref main -f base_branch=r-dev -f confirm_bootstrap=yes-bootstrap-current-target-translations
 gh run list --workflow crowdin-sync.yml --limit 5
 gh pr list --head l10n_r-dev
 ```