docs: add i18n / error-localization conventions to CLAUDE.md

[an9xyz]

Part of #170 (backend i18n).

Summary

Docs-only. Captures the i18n / error-localization conventions in CLAUDE.md so future changes follow the playbook established by the migrated modules (#176/#188/#198/#203/#213/#214) and the recent OIDC (#223) and email (#224) work — instead of re-deriving it each time.

What's documented

• Two facades (pkg/httperr): ResponseErrorL (fixed-400 / D14) vs ResponseErrorLWithStatus (real status, new endpoints only), with a comparison table.
• Error codes (pkg/errcode/<module>.go): registration shape, the 5xx ⟺ Internal=true invariant, anti-enumeration (one generic code), and the Params/Details split.
• Per-module helpers (modules/<module>/api_i18n.go) and mustLookupSharedCode.
• The required gate: make i18n-extract / i18n-extract-check / i18n-lint, plus zh-CN translations in active.zh-CN.toml.
• Source guard: Test<Module>NoLegacyResponseError and the baseline.txt exemption for protocol endpoints.
• Emails: emailtmpl localized templates + i18n.OutboundLanguage(ctx).

Also adds pkg/httperr / pkg/i18n to the Key Packages table and an i18n line to Coding Conventions.

Test plan

• Docs-only; no code changes. Every command/path/API referenced exists in the tree (verified against feat(i18n): migrate OIDC bind flow to ResponseErrorL (Part of #170) #223/feat(i18n): externalize email templates + lang-aware send chain (#221) #224).

[Jerry-Xin]

✅ APPROVE

Comprehensive i18n / error-localization documentation for CLAUDE.md.

• ResponseErrorL vs ResponseErrorLWithStatus distinction (D14 compat vs real status) is clearly explained with the maintainer sign-off caveat
• Error code registration recipe is complete: ID naming, HTTPStatus, DefaultMessage, SafeDetailKeys, Internal flag
• 5xx ⟺ Internal=true invariant and anti-enumeration guidance are important security conventions, well documented
• Params vs Details (D15) distinction is precise
• CI enforcement chain (i18n-extract → i18n-extract-check → i18n-lint) gives clear action steps
• Guard test and baseline exemption pattern documented
• Email template localization section ties into the broader i18n story
• Architecture checklist updated with the i18n cross-reference

No issues found. Clean documentation.

[lml2468]

Summary

Docs-only: adds i18n / error-localization conventions to CLAUDE.md. Comprehensive, accurate, well-structured. No blocking issues.

Covers:

• Two-facade distinction (ResponseErrorL vs ResponseErrorLWithStatus) with correct usage guidance
• Error code registration pattern with all key fields (ID, HTTPStatus, DefaultMessage, SafeDetailKeys, Internal)
• 5xx ⟺ Internal=true invariant
• Anti-enumeration principle (single generic 401 for auth failures)
• Params vs Details (D15) distinction
• Per-module helper pattern (api_i18n.go)
• CI enforcement commands (i18n-extract, i18n-extract-check, i18n-lint)
• Guard test convention
• Email template localization
• Checklist addition reinforcing the rules

APPROVED.

[yujiawei]

Code Review — PR #231 (octo-server)

Scope: Documentation-only change to CLAUDE.md (+44/-4, single file) adding i18n / error-localization conventions. No production code is touched.

Verdict: APPROVED. I verified every concrete claim in the new documentation against the codebase at the PR head SHA. All structural claims (package paths, function signatures, struct fields, make targets, guard tests, email templates) are accurate. A few minor imprecisions are noted below as non-blocking nits.

What was verified ✅

• Package map — pkg/errcode/oidc.go, pkg/httperr/ (ResponseErrorL / ResponseErrorLWithStatus in respond.go:22,41), and pkg/i18n/ (codes registry, localizer, renderer, language negotiation, locales/) all exist as described.
• Two-facade semantics — ResponseErrorL pins the wire status to 400 with the real status in error.http_status (respond.go:60-69, tested in respond_test.go:15-56); ResponseErrorLWithStatus emits the code's real HTTPStatus (respond.go:61-62, tested respond_test.go:93-120). The "currently just modules/oidc bind" claim holds — grep confirms the only caller is modules/oidc/api_i18n.go:40 (respondBindError).
• Code registration shape — codes.Code has ID, HTTPStatus, DefaultMessage, SafeDetailKeys, Internal (registry.go:60-67); ID convention enforced by regex ^err\.(shared|server)\....$ (registry.go:43); err.shared.* codes (auth/rate/param/internal/not_found) exist in codes/shared.go.
• Invariants — 5xx ⟺ Internal=true is enforced by shared_test.go:59-75 and applied by the renderer (renderer.go:69-70,85-86 hide message + details). SafeDetailKeys whitelisting is implemented in details.go:21-44. Params-vs-details (D15) split is enforced via distinct types (params.go, details.go).
• Tooling — make i18n-extract / i18n-extract-check / i18n-lint targets exist in the Makefile and back the described behavior (pkg/i18n/cmd/octo-i18n-extract, tools/lint-direct-error-response, tools/lint-unregistered-code). Per-module api_i18n.go helpers + mustLookupSharedCode confirmed; Test<Module>NoLegacyResponseError guards and tools/lint-direct-error-response/baseline.txt exemptions confirmed.
• Emails — localized templates under modules/base/common/emailtmpl/templates/{en-US,zh-CN}/ with subject/html/text via go:embed; send functions take a lang arg resolved via i18n.OutboundLanguage(ctx) (service_email.go:28-30, used in modules/user/api_emaillogin.go).

Non-blocking nits (P2)

1. Code struct has an undocumented field. The actual struct (pkg/i18n/codes/registry.go:60-67) also has DefaultMessages map[string]string (extreme-fallback translations), not shown in the doc's example. It's optional and usually omitted, so the example is fine as-is — optionally add a one-line note that the field exists.
2. Anti-enumeration wording is slightly broad. The doc says auth/verify failures "map to ONE generic code (e.g. a single 401)". In practice codes/shared.go intentionally has several auth codes for different scenarios (auth.required, token_missing, token_invalid, token_expired, forbidden). The single-code rule correctly applies to credential-verification endpoints (e.g. ErrUserInvalidCredentials, ErrOIDCBindInvalidCredentials), where multiple failure reasons collapse to one code. Consider clarifying "for a single login/verify endpoint, never per-reason" to avoid a reader concluding only one auth code may exist globally.

Neither nit affects correctness, build, or security, and neither blocks merge. Good, accurate documentation that matches the implemented i18n system.