docs(i18n): keep auto-translate routine to a single open PR

[WolfSoko]

What

Updates the Claude auto-translate routine so it keeps exactly one open translation PR at a time and updates the already-open one instead of opening a new PR on every run.

Why

The routine is triggered daily (06:00 UTC) and on every push to main that touches i18n source. Previously it created a fresh date-stamped branch claude/translations-<YYYY-MM-DD> and opened a new PR each run, so open translation PRs accumulated — one per run — until each was merged.

How

In .claude/routines/translate.md (the routine prompt) the flow becomes:

1. Find the existing PR first — look for an open PR whose head is the fixed branch claude/translations; if several chore(i18n) PRs somehow exist, converge back to one.
2. Reuse or create the single branch claude/translations (no date suffix):
   • Reusing: check it out and merge origin/main into it — a non-rewriting update that preserves every commit on the PR, including human review corrections. On merge conflict, abort and stop/report rather than discarding history.
   • Creating: branch from the tip of main.
3. Detect gaps on that branch, so units already translated on the open PR keep state="translated" and aren't re-flagged — only genuinely new gaps are added.
4. Plain fast-forward push to claude/translations — because step 2 only ever merges (never rewrites history), no force-push is needed.
5. Open or update the single PR (update_pull_request refreshes title + body) — never a second one. The title <count> is derived from the branch's diff against origin/main (XLIFF units now translated + new blog/wiki files), not the detector's single-run gap_count.

New steady-state handling: if there are no new gaps but a translation PR is already open, the routine re-pushes only if main advanced (to keep it mergeable) and otherwise leaves it to merge. On merge, the branch is deleted (squash + delete branch) so the next run starts clean from main.

docs/gotchas/i18n.md is updated to describe the single-PR / update-in-place behavior.

Notes

• Docs/prompt-only change — the detector (tools/src/detect-translation-gaps.mjs) and seeder are untouched, so no code tests are affected.
• The Allow unrestricted branch pushes setting can stay off; the routine only ever fast-forward-pushes the single claude/translations branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NQH6VBPhDr46yJMMH9dGcJ

[coderabbitai]

📝 Walkthrough

Walkthrough

The translation routine in .claude/routines/translate.md is rewritten to maintain exactly one long-lived PR on the claude/translations branch instead of creating fresh date-stamped branches. It consolidates duplicate open PRs, merges origin/main forward (no rebase), and drives exit vs. update decisions from gap-detection output. The i18n gotcha doc updates its one-line description to match.

Changes

Translation routine: single long-lived PR strategy

Layer / File(s)	Summary
Goal definition and Setup permissions .claude/routines/translate.md, docs/gotchas/i18n.md	Goal section declares the claude/translations branch invariant and distinct exit/update paths for the zero-gaps case; Setup section restricts pushes to claude/translations with merge/fast-forward semantics only. The i18n gotcha doc updates its one-line description from date-based to persistent PR behavior.
PR consolidation, branch checkout, and main merge .claude/routines/translate.md	Adds step logic to find the open PR whose head is claude/translations, verify the branch remotely, close any extra matching PRs, and either check out the existing branch and merge origin/main into it (aborting on conflict) or create it fresh from origin/main.
Gap detection and exit/update decision .claude/routines/translate.md	Replaces the old "if no gaps, exit" block with a summary.env-driven decision that handles three states: no gaps and no PR (exit), no gaps but PR open (re-push only if main advanced, no empty commit), and gaps present (proceed to commit/push).
Commit, push, and PR create/update .claude/routines/translate.md	Commits only specified paths (excluding .claude-translations artifacts) to claude/translations, upserts exactly one PR against main with a refreshed title/body showing translation count and per-locale breakdown, restricts subscribe_pr_activity to newly-created PRs, and deletes the branch after merge.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• WolfSoko/pushup-stats-service#417: Initially established the date-stamped claude/translations-<YYYY-MM-DD> branch workflow in the same routine file that this PR replaces with the single long-lived branch strategy.

Poem

🐇 Hoppity hop, no more dates in the name,
One branch to rule them, translations the same!
We merge with the main, no rebase in sight,
A single PR kept tidy and right.
The gaps drive the logic, the rabbit's delight~ 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and concisely summarizes the main change: shifting the auto-translate routine from creating multiple date-stamped PRs to maintaining a single long-lived open PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/admiring-bardeen-gu0wgr

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit b31cc35

Command	Status	Duration	Result
nx run cloud-functions:build	✅ Succeeded	<1s	View ↗
nx run web:build -c staging	✅ Succeeded	9s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-20 16:27:32 UTC

[github-actions]

Visit the preview URL for this PR (updated for commit afd58d9):

https://pushup-stats-staging-867b7--pr-488-7r8cjfsu.web.app

_{(expires Sat, 27 Jun 2026 16:28:30 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 43c298a3304e6b54e102dc177faff73680808e1e}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c08d03826

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR updates the Claude auto-translate routine documentation/prompt so translation work is managed through a single long-lived branch (claude/translations) and a single PR that gets updated in place, avoiding one-PR-per-run accumulation.

Changes:

• Switch translation PR flow from date-stamped branches to a single claude/translations branch with in-place PR updates.
• Add explicit “exit decision” behavior for runs with no gaps vs. an already-open translation PR.
• Document the single-PR behavior in the i18n gotchas guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/gotchas/i18n.md	Documents the “single open translations PR” behavior and when the routine exits vs. leaves an existing PR open.
.claude/routines/translate.md	Updates the routine prompt to find/reuse a single PR/branch, detect gaps on that branch, and update the PR in place.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/routines/translate.md:
- Around line 188-215: The instructions reference a `<count>` placeholder in the
commit message (line 194) and PR title (line 208-209) but don't specify how to
calculate it. The definition states it should be "the number of translation
items this branch adds over main (XLIFF units flipped to translated + new
blog/wiki files)" but this differs from the detector's gap_count. Add a
clarification step after the translation work is completed but before
committing: explain that `<count>` must be computed by analyzing the actual
changes made (either by re-running the gap detector and comparing the output, or
by examining the git diff to count XLIFF units where state changed from initial
to translated, plus new blog/wiki files created). Make explicit which approach
is preferred and where to perform this count calculation in the workflow.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 986f5831-a712-4a96-9f11-2a371ed682bb

📥 Commits

Reviewing files that changed from the base of the PR and between ecea521 and b31cc35.

📒 Files selected for processing (2)

• .claude/routines/translate.md
• docs/gotchas/i18n.md

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.