> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# チェックアウトの表示言語

> Waffo チェックアウトの言語を設定するフィールド、BCP 47 の正確な形式と検証エラー、チェックアウトが表示言語を選ぶ際の優先順位の全体、およびチェックアウトが描画できる言語の完全な一覧を説明します。

このページは、Waffo がホストするチェックアウトの**言語**のみを扱います。渡すフィールド、受け付ける値、そして何も渡さなかった場合にページがどの言語で描画するかを決める仕組みです。

どの決済手段がどの順番で表示されるかは別の判断です。[チェックアウトの決済手段表示ルール](/docs/ja/support/cashier-display-rules-faq)を参照してください。国の切り替え、リダイレクト URL、`orderAction.actionType` は[チェックアウトのリダイレクトとアクションタイプ](/docs/ja/support/cashier-redirect-and-action-type-faq)で扱っています。

## チェックアウトの表示言語を制御するフィールドはどれですか？

注文作成時に渡す `paymentInfo.cashierLanguage` です。

| | |
| - | - |
| フィールド | `paymentInfo.cashierLanguage` |
| 必須 | いいえ |
| 最大長 | 24 文字 |
| 形式 | IETF BCP 47 言語タグ |
| 検証 | 注文作成時 — 無効な値は作成呼び出しを失敗させます |
| 適用範囲 | その注文 1 件のみ。アカウントレベルの設定ではないため、注文ごとに渡します。 |

チェックアウトの言語を固定する Merchant Portal の設定はありません。言語を固定したい場合は、すべての注文で `cashierLanguage` を渡してください。

## `cashierLanguage` はどのような形式でなければなりませんか？

`language[-script][-region]` のみで、それ以外は受け付けません。

| サブタグ | 標準 | ルール |
| - | - | - |
| language | ISO 639-1、2 文字 | 必須。チェックアウトがサポートする言語でなければなりません。集合は閉じています。 |
| script | ISO 15924、4 文字 | 任意。指定する場合は `Hant` または `Hans` でなければなりません。集合は閉じています。 |
| region | ISO 3166-1 alpha-2、2 文字 | 任意。有効な国/地域コードでなければなりません。チェックアウトにその地域固有の文言があるかどうかに関わらず、有効なコードはすべて受け付けます。 |

通る例：

| 値 | 意味 |
| - | - |
| `en` | 英語 |
| `en-HK` | 英語、香港 |
| `zh-Hant-HK` | 繁体字中国語、香港 |
| `zh-Hans-HK` | 簡体字中国語、香港 |
| `ja-JP` | 日本語、日本 |

拒否される値：

* アンダースコア区切り — `en_US` は BCP 47 タグではありません。
* バリアントサブタグ — `de-DE-1996`。
* 拡張サブタグ — `en-US-x-foo`。
* 24 文字を超えるもの。

大文字・小文字は正規化されるため、`en-us` は受け付けられ、`en-US` として保存されます。

## 値が間違っている場合、どのエラーが返りますか？

2 つの異なる結果があり、それぞれ意味が異なります。

| 状況 | エラー | メッセージ |
| - | - | - |
| タグが構造的に無効、バリアント/拡張サブタグを含む、または地域が実在する ISO 3166-1 alpha-2 コードではない | `A0047` | `The cashier language format is invalid, it must follow IETF BCP 47: a two-letter ISO 639-1 language, an optional four-letter ISO 15924 script, and an optional two-letter ISO 3166-1 alpha-2 region` |
| タグの形式は正しいが、言語またはスクリプトがサポート対象外 | `A0026` | `The cashier language specified by merchant currently is not supported` |

どちらも注文作成時に HTTP 400 として返されるため、不正な値がチェックアウトページに届くことはありません。`A0047` が返った場合は文字列の形を修正してください。`A0026` が返った場合は形は正しいものの、その言語が Waffo の描画対象ではないということです。下の一覧を確認してください。

## 同じフィールドはサブスクリプションでも使えますか？

はい。`paymentInfo.cashierLanguage` はサブスクリプション作成時にも同じ名前で存在し、同じ 24 文字制限、同じ BCP 47 ルール、同じ 2 つのエラーが適用されます。サブスクリプション作成フローの同じ場所で検証されます。

## `cashierLanguage` はチェックアウトページ以外にも影響しますか？

サブスクリプションでは、はい。**エンドユーザー向けのサブスクリプション通知は同じ判断を再利用します**。Waffo が貴社の顧客にサブスクリプション通知を送る際、言語は `cashierLanguage` を指定していればその値、指定していなければ顧客の支払通貨から推定されます。

チェックアウトページとの違いに注意してください。通知はブラウザセッションではないため、読み取れる `Accept-Language` ヘッダーも国タブもありません。通知のフォールバックは**通貨ベース**、チェックアウトページのフォールバックは**国ベース**です（次の質問を参照）。

## チェックアウトは表示言語をどのように決めますか？優先順位はありますか？

はい。5 つの層があり、上から順に評価されます。最初に値を返した層が採用されます。

| 層 | ソース | 備考 |
| - | - | - |
| 0 | **固定された表示言語** | 顧客が決済手段選択ページで送信した時点で実際に見ていた言語のスナップショット。その送信後にのみ存在します。 |
| 1 | **`paymentInfo.cashierLanguage`** | 貴社の値をそのまま使用（注文作成時にすでに検証・正規化済み）。 |
| 2 | **ブラウザの `Accept-Language`** | ヘッダーの最優先エントリのみ。何が読み取られるかは下記を参照。 |
| 3 | **国からの推定** | 送信前は顧客の*実際の*所在地。送信後はチェックアウトの表示国。下記を参照。 |
| 4 | **`en`** | 層 3 が使用可能な値を返さない場合の最終フォールバック。 |

設計上考慮すべき 2 つの帰結：

* **層 0、1、2 は言語を固定します。** いずれかがヒットすると、言語はもう国に追従しません。顧客が国タブを切り替えても文言はそのままです。
* **層 3 だけが国タブに追従します。** つまり、`cashierLanguage` がなく、使用可能な `Accept-Language` もない顧客は国を切り替えると文言が変わり、どちらかがある顧客は変わりません。

言語の解決は表示のみに関わります。何らかの理由で失敗しても、決済自体には影響しません。

## 層 3 は実際にどの国を使いますか？

注文がライフサイクルのどこにあるかによります。「表示国」と「顧客の国」は同じものではないため、この区別は重要です。

| 注文の状態 | 層 3 で使用される国 |
| - | - |
| まだ決済手段選択ページにいる | 顧客の**実際の**所在地：実在する国に切り替えた場合はその国タブ、そうでなければ IP から推定された国。 |
| 送信後 | チェックアウトの**表示国**（`countryCode`）。 |

選択ページでは、顧客自身の国が注文の候補一覧に含まれていない場合、表示国は候補一覧のいずれかの国で埋め戻されることがあります。この埋め戻された値は顧客の所在地を表さないため、言語の判断では意図的に使用しません。

**Global** タブの選択は所在地ではないため、所在地としては扱われません。IP から推定された国にフォールスルーします。

## 固定された表示言語とは何ですか？層 0 が存在する理由は？

顧客が決済手段選択ページで選択を送信すると、チェックアウトはその時点で見ていた言語を注文に保存します。それ以降、この値が他のすべてに優先します。

これは決済の途中で言語がぶれるのを防ぐために存在します。グローバルに利用可能な決済手段は、注文の表示国を**Global**に移動させます。これは実在する国ではなくセンチネル値です。スナップショットがなければ、現地語で表示されていた注文は、顧客がグローバルな決済手段を選んだ瞬間に英語のフォールバックへ切り替わり、顧客は選択から支払いの間にページの言語が変わるのを目にすることになります。スナップショットはすでに見ていた言語を固定します。

この値は設定も読み取りもできません。送信時にチェックアウトが書き込みます。貴社の連携への実務上の影響はこれだけです：**顧客が選択ページで送信した後は、何をしても言語は変わりません。**

## チェックアウトは `Accept-Language` から正確には何を読み取りますか？

層 2 は多くの人が想像するより狭いものです。

* ヘッダーの**最も重みの高い**エントリのみが考慮されます。それがサポート対象の言語にマッピングされない場合、チェックアウトは次のエントリを**試しません**。層 3 へ降ります。
* **主要言語サブタグ**のみが使用されます。ヘッダーの `zh-Hant-TW` は `zh` に畳み込まれ、ヘッダー内のスクリプトと地域は破棄されます。
* 受け付ける主要サブタグは `en`、`es`、`id`、`ja`、`ko`、`ms`、`pl`、`pt`、`th`、`tr`、`vi`、`zh` です。それ以外（`fr`、`ru` など）は何も返さず、層 3 へフォールスルーします。
* 不正な形式のヘッダー（一部の古いアプリ内ブラウザは品質値を重複して出力します）は、生の文字列内の最初の言語タグを読み取る動作に退化し、同じマッピングが適用されます。

層 2 は主要サブタグのレベルで解決されるため、ブラウザからの `zh` は**繁体字**中国語で描画されます。下記のスクリプトのフォールバックを参照してください。

## チェックアウトはどの言語をサポートしていますか？

`cashierLanguage` が完全なタグとして受け付ける値は次のとおりです。

| タグ | 言語 |
| - | - |
| `en` | 英語 |
| `pt-BR` | ポルトガル語（ブラジル） |
| `es-MX` | スペイン語（メキシコ） |
| `es-PE` | スペイン語（ペルー） |
| `es-CO` | スペイン語（コロンビア） |
| `es-CL` | スペイン語（チリ） |
| `id-ID` | インドネシア語 |
| `vi-VN` | ベトナム語 |
| `ru-RU` | ロシア語 |
| `th-TH` | タイ語 |
| `ja-JP` | 日本語 |
| `ko-KR` | 韓国語 |
| `ms-MY` | マレー語 |
| `pl-PL` | ポーランド語 |
| `tr-TR` | トルコ語 |
| `en-KE` | 英語（ケニア） |
| `en-NG` | 英語（ナイジェリア） |
| `en-HK` | 英語（香港） |
| `zh-Hant-TW` | 繁体字中国語（台湾） |
| `zh-Hant-HK` | 繁体字中国語（香港） |
| `zh-Hans-HK` | 簡体字中国語（香港） |
| `zh-Hans` | 簡体字中国語 |

これらの文字列そのものに限定されるわけではありません。検証はサブタグ単位で行われるため、サポート対象の言語、任意のサポート対象スクリプト、有効な ISO 地域の任意の組み合わせが受け付けられます。たとえば `en-SG` などです。*地域*が何を変えるかは次で説明します。

## `en-HK` を渡しましたが、ページは `en` と同じに見えます。地域サブタグは無視されるのですか？

ページの文言については、実質的にそのとおりです。チェックアウトの文言は **13 の言語バケット**で管理されており、タグは言語とスクリプトのみでバケットに対応付けられます。地域サブタグが別の文言セットを選ぶことはありません。

| バケット | そのバケットに入るタグ |
| - | - |
| `en` | `en`、`en-HK`、`en-KE`、`en-NG`、任意の `en-*` |
| `pt` | `pt-BR`、任意の `pt-*` |
| `es` | `es-MX`、`es-PE`、`es-CO`、`es-CL`、任意の `es-*` |
| `zh-Hant` | `zh-Hant-TW`、`zh-Hant-HK`、および素の `zh` |
| `zh-Hans` | `zh-Hans`、`zh-Hans-HK` |
| `vi` | `vi-VN` |
| `th` | `th-TH` |
| `id` | `id-ID` |
| `ja` | `ja-JP` |
| `ko` | `ko-KR` |
| `ms` | `ms-MY` |
| `pl` | `pl-PL` |
| `tr` | `tr-TR` |

したがって `es-PE` と `es-CL` は同じスペイン語の文言を描画し、`en-KE` と `en-NG` は同じ英語の文言を描画します。地域サブタグは引き続き注文に保持され、ロケールに応じた書式設定には使用されますが、文言を分岐させることはありません。

人を驚かせる 2 つの具体的なルール：

* **素の `zh` は繁体字中国語で描画されます。** スクリプトサブタグがないと両者を区別するものがないため、チェックアウトは `zh` を `zh-Hant` に解決します。簡体字にしたい場合は、`zh-Hans` または `zh-Hans-HK` のように `Hans` スクリプトを明示的に渡してください。
* **バケットのない言語は英語で描画されます。** `ru-RU` は検証を通りますが、ロシア語は 13 の文言バケットに含まれないため、ページは英語で描画されます。

## 何も渡しませんでした。顧客にはどの言語が表示されますか？

層 2 から 4 が、この順序で決定します。

1. 顧客のブラウザが送るヘッダーの最上位エントリが、受け付ける 12 の主要サブタグのいずれかであれば、その言語が使用され、国タブを切り替えても変わりません。
2. そうでなければ言語は国から推定され（送信前は実際の所在地、送信後は表示国）、タブを切り替えると**変わります**。
3. どちらからも得られない場合、ページは英語になります。

決定的な言語が重要な場合（ローカライズされたブランド体験、規制のある市場、スクリーンショットに基づくサポートフローなど）は、この連鎖に頼るのではなく `cashierLanguage` を渡してください。

## 領収書をダウンロードする際、顧客はどの言語を選べますか？

同じ 13 のバケットが、それぞれの言語名で提示されます：English、Português、Español、繁體中文、简体中文、Tiếng Việt、ไทย、Bahasa Indonesia、日本語、한국어、Bahasa Melayu、Polski、Türkçe。

領収書の言語はダウンロード時に顧客自身が選択します。`cashierLanguage` によって決まるものではなく、選択してもチェックアウトページの言語は変わりません。

## 顧客自身にチェックアウトの言語を選ばせることはできますか？

チェックアウトページに言語セレクターはありません。言語は 5 層の連鎖が解決した結果になります。

顧客が*変更できる*のは、決済手段選択ページ上の国です。それが言語を変えるのは、連鎖が層 3 に到達した場合のみ、つまり貴社が `cashierLanguage` を渡さず、かつブラウザのヘッダーが一致しなかった場合のみです。国セレクターがそもそも表示される条件については、[チェックアウトのリダイレクトとアクションタイプ](/docs/ja/support/cashier-redirect-and-action-type-faq)を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.