vtex-io-messages-and-i18n

消息与国际化

适用场景

当 VTEX IO 应用需要使用翻译文案，而不是硬编码字符串时，使用此技能。

• 为店面或 Admin 应用添加本地化 UI 文本
• 创建或更新 /messages/*.json 翻译文件
• 在 context.json 中定义消息键
• 检查当前硬编码了面向用户文案的 React、Admin 或后端代码
• 将应用专属翻译与 vtex.messages 集成

以下情况不使用此技能：

• 常规 UI 布局或组件组合
• 授权、策略或身份验证令牌
• 服务运行时容量配置
• 在 HTTP、GraphQL 和事件驱动 API 之间进行选择

决策规则

• 对面向用户的文案使用 messages 构建器和翻译文件，不要在源代码中硬编码标签、按钮文本或 UI 消息。
• 翻译键应保持稳定、明确，并限定在应用领域内；不要使用 title 或 button 这类通用键。具体格式可以不同，但键应具体、具有描述性，并明确归属于该应用。
• 根据 UI 界面或领域为消息 ID 添加前缀，例如，店面消息使用 store/...，Admin 或 Site Editor 消息使用 admin/...，以便整理键并避免不同上下文之间发生冲突。
• 在 /messages/context.json 中定义消息键，以便 VTEX IO 发现和管理应用的翻译范围。保持为 messageId -> description 格式的扁平映射，并包含应用实际使用的键。
• 翻译消息内容应简短且专注于应用。不要将消息系统用作通用内容存储。
• 在 React 或 Admin UI 中，优先使用消息 ID 和本地化辅助工具，而不是在 JSX 中直接填写文案。
• 在后端或 GraphQL 流程中，仅当应用边界确实需要本地化文本时才进行翻译；否则应返回稳定的机器可读数据，由调用方本地化其呈现内容。
• 仅当应用确实需要自定义翻译行为或消息解析，且常规的应用本地消息文件无法满足需求时，才覆盖应用级的 vtex.messages。

硬性约束

约束：面向用户的字符串必须来自消息基础设施

面向用户的字符串必须来自消息基础设施，不得硬编码在组件、处理程序或解析器中。

原因

硬编码文案会破坏本地化、增加消息审核难度，并导致店面、Admin 和后端流程的行为不一致。

检测

如果在本地化应用中，发现标签、按钮、标题、提醒或其他面向用户的文本直接写在 JSX 中，或嵌入后端响应格式化代码中，请立即停止，并将这些文案移至消息文件。

正确

<FormattedMessage id="admin/my-app.save" />

错误

<button>Save</button>

约束：必须明确声明和组织消息键

消息键必须限定在应用范围内，并在应用的消息配置中声明，不得在代码中临时创建。

原因

缺乏结构的键难以维护，容易在不同应用区域之间发生冲突，也会导致消息归属不明确。

检测

如果代码引入了新的消息 ID，却没有对应的翻译文件或 context.json 条目，请立即停止，并明确添加消息约定。

正确

{
  "admin/my-app.save": "Save"
}

错误

{
  "save": "Save"
}

约束：不得将消息系统用作通用内容或配置存储

翻译文件必须包含本地化文案，不得存放运行配置、机密信息或大量内容。

原因

消息基础设施专为翻译字符串设计。将其用于其他数据会造成维护混乱，并将本地化问题与配置或内容存储混在一起。

检测

如果消息文件中包含 API URL、凭据、业务规则或冗长的结构化内容，请立即停止，并将这些数据移至应用设置、配置应用或专用内容机制中。

正确

{
  "store/my-app.emptyState.title": "No records found"
}

错误

{
  "apiBaseUrl": "https://partner.example.com",
  "featureFlags": {
    "betaMode": true
  }
}

推荐模式

推荐的文件布局：

.
├── messages/
│   ├── context.json
│   ├── en.json
│   └── pt.json
└── react/
    └── components/
        └── SaveButton.tsx

最精简的消息设置：

// messages/context.json
{
  "admin/my-app.save": "Label for the save action in the admin settings page"
}

// messages/en.json
{
  "admin/my-app.save": "Save",
  "store/my-app.emptyState.title": "No records found"
}

// messages/pt.json
{
  "admin/my-app.save": "Salvar"
}

import { FormattedMessage } from 'react-intl'

export function SaveButton() {
  return <FormattedMessage id="admin/my-app.save" />
}

后端或 GraphQL 翻译模式：

scalar IOMessage

type ProductLabel {
  id: ID
  label: IOMessage
}

type Query {
  productLabel(id: ID!): ProductLabel
}

export const resolvers = {
  Query: {
    productLabel: async (_: unknown, { id }: { id: string }) => {
      return {
        id,
        label: {
          content: 'store/my-app.product-label',
          description: 'Label for product badge',
          from: 'en-US',
        },
      }
    },
  },
}

即使应用的主要受众使用其他区域设置，也要保留一份完整的 en.json 作为默认回退文件，让消息系统有稳定的解析基础，并支持自动翻译行为。

在代码中使用已翻译的 ID，明确维护翻译文件，并将面向用户的文案集中在消息系统中，而不是散落在应用各处。

常见故障模式

• 在 JSX、解析器或处理程序响应中硬编码面向用户的字符串。
• 在代码中添加新的消息 ID，却未更新 context.json 或消息文件。
• 使用 title、save 或 button 等通用或容易冲突的键。
• 在消息文件中存储配置值或未本地化的业务数据。
• 将 vtex.messages 覆盖当作默认路径，而不是使用应用本地的消息管理方式。

审查清单

• 面向用户的字符串是否来自消息基础设施，而非硬编码在代码中？
• 消息键是否明确、限定于应用范围，并保持一致的声明方式？
• context.json 是否反映应用所用的翻译范围？
• 消息文件是否仅包含本地化文案，而不含配置或操作数据？
• 此应用是否确实需要自定义 vtex.messages？

相关技能

• vtex-io-storefront-react - 当主要问题是店面组件结构和面向购物者的 UI 行为时使用
• vtex-io-admin-react - 当主要问题是 Admin UI 结构和操作交互模式时使用
• vtex-io-graphql-api - 当主要问题是 GraphQL 架构和解析器设计，而非翻译基础设施时使用

参考

• 消息 - VTEX 消息应用及其运行时翻译行为
• 覆盖 Messages 应用 - 应用专属的 vtex.messages 覆盖方式