REST API 的本地化 [英] Localization for REST APIs

问题描述

我开始此讨论是为了收集有关 API 本地化实践的更多信息.HTTP 似乎没有提供足够的指导，甚至实践状态也不够.

I am starting this discussion to gather more info on localization practices for APIs. It seems HTTP does NOT provide sufficient guidance and even the state of practice is not sufficient enough.

基本问题是 API 可能需要提供取决于用户文化、国家/地区、语言和时区的内容.例如，德国用户想要阅读带有欧洲公制日期、数字、单位、使用欧元货币和中欧时区的德语消息.

The basic problem is that APIs may need to provide content that is dependent on the user culture, country, language and timezone. For example a German user would like to read messages in German language, with European metric dates, numbers, units, using Euro currency and in Central European Timezone.

通读 RFC 7231 第 5.3.5 节接受语言 进一步深入到 RFC 4647，人们可能会认为 Accept-Language 已经足够复杂，应该这样做.但是有几个明显的缺点:

Reading through RFC 7231 Section 5.3.5 Accept-Language and further into RFC 4647 one may think Accept-Language is sophisticated enough and is what should be done. There are several notable shortcomings though:

1. 语言标签可能不够精确，例如用户只能请求没有国家/地区代码的语言，因此将歧义保留为:de, en;q=0.8"
2. 即使用户提供语言和国家偏好，也不清楚如何将消息区域设置和值格式区域设置的选择联系起来.例如，如果用户请求:hu_HU, en_US;q=0.9"而该应用程序缺少匈牙利语消息，并且是用 Java 编写的，它知道如何用匈牙利语格式化日期.那么应用程序应该使用带有匈牙利日期的英文消息还是提供带有美国日期的英文消息?实际情况可能更复杂.
3. 时区不存在于语言标签中.似乎没有 HTTP 标准标头.

我看到微软已经考虑过#2 在 ASP.Net 中引入了 Culture 和 UICulture 的概念，将消息语言的选择与格式分开.

I see Microsoft have thought about #2 in ASP.Net and introduce the notion of Culture and UICulture to separate selection of message language from formatting.

在 Java 世界中，Spring 引入了 TimeZoneAwareLocaleContext 解决 #3

In Java world Spring have introduced TimeZoneAwareLocaleContext to address #3

W3c 已发布指南以接受用于区域设置的语言.这或多或少说明 Accept-Language 是不够的

W3c have issued guideline to Accept-Language used for locale setting. This more or less says that Accept-Language is not enough

那你的想法是什么?

1. 您是否知道可以全面解决此问题的 API?指针?
2. API 是否应该接受多个值来选择消息语言、值格式区域设置和时区?
3. 是否应该使用Accept-Language?

推荐答案

好的，

这里总结了我如何回答我的问题.我希望这对未来的 API 创作者有所帮助.

here is a summary of how I answer my question. I hope this helps future API authors.

基于 API 之上的 UI 的基本要求(不包括货币表示)似乎是:

The fundamental requirements for an UI based on top of API excluding currency presentation seem to be:

1. 使用 RFC 4647 语言范围列表从可用产品翻译中选择最佳语言
2. 使用 RFC 4647 语言范围列表从可用的数据格式中选择最佳数据格式
3. 允许客户提供不同的翻译和格式偏好.在某些情况下，人们找不到最好的翻译，但更愿意看到符合他们文化的正确格式.
4. 允许客户端使用 IANA TZDB 标识符指定时区
5. 使用 Unicode CLDR 格式化数据元素 http://cldr.unicode.org/
6. 在本地化包中使用命名占位符，例如{驱动器} 已损坏"比{1}已损坏"更容易正确翻译

在 REST HTTP 标头上，我建议使用 3 个标头

On the REST HTTP headers I suggest use of 3 headers

1. accept-language - 用于选择翻译并遵循 RFC 7231 https://www.rfc-editor.org/rfc/rfc7231#section-5.3.5
2. format-locale - 用于选择与翻译语言首选项不同的数据格式样式.再次列出语言范围元素.如果省略，则默认为 accept-language.
3. timezone - 用于选择呈现日期和时间值的时区.这应该是来自 IANA TZDB 的有效时区 ID https://www.iana.org/time-zones

1. accept-language - used for selecting translation and following the guidelines of RFC 7231 https://www.rfc-editor.org/rfc/rfc7231#section-5.3.5
2. format-locale - used to select data formatting style if different from the translation language preferences. Again list of language range elements. Defaults to accept-language if omitted.
3. timezone - used to select timezone for rendering date and time values. This should be valid timezone ID from the IANA TZDB https://www.iana.org/time-zones

在实现方面，Java 8 及更高版本似乎具有实现全球化应用程序的全部能力.其他语言和较旧的 Java 版本似乎存在不同程度的问题.

Implementation wise it seems Java 8 and later have full capability to implement a globalized application. Other languages and older Java versions seem to have varying degrees of issues.

这篇关于REST API 的本地化的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！