如何结合HATEOAS实现REST API的多语言本地化？

背景与现有方案 #

客户端获取特定语言资源时，API可采用以下实现方式：

• Query Parameter（如?lang=de）
• Accept-Language Header
• URI路径段（如/classes/5/fr）
• Accept Header及多种表示类型
• Cookie
• 服务器存储的用户偏好

当前采用的语言优先级方案：

1. Query Parameter（优先支持员工编辑特定语言内容，同时适配HATEOAS链接）
2. Accept-Language Header
3. 服务器存储的用户偏好
4. 应用默认值

应用支持资源字段级多语言，例如课程标题仅存英文、描述有多语言版本，系统会返回各字段的最佳匹配结果，示例响应：

{
  "className": {
    "value": "Swing Dancing",
    "language": "en"
  },
  "description": {
    "value": "Lerne Lindy Hop für Anfänger.",
    "language": "de"
  }
}

现有HATEOAS链接示例（仅支持Query Parameter和URI路径段切换语言）：

{
  "className": "Swing Dancing",
  "description": "Learn to dance Lindy Hop for beginners.",
  "language": "en",
  "_links": {
    "lang-de": "/classes/5/?lang=de",
    "lang-fr": "/classes/5/fr"
  }
}

核心疑问 #

1. 若将翻译视为资源的表示形式，采用推荐的Accept-Language Header时，如何与HATEOAS配合？因无法将Header添加到URI，且HATEOAS要求客户端不应构造URI，是否存在理解误区？
2. 通过传入userId获取服务器存储的用户偏好，是否符合REST无状态的规范？

解答 #

关于Accept-Language与HATEOAS的配合 #

你对HATEOAS的理解存在误区：HATEOAS的核心是客户端通过响应提供的链接导航，而非硬编码URI，但完全允许客户端设置请求头（包括Accept-Language）来协商资源表示。

• 响应中的lang-de、lang-fr这类链接，是给客户端提供显式切换语言的快捷方式，对应Query Parameter或路径段的实现；
• 默认的语言协商逻辑依然可以基于Accept-Language Header：客户端首次请求资源时，携带Accept-Language头获取对应语言的表示，响应中可补充self链接（如/classes/5），客户端后续请求该链接时，继续携带Accept-Language头即可获取对应语言版本，完全符合HATEOAS要求。

服务器存储用户偏好的REST合规性 #

REST的无状态要求是服务器不保存客户端的会话状态，每个请求都包含足够的上下文信息。通过userId（通常通过请求头的身份凭证传递，而非直接作为参数）获取用户偏好，是符合无状态规范的：

• 用户标识是请求的一部分，服务器不需要记住客户端之前的交互；
• 服务器每次处理请求时，根据userId查询对应的偏好配置，这属于业务数据查询，而非会话状态存储。

对现有方案的优化建议 #

• 在_links中补充self链接，供客户端后续通过Accept-Language头请求默认协商的语言版本；
• 对于字段级多语言的返回格式，当前的结构（每个字段包含value和language）清晰展示了语言匹配结果，能提升客户端处理的透明度，建议保留。

内容的提问来源于stack exchange，提问作者M. Koch