Go 错误应避免硬编码字符串，须用自定义 LocalizableError 接口延迟翻译，MessageID 作纯标识符，i18n 资源按 JSON 结构支持占位符，响应体需同时返回 code、error_id 和 localized message。
错误信息不能硬编码字符串
Go 的 error 类型本质是接口，一旦用 errors.New("用户不存在") 或 fmt.Errorf("数据库连接失败: %w", err) 直接写死中文，后续国际化就只能靠反射或字符串替换——这两种方式在生产环境都不可靠，且破坏错误链和类型判断逻辑。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有业务错误统一通过自定义 error 类型构造，例如
type AppError struct { Code string; MessageID string; Args []interface{} } -
MessageID是纯标识符（如"user_not_found"），不带语言、不带格式，只用于查表 - 避免在 error 实现中直接调用 i18n 翻译函数，否则会把语言上下文（
locale）耦合进错误创建过程，导致同一错误在不同请求中翻译不一致
翻译时机必须延迟到 error 处理时
错误的生成和展示通常跨多个调用层级，比如 HTTP handler → service → repo。只有在最终响应前（如 middleware 或 handler 末尾）才明确知道当前请求的 Accept-Language 和用户偏好，这时才应做翻译。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 定义可翻译的 error 接口：
type LocalizableError interface { error; Localize(*i18n.Bundle) string } - HTTP 中间件中注入
*i18n.Bundle（来自go-i18n/i18n或类似库），并调用err.(LocalizableError).Localize(bundle) - 对非本地化 error（如标准库
os.PathError），保持原样透传，不强行翻译；可加前缀标注来源，例如"system_error: permission denied"
i18n 资源文件结构要支持嵌套与复用
错误消息常需动态参数（如用户名、资源 ID），且不同语言的语序差异大（如中文“用户 {name} 未找到”，日语可能是“{name} というユーザーは見つかりません”）。硬编码模板字符串会很快失控。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 使用
go-i18n的 JSON 格式，每个MessageID对应一个对象，支持description和带占位符的translation：
{
"user_not_found": {
"description": "User with given name does not exist",
"translation": "用户 {{.Name}} 不存在"
}
}
- 调用时传入 map：
bundle.Localize(&i18n.LocalizeConfig{MessageID: "user_not_found", TemplateData: map[string]interface{}{"Name": "alice"}}) - 避免在资源文件里写逻辑（如条件分支），复杂文案拆成多个独立
MessageID，由 Go 代码控制分支
HTTP 错误响应体需同时携带 code、id、localized message
前端不仅需要显示文案，还依赖 code 做逻辑判断（如跳转登录页），MessageID 用于埋点或 fallback，而 message 仅用于展示。三者缺一不可。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 定义统一错误响应结构，例如：
type ErrorResponse struct {
Code int `json:"code"` // HTTP status or business code
ErrorID string `json:"error_id"` // e.g. "user_not_found"
Message string `json:"message"` // localized, ready-to-show
RequestID string `json:"request_id,omitempty"`
}
- 不要把
Args原样塞进响应体——存在敏感信息泄露风险（如密码、token）；只传脱敏后的键名（如"user_id"），不传值 - 测试时用
bundle.MustGetMessage替代bundle.Localize，让缺失翻译直接 panic，避免上线后静默回退到英文
最容易被忽略的是错误链中底层 error 的 MessageID 可能被上层覆盖或丢失。如果 service 层 wrap 了 repo 层的 AppError，必须显式保留原始 MessageID 字段，而不是只保留 Error() 字符串。
