docs(roadmap): note i18n tooling gaps found during debt repayment

[FullGas1]

Summary

• Two tooling gaps surfaced while working FIX-I18N-DEBT-REPAYMENT (fix(i18n): repay pre-existing KO/ES translation debt (FIX-I18N-DEBT-REPAYMENT) #116), out of scope for that content-only lot, captured here for a future lot to pick up:
  • translate_i18n.py requires a separate ANTHROPIC_API_KEY (own billing) - a Claude Code headless-mode path (claude -p) could use the existing subscription instead, trading CI-compatibility for that.
  • tools/build/i18n_dict_utils.py's parser doesn't distinguish a live dictionary entry from one commented out with -- STALE: , so translate_i18n.py and check_i18n_diff.py both treat dead keys as real stubs/diffs. Also noted: KO/ES dictionaries carry empty entries that CTLD_i18n_en.lua already marks -- STALE: but that aren't marked stale in KO/ES themselves - possible sync drift in generate_i18n_dicts.ps1, not yet root-caused.
• No code change, dev/roadmap.md only.

Test plan

• N/A - documentation only.

Generated with Claude Code

Summary by Sourcery

Document i18n tooling limitations and follow-up work in the roadmap related to translation workflow and stale dictionary handling.

Documentation:

• Add roadmap notes about using Claude Code headless mode as an alternative to direct Anthropic API usage for i18n translation tooling.
• Add roadmap notes about improving i18n dictionary parsing to ignore -- STALE: entries and investigate sync drift between language dictionaries.

[sourcery-ai]

Reviewer's Guide

Documentation-only PR updating dev/roadmap.md to capture two i18n tooling gaps discovered during previous debt repayment work, outlining current behavior and proposed directions for future improvements.

Sequence diagram for translate_i18n.py Anthropic API vs Claude Code CLI flow

sequenceDiagram
  participant translate_i18n_py
  participant anthropic_sdk
  participant claude_cli

  translate_i18n_py->>anthropic_sdk: use ANTHROPIC_API_KEY
  anthropic_sdk-->>translate_i18n_py: return translations

  alt future_claude_code_path
    translate_i18n_py->>claude_cli: call claude -p prompt
    claude_cli-->>translate_i18n_py: return translations
  end

Loading

Flow diagram for i18n_dict_utils.py parse_dict handling STALE entries

flowchart LR
  A[parse_dict line] --> B[strip line]
  B --> C{starts with --}
  C -->|yes| D[ignore entry]
  C -->|no| E[match _ENTRY_RE]
  E --> F[emit dictionary entry]

Loading

File-Level Changes

Change	Details	Files
Document i18n translation tooling limitations and possible shift from direct Anthropic API usage to Claude Code CLI headless mode.	Describe current translate_i18n.py behavior requiring a dedicated ANTHROPIC_API_KEY and separate usage-based billing. Explain contributor pain point when they have Claude Code subscription but no Anthropic API key, forcing manual translation. Outline potential approach to have translate_i18n.py shell out to claude -p (headless CLI) instead of the anthropic SDK. Highlight trade-offs of CLI-based approach, including lack of CI suitability and different cost model, and suggest considering dual mode (API vs CLI) or full replacement.	dev/roadmap.md
Document parsing gap in i18n_dict_utils.py around handling of stale, commented-out dictionary entries and related dictionary drift.	Explain that i18n_dict_utils.py’s regex-based parser currently matches entries even when lines are commented as -- STALE:, causing stale keys to be treated as live. Describe impact on translate_i18n.py and check_i18n_diff.py, which both inherit this behavior via shared parsing logic, leading to wasted translations and diffs for dead keys. Note observed KO/ES dictionary inconsistencies where CTLD_i18n_en.lua marks entries as -- STALE: but KO/ES equivalents remain unmarked, suggesting possible sync issues. Propose that parse_dict/parse_keep_en and callers should ignore lines whose stripped content starts with --, and flag need to investigate generate_i18n_dicts.ps1 for the drift cause.	dev/roadmap.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="dev/roadmap.md" line_range="124-125" />
<code_context>
+une clé API séparée — le script pourrait shell-out vers ce mode au lieu d'utiliser le SDK
+`anthropic`. Compromis à trancher : ça suppose une session Claude Code authentifiée disponible
+partout où le script tourne, ce qui exclut la CI (contrairement à la clé API, qui elle s'y prête) ;
+et ça change le modèle de coût (quota d'abonnement au lieu de facturation API). À grill avant de
+lancer un lot : faut-il un mode dual (API si dispo, sinon CLI), ou remplacer complètement ?
+
+## TOOLING — `i18n_dict_utils.py` ne distingue pas une entrée `-- STALE:` d'une entrée live
</code_context>
<issue_to_address>
**issue (typo):** Typo in “À grill avant de” — “grill” should be corrected.

“À grill avant de lancer un lot” contient vraisemblablement une faute : “grill” n’est pas correct en français ici. Remplace-le par le verbe ou l’expression voulue (par ex. une forme de “griller / mettre sur le grill” ou un autre verbe approprié).

```suggestion
et ça change le modèle de coût (quota d'abonnement au lieu de facturation API). À clarifier avant de
lancer un lot : faut-il un mode dual (API si dispo, sinon CLI), ou remplacer complètement ?
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue (typo): Typo in “À grill avant de” — “grill” should be corrected.

“À grill avant de lancer un lot” contient vraisemblablement une faute : “grill” n’est pas correct en français ici. Remplace-le par le verbe ou l’expression voulue (par ex. une forme de “griller / mettre sur le grill” ou un autre verbe approprié).

Suggested change

	et ça change le modèle de coût (quota d'abonnement au lieu de facturation API). À grill avant de
	lancer un lot : faut-il un mode dual (API si dispo, sinon CLI), ou remplacer complètement ?
	et ça change le modèle de coût (quota d'abonnement au lieu de facturation API). À clarifier avant de
	lancer un lot : faut-il un mode dual (API si dispo, sinon CLI), ou remplacer complètement ?