[luv-307] fix: bump translate-docs retries 2→5 and concurrency 2→4 post-LiteLLM-scale

[NiveditJain]

Summary

• scripts/translate-docs/translator.ts — pass maxRetries (default 5, up from the SDK default of 2) to new Anthropic({ maxRetries }). Override via TRANSLATE_MAX_RETRIES (integer ≥ 0; 0 disables retries). The SDK already retries APIConnectionError / APIConnectionTimeoutError / 408/409/429/5xx with exponential backoff + jitter; we just need it to retry more so the LB has more chances to route a retry to a healthy LiteLLM replica.
• scripts/translate-docs/cli.ts — raise per-job MAX_CONCURRENT from 2 to 4 (env-overridable via TRANSLATE_MAX_CONCURRENT, integer ≥ 1) and rewrite the inline comment that cited the pre-scale gateway-cliff state. With CI matrix max-parallel: 4 unchanged, global ceiling moves from 4×2=8 to 4×4=16 in flight — still half the failure-mode threshold of ~28 from [luv-306] fix: cap translate-docs matrix at max-parallel: 4 #305 even before the LiteLLM scale-out.
• CHANGELOG.md — Unreleased→Fixes entry documenting the change, prior context ([translate-docs] use claude-haiku-4-5 alias instead of dated snapshot #300, [luv-306] fix: cap translate-docs matrix at max-parallel: 4 #305), and motivation (LiteLLM was horizontally scaled per github.com/exospherehost/platform; previous cap leaves capacity on the floor; remaining transient Connection error. failures are per-request and need explicit retry budget).
• Env parsing hardening (per CodeRabbit feedback): both env vars now use Number.parseInt + Number.isInteger range checks instead of Number(env) || N. The prior form treated "0" as unset and silently accepted negatives — for MAX_CONCURRENT, a 0 or negative override would spawn zero workers via Math.min(MAX_CONCURRENT, tasks.length) and hang the run.
• .gitignore — drive-by chore: ignore local .monitor-*.sh / .monitor-*.log scratch files used for ad-hoc CI watch loops.

Empirically observed before this change: bun scripts/translate-docs/cli.ts --languages zh --force returned 2 successes + 2 Connection error. lines on the 5 uncached Tier-1 (Sonnet) MDX pages. Post-fix the SDK's 5-retry budget should absorb those transients; concurrency bump takes back the throughput the prior cap forfeited.

Test plan

• bunx tsc --noEmit clean
• bun run lint scripts/translate-docs/translator.ts scripts/translate-docs/cli.ts clean (only a pre-existing unrelated <img> warning in app/)
• bun scripts/translate-docs/cli.ts --languages zh --dry-run runs end-to-end with no errors
• CI green (quality / test / build / test-e2e) on the latest commit
• Live Translate Docs workflow run on main goes green across the full 14-language matrix (currently being monitored on run 25535770708)
• Local re-run with default settings: bun scripts/translate-docs/cli.ts --languages zh --force finishes with no Connection error. lines (live API)
• Override path with custom limits via TRANSLATE_MAX_CONCURRENT and TRANSLATE_MAX_RETRIES succeeds (live API)

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d2e37b4e-6121-4050-9337-9673433da6f7

📥 Commits

Reviewing files that changed from the base of the PR and between eeb58e1 and 92788f5.

📒 Files selected for processing (2)

• scripts/translate-docs/cli.ts
• scripts/translate-docs/translator.ts

---

📝 Walkthrough

Walkthrough

This PR makes translate-docs retry and per-job concurrency configurable via environment variables (TRANSLATE_MAX_RETRIES default 5, TRANSLATE_MAX_CONCURRENT default 4), updates the Anthropic client to use the retry setting, and documents capping the workflow matrix at max-parallel: 4.

Changes

Translate-docs Concurrency and Retry Configuration

Layer / File(s)	Summary
SDK Client Retry Configuration scripts/translate-docs/translator.ts	getClient() reads TRANSLATE_MAX_RETRIES from environment (default 5) and passes it as maxRetries to new Anthropic({ maxRetries }).
CLI Concurrency Limiter Configuration scripts/translate-docs/cli.ts	MAX_CONCURRENT is computed from process.env.TRANSLATE_MAX_CONCURRENT (integer ≥1, default 4) and used by runWithConcurrency to limit concurrent translation jobs.
Changelog Documentation CHANGELOG.md	Unreleased notes updated to record SDK retry tuning, CLI concurrency increase, env var overrides, and workflow matrix cap at max-parallel: 4.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• exospherehost/failproofai#305: Caps translate-docs workflow matrix at max-parallel: 4 to reduce cross-job in-flight requests.
• exospherehost/failproofai#300: Modifies MAX_CONCURRENT in scripts/translate-docs/cli.ts concurrency configuration.

Poem

🐰 I nibble env vars, gentle and spry,

Retries set to five so failures pass by,
Four hops at a time, concurrency neat,
Docs note the change — the pipeline's heartbeat,
A rabbit-approved tune for a steadier sky.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main changes: increasing retry policy to 5 and concurrency to 4 for the translate-docs script, with context about the LiteLLM scaling that motivated these changes.
Description check	✅ Passed	The description comprehensively covers the required template sections with detailed explanations of changes, motivation, env-var hardening, observed vs. expected behavior, and a test plan with specific verification steps.
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.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

scripts/translate-docs/cli.ts (1)

189-199: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate TRANSLATE_MAX_CONCURRENT before using it as worker count.

Line 189 accepts negative values and Line 199 can then create zero workers, causing queued translation tasks to never execute.

Suggested fix

-  const MAX_CONCURRENT = Number(process.env.TRANSLATE_MAX_CONCURRENT) || 4;
+  const parsedConcurrent = Number.parseInt(process.env.TRANSLATE_MAX_CONCURRENT ?? "", 10);
+  const MAX_CONCURRENT =
+    Number.isInteger(parsedConcurrent) && parsedConcurrent > 0
+      ? parsedConcurrent
+      : 4;
@@
-    await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT, tasks.length) }, () => next()));
+    const workers = Math.min(MAX_CONCURRENT, tasks.length);
+    await Promise.all(Array.from({ length: workers }, () => next()));

🤖 Prompt for 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.

In `@scripts/translate-docs/cli.ts` around lines 189 - 199, The MAX_CONCURRENT
value can be negative or zero causing Promise.all to spawn 0 workers and hang;
validate and normalize it when constructing MAX_CONCURRENT used by
runWithConcurrency: parse the env value as an integer (e.g., parseInt or
Number), clamp it to a sensible range (>=1 and optionally an upper cap), and
fallback to the default 4 only if parsing fails; update the constant
MAX_CONCURRENT and ensure the Promise.all Array.from length uses this validated
positive integer so next() workers are always created. Reference symbols:
MAX_CONCURRENT, runWithConcurrency, and the Promise.all(Array.from(..., () =>
next())) worker creation.

🤖 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 `@scripts/translate-docs/translator.ts`:
- Around line 12-13: The env parsing for TRANSLATE_MAX_RETRIES is brittle
(treats "0" as falsy and allows negatives); update the logic that sets
maxRetries so it explicitly parses TRANSLATE_MAX_RETRIES (use parseInt or Number
and Number.isInteger), verify the parsed value is a finite integer >= 0, and
only fall back to the default 5 when the env is absent or invalid; then pass
that validated maxRetries into the Anthropic client constructor (the variable
maxRetries and the new Anthropic({ maxRetries }) call).

---

Outside diff comments:
In `@scripts/translate-docs/cli.ts`:
- Around line 189-199: The MAX_CONCURRENT value can be negative or zero causing
Promise.all to spawn 0 workers and hang; validate and normalize it when
constructing MAX_CONCURRENT used by runWithConcurrency: parse the env value as
an integer (e.g., parseInt or Number), clamp it to a sensible range (>=1 and
optionally an upper cap), and fallback to the default 4 only if parsing fails;
update the constant MAX_CONCURRENT and ensure the Promise.all Array.from length
uses this validated positive integer so next() workers are always created.
Reference symbols: MAX_CONCURRENT, runWithConcurrency, and the
Promise.all(Array.from(..., () => next())) worker creation.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4e156f5a-95b9-4da6-ab05-20de4c885f82

📥 Commits

Reviewing files that changed from the base of the PR and between 8492575 and eeb58e1.

📒 Files selected for processing (3)

• CHANGELOG.md
• scripts/translate-docs/cli.ts
• scripts/translate-docs/translator.ts