在 VTEX IO 应用中用 messages…

当 VTEX IO 应用需要本地化 UI 文案（店面、Admin 或后端）时，用 messages builder 和翻译文件替代硬编码字符串。

适用场景

解决思路

1. 使用 `messages` builder 和翻译文件管理面向用户的文案，而不是在源码中硬编码标签、按钮文字或 UI 消息。
2. 保持翻译 key 稳定、明确、限定在应用域内，避免使用 `title`、`button` 这类通用 key；格式可灵活，但 key 必须具体、可描述、归属清晰。
3. 按 UI 界面或域为 message ID 加前缀，例如店面消息用 `store/...`，Admin 或 Site Editor 消息用 `admin/...`，避免跨上下文冲突。
4. 在 `/messages/context.json` 中定义 message key，让 VTEX IO 能发现并管理应用的翻译面；保持为 `messageId -> description` 的扁平映射，且只包含应用实际使用的 key。
5. 翻译消息内容保持精简且聚焦应用，不要把 messages 系统当作通用内容存储。
6. 在 React 或 Admin UI 中，优先使用 message ID 和本地化辅助函数，而不是在 JSX 中写死文案。
7. 在后端或 GraphQL 流程中，仅当应用边界确实需要本地化文本时才翻译；否则返回稳定的面向机器的数据，由调用方本地化展示。
8. 仅当应用确实需要自定义翻译行为或消息解析（超出普通应用本地消息文件）时，才使用应用级覆盖 `vtex.messages`。
9. 确保面向用户的字符串来自 messages 基础设施，而不是硬编码在组件、handler 或 resolver 中；例如使用 `<FormattedMessage id="admin/my-app.save" />` 而非 `<button>Save</button>`。
10. message key 必须应用级作用域并在应用消息配置中显式声明，不能临时在代码中发明；新增 message ID 时必须同步更新翻译文件和 `context.json`。
11. 翻译文件只能包含本地化文案，不得包含 API URL、凭证、业务规则或大型结构化内容；这些应放到应用设置、配置应用或专门的内容机制中。
12. 推荐文件布局：`messages/context.json`、`messages/en.json`、`messages/pt.json` 以及 `react/components/` 下的组件。
13. 保持完整的 `en.json` 作为默认回退，即使应用主要受众使用其他语言，以便消息系统有稳定的解析和自动翻译基础。
14. 后端或 GraphQL 翻译模式：定义 `scalar IOMessage`，在类型中使用 `IOMessage` 字段，并在 resolver 中返回包含 `content`（message ID）、`description` 和 `from` 的对象。
15. 在代码中使用翻译 ID，保持翻译文件显式，并将面向用户的文案集中到 messages 系统，而不是散落在应用各处的字面量。
16. 避免常见失败模式：在 JSX/resolver/handler 中硬编码、新增 ID 不更新 `context.json`、使用通用易冲突 key、在消息文件中存配置或非本地化业务数据、把 `vtex.messages` 覆盖当作默认路径。
17. 按审查清单自检：用户可见字符串是否来自 messages 基础设施、key 是否显式且应用级作用域、`context.json` 是否反映翻译面、消息文件是否仅限本地化文案、`vtex.messages` 自定义是否确有必要。

适用边界 · 注意事项

• 不适用于通用 UI 布局或组件组合。
• 不适用于授权、策略或认证令牌。
• 不适用于服务运行时规格，也不适用于在 HTTP、GraphQL 和事件驱动 API 之间做选择。