国际化

VEF 内置了应用级 i18n 层，用于框架消息、验证输出和错误响应。

支持的语言

框架当前内置支持：

语言代码
`zh-CN`
`en`

默认应用语言：

配置项	值
默认语言	`zh-CN`

公共 API

公开 i18n API 故意保持得很小：

API	作用
`i18n.T(messageID, data...)`	翻译并在失败时自动回退
`i18n.Te(messageID, data...)`	翻译并显式返回错误
`i18n.SetLanguage(code)`	在运行时切换全局语言
`i18n.GetSupportedLanguages()`	列出支持的语言代码
`i18n.IsLanguageSupported(code)`	判断语言是否受支持
`i18n.New(config)`	创建独立 translator 实例

绝大多数应用代码只需要 i18n.T(...)。

Translator 模型

公共抽象是 i18n.Translator：

方法	作用
`T(messageID, data...)`	翻译并在失败时回退到 message ID
`Te(messageID, data...)`	翻译并返回显式错误

配置模型

构造器使用的配置类型是：

类型	作用
`i18n.Config`	通过 `Locales embed.FS` 提供嵌入式语言文件

语言选择

框架启动时按以下顺序决定语言：

优先级	来源
1	`VEF_I18N_LANGUAGE`
2	框架默认语言 `zh-CN`

之后也可以通过 i18n.SetLanguage(...) 切换当前进程级 translator，这在测试里尤其有用。

i18n 自动生效的地方

即使你从不手动调用 i18n，它也已经影响这些位置：

区域	效果
`result.Ok(...)` 和 `result.Err(...)`	成功/错误消息自动本地化
验证输出	字段标签和自定义规则消息自动翻译
内置资源错误	框架返回值自动本地化

所以在 VEF 里，i18n 不只是 UI 文本问题，它本身就是后端响应契约的一部分。

最小示例

package userinfo

import (
  "github.com/gofiber/fiber/v3"

  "github.com/coldsmirk/vef-framework-go/i18n"
  "github.com/coldsmirk/vef-framework-go/result"
)

func UserInfoNotImplemented(ctx fiber.Ctx) error {
  return result.ErrNotImplemented(
    i18n.T(result.ErrMessageUserInfoLoaderNotImplemented),
  )
}

与验证的集成

验证与 i18n 的集成主要体现在两点：

机制	效果
`label_i18n`	字段标签可翻译
自定义 validator 规则翻译	框架自定义规则会返回本地化消息

这也是为什么真实项目里的请求验证错误会比默认 validator 输出更可读。

实践建议

普通业务代码优先使用 i18n.T(...)
只有在你需要显式处理翻译失败时，才使用 i18n.Te(...)
i18n.SetLanguage(...) 更适合作为测试工具或受控运行时切换工具
要意识到 result 消息本身已经是本地化内容，因此后端响应天然属于 i18n 表面的一部分

下一步

继续阅读验证，看翻译后的字段标签和验证消息是如何出现在请求错误里的。

支持的语言​

公共 API​

Translator 模型​

配置模型​

语言选择​

i18n 自动生效的地方​

最小示例​

与验证的集成​

实践建议​

下一步​