feat(i18n): soft multi-locale catalogs + SL_LOCALE (C01 L16)

[KooshaPari]

Summary

• Soft Spanish catalog locales/es.json + SL_LOCALE / t_locale (C01 L16).
• Fluent/ICU remains a documented future hook.

Test plan

• pwsh ./scripts/i18n-check.ps1 -SelfCheck
• cargo test -p session-ledger --test i18n --lib i18n

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 88891a93-b91d-4094-9e2b-5a1df32c7f0a

📥 Commits

Reviewing files that changed from the base of the PR and between 7286ed9 and 48e14c1.

📒 Files selected for processing (6)

• CHANGELOG.md
• docs/ops/i18n.md
• locales/es.json
• scripts/i18n-check.ps1
• src/i18n.rs
• tests/i18n.rs

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (3)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Perform feature work in a git worktree under .claude/worktrees/, created from origin/main with a branch type of feat, fix, chore, ci, or docs; never work directly on main.
Do not directly commit to main; submit changes through a pull request.
Do not use git reset --hard, git stash, or git clean in worktrees.
Do not bypass hooks with --no-verify without operator approval.
Do not add AI attribution to commit or pull-request metadata.

Files:

• tests/i18n.rs
• CHANGELOG.md
• locales/es.json
• docs/ops/i18n.md
• scripts/i18n-check.ps1
• src/i18n.rs

**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

**/*.rs: Fix Clippy warnings instead of suppressing them with #[allow]; any necessary suppression must include a tracking-issue comment.
Use the Rust toolchain pinned in rust-toolchain.toml.

Files:

• tests/i18n.rs
• src/i18n.rs

**/*.{rs,toml}

📄 CodeRabbit inference engine (AGENTS.md)

Run locked Cargo builds and tests, including cargo build --all-targets --locked and cargo test --all-features --locked, and keep the workspace lint- and format-clean with Clippy and rustfmt.

Files:

• tests/i18n.rs
• src/i18n.rs

🔇 Additional comments (8)

docs/ops/i18n.md (2)

3-10: LGTM!

Also applies to: 19-23, 33-34, 51-61, 62-75

---

84-87: 📐 Maintainability & Code Quality | ⚡ Quick win

Doc's SelfCheck enumeration is missing two asserted anchors.

This text lists the helper exports -SelfCheck verifies as t / t_locale / try_catalog / SL_LOCALE / DEFAULT_LOCALE, but scripts/i18n-check.ps1 also asserts SOFT_LOCALE_ES and active_locale as helper anchors. Worth including them here so the doc's stated contract matches what the script actually checks.

📝 Proposed fix

 `-SelfCheck` asserts `locales/en.json` + `locales/es.json` share required keys,
-`src/i18n.rs` exposes `t` / `t_locale` / `try_catalog` / `SL_LOCALE` /
-`DEFAULT_LOCALE`, this doc keeps the Phase-0 decision and Fluent/ICU future
+`src/i18n.rs` exposes `t` / `t_locale` / `try_catalog` / `active_locale` /
+`SL_LOCALE` / `DEFAULT_LOCALE` / `SOFT_LOCALE_ES`, this doc keeps the Phase-0 decision and Fluent/ICU future
 hooks, and the Rust wrapper test is present.

CHANGELOG.md (1)

9-10: LGTM!

locales/es.json (1)

1-12: LGTM!

src/i18n.rs (2)

3-22: LGTM!

Also applies to: 78-78, 93-104, 132-162, 178-214

---

105-130: 🎯 Functional Correctness | ⚡ Quick win

normalize_locale doesn't trim before matching, so a padded SL_LOCALE/explicit tag silently falls back to English.

active_locale checks env_tag.trim().is_empty() (and similarly explicit.filter(|s| !s.trim().is_empty())) for emptiness, but then passes the untrimmed value into normalize_locale, which itself never trims before splitting/comparing. A value like " es" or "es " won't match SOFT_LOCALE_ES/DEFAULT_LOCALE and silently degrades to the English catalog via t_locale's fallback — no crash, but the intended locale selection quietly doesn't happen.

🛠️ Proposed fix

 pub fn normalize_locale(tag: &str) -> &str {
-    let primary = tag.split(['-', '_']).next().unwrap_or(tag);
+    let tag = tag.trim();
+    let primary = tag.split(['-', '_']).next().unwrap_or(tag);
     if primary.eq_ignore_ascii_case(SOFT_LOCALE_ES) {

scripts/i18n-check.ps1 (1)

6-9: LGTM!

Also applies to: 26-27, 66-75, 76-117, 119-140, 141-163

tests/i18n.rs (1)

1-7: 🎯 Functional Correctness

Doc-only change looks correct; confirm the locked cargo test run before merge.

Comment text accurately reflects the updated scope. However, the PR's test plan notes the Rust i18n test command remains unchecked — please confirm cargo test --all-features --locked (which exercises this i18n_scaffold_self_check_validates_anchors test and, transitively, the updated scripts/i18n-check.ps1) actually passes before merge.

As per path instructions, "Run locked Cargo builds and tests, including cargo build --all-targets --locked and cargo test --all-features --locked, and keep the workspace lint- and format-clean with Clippy and rustfmt."

Source: Path instructions

---

📝 Walkthrough

Summary

Adds soft Spanish locale support with embedded catalog loading, SL_LOCALE selection, locale normalization, translation fallback behavior, documentation, and self-check coverage.

Must Fix

• Run and confirm cargo fmt --check, cargo clippy --workspace -- -D warnings, and cargo test --workspace; the Rust i18n test remains unchecked in the stated test plan.

Should Fix

• Add executable tests for SL_LOCALE behavior, unknown-locale fallback, and missing-key fallback rather than relying primarily on source/documentation anchors.

Consider

• Fluent/ICU integration is appropriately documented as future work.

Approve / Request Changes

Request changes pending successful Rust formatting, clippy, and workspace test verification.

Walkthrough

The Phase-0 i18n scaffold now embeds English and Spanish catalogs, supports locale selection through explicit helpers or SL_LOCALE, applies English and key fallbacks, and validates catalog parity and related documentation anchors.

Changes

Soft multi-locale i18n

Layer / File(s)	Summary
Locale contract and Phase-0 documentation docs/ops/i18n.md, CHANGELOG.md	Documents English/Spanish catalog structure, locale selection precedence, fallback behavior, SelfCheck expectations, and deferred Fluent/ICU integration.
Spanish catalog and locale-aware lookup locales/es.json, src/i18n.rs	Adds Spanish messages and locale helpers for normalization, active-locale resolution, catalog lookup, translation, and English/key fallback; tests cover Spanish lookup and locale aliases.
Catalog parity and self-check validation scripts/i18n-check.ps1, tests/i18n.rs	Validates both catalogs, required keys, message-count parity, Rust helper anchors, and updated documentation anchors.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant t_locale
  participant active_locale
  participant Catalog
  Caller->>t_locale: request key with optional locale
  t_locale->>active_locale: resolve explicit locale or SL_LOCALE
  active_locale-->>t_locale: return normalized locale
  t_locale->>Catalog: look up localized message
  Catalog-->>t_locale: return Spanish or English fallback
  t_locale-->>Caller: return translated string

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding soft multi-locale catalogs with SL_LOCALE support.
Description check	✅ Passed	The description matches the change set and test plan, covering the Spanish catalog, locale selection, and future hook.
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.

✨ 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 feat/sl-w34-i18n

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/sl-w34-i18n

---

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.}