go-i18n: Instructions file for Claude Code

go-i18n

Go internationalization library with ICU MessageFormat support, deterministic fallback chains, and optional net/http locale detection. For user-facing installation and examples, see README.md. For internal contracts and design rules, start with SPECS/00-overview.md.

Commands

Use task targets first:

# Tests
task test
task test-verbose
task test-coverage
task bench

# Quality
task fmt
task vet
task lint

task vuln
task verify

Direct Go commands are fine for focused work:

go test -race -p 1 ./...
go test ./... -run TestName
go test -bench=. -benchmem ./...

Architecture

Key files and directories:

• i18n.go — bundle construction, locale matching, fallback state, MessageFormat compilation, introspection APIs
• localizer.go — locale-scoped lookup and formatting APIs
• loader.go — LoadMessages, LoadFiles, LoadGlob, LoadFS
• locale.go — Accept-Language matching via golang.org/x/text/language
• detector.go — request locale detection from query, cookie, header, and Accept-Language
• context.go — context helpers for *Localizer
• middleware/http.go — optional stdlib HTTP middleware
• result.go — TranslationResult and TranslationSource
• examples/ — runnable usage examples
• .references/ — pinned upstream implementations used as design evidence, not package contracts

Agent Operating Rules

• Read the relevant SPECS and adjacent tests before changing behavior.
• Reproduce bugs through the caller-visible path before editing implementation.
• Use one behavior-focused vertical slice at a time: RED, GREEN, then refactor.
• Prefer the standard library, current dependencies, and existing package helpers before adding code.
• Apply KISS, DRY, and YAGNI without weakening validation, errors, or tests.
• Keep edits scoped to the requested contract and preserve unrelated worktree changes.
• Resolve conflicting evidence explicitly; fail loudly when a required contract is unclear.
• Match verification to the changed behavior and run the repository gates before shipping.
• Do not add policy-only scripts that merely restate README, AGENTS, or SPECS prose.
• Do not add tests that mirror spec wording when behavior tests already prove the contract.