AIP-143 标准代号

编号	143
原文链接	AIP-143: Standardized codes
状态	批准
创建日期	2019-07-24
更新日期	2019-07-24

许多常见的概念，如语言、国家、货币等，都有用于数据通信和处理的通用代号（通常由国际标准化组织正式定义）。这些代号解决了在书面语言中，同一概念往往存在多种表达方式的问题（如“United States”和“USA”、“Español”和“Spanish”）。

指南

对于存在标准代号且广泛使用的概念，表示这些概念的域 应当 使用标准代号进行输入和输出。

// A message representing a book.
message Book {// Other fields...// The IETF BCP-47 language code representing the language in which// the book was originally written.// https://en.wikipedia.org/wiki/IETF_language_tagstring language_code = 99;
}

• 表示标准概念的域 必须 为标准代号选择合适的数据类型（通常是 string ）。
  • 表示标准概念的域 不应 使用枚举，即使只允许一个很小的取值集合。在这种情况下使用枚举，往往导致在使用多个API时出现令人沮丧的查找表。
  • 表示标准概念的域 必须 表明所遵守的标准，最好带上链接（指向标准本身、维基百科描述或类似内容）。
• 域名字 应当 以 _code 或 _type 结尾，概念拥有更明确后缀的除外。
• 在处理用户输入值时，验证过程 应当 是大小写不敏感的，除非可能引发歧义（如 en-gb 和 en-GB ）。当向用户返回值时，API 应当 使用规范大小写（上例中的 en-GB ）。

内容类型

表示内容或媒体类型的域 必须 使用IANA媒体类型。由于历史原因，域 应当 称为 mime_type 。

国家和地区

表示单个国家或地区的域 必须 使用Unicode CLDR地区代号（列表），例如 US 或 CH ，域 必须 称为 region_code 。

重要提示 请阅读此要求的理由。

货币

表示货币的域 必须 使用ISO-4217货币代号，例如 USD 或 CHF ，域 必须 称为 currency_code 。

注意 要表示以特定货币计价的金额，而非货币代号本身，请使用google.type.Money。

语言

表示语言的域 必须 使用IETF BCP-47语言代号（列表），例如 en-US 或 de-CH ，域 必须 称为 language_code 。

时区

表示时区的域 应当 使用IANA TZ代号，域 必须 称为 time_zone 。

域也 可以 表示UTC偏移量而非时区（注意两者存在细微差别）。此时，域 必须 使用ISO-8601格式， 必须 命名为 utc_offset 。

理由

国家地区域名字

使用 region_code 而非 country_code 非常重要，可以表达与国家不同的地区，避免与地区主权或归属有关的政治争端。许多公司是Unicode CLDR的支持者，按照Unicode CLDR标准进行产品国际化工作，API也不例外。此外，Unicode CLDR支持的许多值本身并不是国家，因此使用更通用的名字实际上更符合规范。此外，Unicode CLDR支持的值很多本身并非独立国家，使用更通用的名字实际上与规范更兼容。

修订记录

• 2024-12-03 补充国家地区域名字理由。
• 2024-11-12 将国家地区代号列表从IANA列表改为CLDR列表。
• 2020-05-12 将 country_code 指南替换为 region_code ，修正之前的错误。