国際化(i18n)
Apothem ドキュメントサイトが、ロケールコホートをどのように宣言し、hreflang の代替言語リンクをどのように出力し、右書きレンダリングをどのように扱い、翻訳のギャップをどのように正直に提示するか。
このページでは、Apothem ドキュメントサイトが複数の言語をどのように扱うかを
文書化します。すなわち、宣言するロケールコホート、出力する hreflang の
仕組み、右書きへの対応状況、そしてロケールごとの翻訳の正直な状態です。
決定の要約
- プラットフォーム: Next.js App Router + Fumadocs。 サイトは
site/から ビルドされます。ロケールコホートはsite/lib/i18n.tsで宣言され、 代替言語リンクの仕組みはsite/lib/hreflang.tsにあります。 - ロケールコホート: 宣言済み。 12 ロケールからなる Modern Dev Cohort が 正規の信頼できる情報源として宣言されており、英語がソースロケールです。
- ロケールごとのルーティング: 未有効化。 英語コンテンツしか存在しない 状態でコホート全体にロケール接頭辞付きのルートを有効化すると、英語ソースへ 暗黙的にフォールバックする 11 個のコンテンツなしルートが生まれます。それは i18n の規律が禁じる「暗黙の英語のみへのずれ」にあたるため、レビュー済みの 翻訳コンテンツが入るまでルーティングは単一ロケールのままにします。
hreflangの仕組み: 有効。 すべてのページは、作成済みコンテンツを 持つ各ロケールを対象とする<link rel="alternate">の集合と、x-defaultフォールバックを出力します。まだ翻訳を待っているロケールは省略され —— 決して英語フォールバックへ向けられることはなく —— その結果、検索エンジンには 翻訳が存在しないことが正確に伝えられます。- 右書きへの対応: 整備済み。 共有スタイルシートは全体を通じて論理 CSS
プロパティを使用しているため、アラビア語コンテンツが入った時点で
アラビア語ページは
dir="rtl"下で正しくレンダリングされます。 - 機械翻訳ポリシー: 未レビューのものは出荷しない。 機械翻訳された ページ本文は一切公開されません。翻訳は機械によって種付けされ、いずれの ロケールも翻訳済みとマークされる前に人間のレビューによってゲートされます。
ロケールコホート
Modern Dev Cohort は 12 のロケールを宣言します。英語はサイトのルートで 配信されます。残る 11 のターゲットは、スタックが国際化に対応しており、 翻訳のギャップが暗黙ではなく明示的であるよう宣言されています。
| コード | パス | 言語 | 書字方向 | コンテンツ |
|---|---|---|---|---|
en | / | 英語 | LTR | 翻訳済み(ソース) |
zh-CN | /zh-cn/ | 簡体字中国語 | LTR | 保留中 |
es | /es/ | スペイン語 | LTR | 保留中 |
pt-BR | /pt-br/ | ブラジルポルトガル語 | LTR | 保留中 |
fr | /fr/ | フランス語 | LTR | 保留中 |
de | /de/ | ドイツ語 | LTR | 保留中 |
ja | /ja/ | 日本語 | LTR | 保留中 |
ko | /ko/ | 韓国語 | LTR | 保留中 |
ru | /ru/ | ロシア語 | LTR | 保留中 |
id | /id/ | インドネシア語 | LTR | 保留中 |
ar | /ar/ | アラビア語 | RTL | 保留中 |
hi | /hi/ | ヒンディー語 | LTR | 保留中 |
コホートは唯一の信頼できる情報源です。それへの修正は、暗黙の編集ではなく、 慎重な決定を経て行われます。
hreflang の仕組み
site/lib/hreflang.ts は、Next.js が各ページの <head> にレンダリングする
alternates.languages マップを構築します。その構築は一つのルールを守ります。
すなわち、ロケールの代替言語リンクは、そのロケールに作成済みコンテンツが
ある場合に のみ 出力されます。今日のところ翻訳済みロケールは英語だけで
あるため、すべてのページはちょうど 2 つのリンクを出力します:
<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />ページの canonical リンクは常にそのページ自身の URL です —— ロケールを
またいで指し示すことは決してありません。あるロケールのコンテンツが入り、
site/lib/i18n.ts でそのステータスが翻訳済みに切り替わると、そのロケールの
hreflang リンクは自動的に出力され始め、同じ変更セットでロケールごとの
ルーティングが有効化されます。
右書きレンダリング
アラビア語はコホートの右書きロケールです。サイトはそれに対応する準備が できています:
- 論理 CSS プロパティのみ。 共有スタイルシートとコンポーネントは、
物理プロパティ(
margin-left、text-align: left)ではなく論理プロパティ (margin-inline-start、padding-inline-end、text-align: start、inset-inline-start)を使用します。論理プロパティはdir="rtl"下で 自動的に反転するため、同じスタイルシートが両方の書字方向を正しく扱います。 - 書字方向属性。 アラビア語ページは、アラビア語コンテンツが入った時点で、
lang="ar"とともに<html>要素にdir="rtl"を設定します。 - 双方向コンテンツ。 書字方向が混在する文字列 —— 例えばアラビア語の
段落内の英語コマンド —— は
<bdi>でラップされ、埋め込まれた左書きの 連なりが右書きの流れの中で正しくレンダリングされます。
翻訳の追加
サイトをコホートのロケールへ翻訳するには:
- そのロケールについてレビュー済みの翻訳ページを作成します。
site/lib/i18n.tsでそのロケールのコンテンツステータスを翻訳済みに 切り替えます。- その
hreflangリンクが出力され始め、そのルートが到達可能になります。
あるロケールの翻訳が作成・レビューされるまでは、英語ページを信頼できる 情報源として保ちます。未レビューの機械翻訳コンテンツは一切出荷されません。
現状と、翻訳済みコーパスへの道のり
今日のところ、サイトは国際化に対応していますが、コンテンツは英語のみです。
インフラ —— コホート宣言、hreflang の仕組み、論理 CSS による右書き対応
—— は整備されていますが、ロケールごとの翻訳済みコーパスはまだありません。
完全に翻訳されたコーパスはフィーチャーティアの作業です。すなわち、各ロケールの
ページは機械で種付けされ、その後に人間によってレビューされ、各ロケールが
レビューのしきい値をクリアして初めて、リリースは国際化の観点で本番準備が
整います。それまでは、コホートは宣言され、ギャップは可視化され、未レビューの
翻訳は一切出荷されません。