國際化 · HTTP 接口設計指北

## 國際化 ### [](https://github.com/bolasblack/http-api-guide#語言標簽)語言標簽 [RFC 5646](http://tools.ietf.org/html/rfc5646)?([BCP 47](http://tools.ietf.org/html/bcp47)) 規定的語言標簽的格式如下： ~~~ language-script-region-variant-extension-privateuse ~~~ 1. `language`：這部分使用的是 ISO 639-1, ISO 639-2, ISO 639-3, ISO 639-5 中定義的語言代碼，必填 * 這個部分由?`primary-extlang`?兩個部分構成 * `primary`?部分使用 ISO 639-1, ISO 639-2, ISO 639-3, ISO 639-5 中定義的語言代碼，優先使用 ISO 639-1 中定義的條目，比如漢語?`zh` * `extlang`?部分是在某些歷史性的兼容性的原因，在需要非常細致地區別?`primary`?語言的時候使用，使用 ISO 639-3 中定義的三個字母的代碼，比如普通話?`cmn` * 雖然?`language`?可以只寫?`extlang`?省略?`primary`?部分，但出于兼容性的考慮，還是**建議**加上?`primary`?部分 2. `script`: 這部分使用的是?[ISO 15924](http://www.unicode.org/iso15924/codelists.html)?([Wikipedia](http://zh.wikipedia.org/wiki/ISO_15924)) 中定義的語言代碼，比如簡體漢字是?`zh-Hans`?，繁體漢字是?`zh-Hant`?。 3. `region`: 這部分使用的是 ISO 3166-1 ([Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) 中定義的地理區域代碼，比如?`zh-Hans-CN`?就是中國大陸使用的簡體中文。 4. `variant`: 用來表示?`extlang`?的定義里沒有包含的方言，具體的使用方法可以參考?[RFC 5646](http://tools.ietf.org/html/rfc5646#section-2.2.5)?。 5. `extension`: 用來為自己的應用做一些語言上的額外的擴展，具體的使用方法可以參考?[RFC 5646](http://tools.ietf.org/html/rfc5646#section-2.2.6)。 6. `privateuse`: 用來表示私有協議中約定的一些語言上的區別，具體的使用方法可以參考?[RFC 5646](http://tools.ietf.org/html/rfc5646#section-2.2.7)。其中只有?`language`?部分是必須的，其他部分都是可選的；不過為了便于編寫程序，建議設計接口時約定語言標簽的結構，比如統一使用?`language-script-region`?的形式（?`zh-Hans-CN`,?`zh-Hant-HK`?等等）。語言標簽是大小寫不敏感的，但按照慣例，建議?`script`?部分首字母大寫，?`region`?部分全部大寫，其余部分全部小寫。 **有一點需要注意，任何合法的標簽都必須經過 IANA 的認證，已通過認證的標簽可以在[這個網頁](http://www.iana.org/assignments/language-subtag-registry)查到。此外，網上還有一個非官方的[標簽搜索引擎](http://people.w3.org/rishida/utils/subtags/)。** 相關資料： * ISO 639-1 Code List ([Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)) * [ISO 639-2 Code List](http://www.loc.gov/standards/iso639-2/php/code_list.php)?([Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes)) * [ISO 639-3 Code List](http://www-01.sil.org/iso639-3/codes.asp?order=639_3&letter=%25) * [ISO 639-5 Code List](http://www.loc.gov/standards/iso639-5/id.php)?([Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-5_codes)) * [ISO 639-3 Macrolanguage Mappings](http://www-01.sil.org/iso639-3/macrolanguages.asp)?([Wikipedia](https://en.wikipedia.org/wiki/ISO_639_macrolanguage)) * [Relationship between ISO 639-3 and the other parts of ISO 639](http://www-01.sil.org/iso639-3/relationship.asp) * [網頁頭部的聲明應該是用 lang="zh" 還是 lang="zh-cn"？ - 知乎](http://www.zhihu.com/question/20797118) * [IETF language tag - Wikipedia](https://en.wikipedia.org/wiki/IETF_language_tag) * [語種名稱代碼](http://www.ruanyifeng.com/blog/2008/02/codes_for_language_names.html)?：文中對帶有方言（?`extlang`?）部分的標簽介紹有誤 * [Language tags in HTML and XML](http://www.w3.org/International/articles/language-tags/) * [Choosing a Language Tag](http://www.w3.org/International/questions/qa-choosing-language-tags) ### [](https://github.com/bolasblack/http-api-guide#時區)時區客戶端請求服務器時，如果對時間有特殊要求（如某段時間每天的統計信息），則可以參考?[IETF 相關草案](http://tools.ietf.org/html/draft-sharhalakis-httptz-05)?增加請求頭?`Timezone`?。 ~~~ Timezone: 2007-06-12T23:48:22+0800 // OR Timezone: 1977-07-30T12:00:11+0200;;Europe/Athens ~~~ 時區的名稱可以參考?[tz datebase](http://www.iana.org/time-zones)([Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) 。如果客戶端請求時沒有指定相應的時區，則服務端默認使用?[UTC](http://zh.wikipedia.org/wiki/%E5%8D%8F%E8%B0%83%E4%B8%96%E7%95%8C%E6%97%B6)?時間返回相應數據。 PS 考慮到存在[夏時制](https://en.wikipedia.org/wiki/Daylight_saving_time)這種東西，所以不推薦客戶端在請求時使用 Offset 。 ### [](https://github.com/bolasblack/http-api-guide#時間格式)時間格式時間格式遵循?[ISO 8601](https://www.iso.org/obp/ui/#iso:std:iso:8601:ed-3:v1:en)([Wikipedia](https://en.wikipedia.org/wiki/ISO_8601)) 建議的格式： * 日期?`2014-07-09` * 時間?`14:31:22+0800` * 具體時間?`2007-11-06T16:34:41Z` * 持續時間?`P1Y3M5DT6H7M30S`?（表示在一年三個月五天六小時七分三十秒內） * 時間區間?`2007-03-01T13:00:00Z/2008-05-11T15:30:00Z`?、?`2007-03-01T13:00:00Z/P1Y2M10DT2H30M`?、?`P1Y2M10DT2H30M/2008-05-11T15:30:00Z` * 重復時間?`R3/2004-05-06T13:00:00+08/P0Y6M5DT3H0M0S`?（表示從2004年5月6日北京時間下午1點起，在半年零5天3小時內，重復3次）相關資料： * [What's the difference between ISO 8601 and RFC 3339 Date Formats?](http://stackoverflow.com/questions/522251/whats-the-difference-between-iso-8601-and-rfc-3339-date-formats) * [JSON風格指南 - Google 風格指南（中文版）](https://github.com/darcyliu/google-styleguide/blob/master/JSONStyleGuide.md#%E5%B1%9E%E6%80%A7%E5%80%BC%E6%95%B0%E6%8D%AE%E7%B1%BB%E5%9E%8B) ### [](https://github.com/bolasblack/http-api-guide#貨幣名稱)貨幣名稱貨幣名稱可以參考 ISO 4217([Wikipedia](http://en.wikipedia.org/wiki/ISO_4217)) 中的約定，標準為貨幣名稱規定了三個字母的貨幣代碼，其中的前兩個字母是 ISO 3166-1([Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) 中定義的雙字母國家代碼，第三個字母通常是貨幣的首字母。在貨幣上使用這些代碼消除了貨幣名稱（比如 dollar ）或符號（比如 $ ）的歧義。相關資料： * 《RESTful Web Services Cookbook 中文版》 3.9 節《如何在表述中使用可移植的數據格式》