[ADP-771] OpenAPI: Language Code format

Overview

由於 OpenAPI 規範中未定義語言代碼的標準格式，我們制定了以 ISO-639-1 作為雙字母語言代碼及 BCP 47 作為擴展語言標籤的格式規範。

Guidance

• 必須(MUST) 使用 ISO 639-1 雙字母語言代碼作為基礎格式（例如："en", "zh", "ja"）
• 應該(SHOULD) 在需要表示更具體的語言變體時，使用 BCP 47 格式（例如："zh-CN", "en-US"）
• 必須(MUST) 將語言代碼定義為字串類型（string type）

Implementation

Schema Definition

components:
  schemas:
    LanguageCode:
      type: string
      format: iso-639-1
      description: Language code in ISO 639-1 or BCP 47 format
      example: "en"
    ExtendedLanguageCode:
      type: string
      format: bcp47-language-tag
      description: Extended language tag in BCP 47 format
      example: "zh-CN"

Reference

• ISO 639-1 Language Codes
• BCP 47 - Tags for Identifying Languages
• IETF Language Tags
• Zalando API Guidance
• OTTO 自訂格式

  INFO

  在 OTTO 的 API 設計指南中，他們使用單一 format 名稱 otto:language-code 來同時支援 ISO-639-1 和 BCP 47 格式。