Localization

Riebeckite では、@riebeckite/plugin-l10n を使って多言語 Site を構築できます。

l10n Plugin は、Content ごとの言語を判定し、

• 言語ごとの URL
• 同じ Content の翻訳版
• Site 内リンク
• 言語切り替え
• SEO と組み合わせた hreflang

などを扱います。

flowchart LR
    Content["Markdown"]
    L10n["l10n Plugin"]
    EN["English"]
    JA["日本語"]
 
    Content --> L10n
    L10n --> EN
    L10n --> JA

starter 以上の Preset では、次の7言語が設定されます。

en
ja
zh-CN
es
de
fr
ko

すべての言語の記事を用意する必要はありません。実際に利用する言語に合わせて設定できます。

基本設定

riebeckite.config.ts に l10n Plugin を追加します。

import { l10n } from "@riebeckite/plugin-l10n";
 
export default defineConfig({
  plugins: [
    l10n({
      defaultLang: "en",
      languages: ["en", "ja"],
    }),
  ],
});

この例では、

defaultLang
  → en
 
利用する言語
  → en / ja

となります。

defaultLang は、Content の言語を他の方法で判定できなかった場合にも使われます。

Content の言語を決める

l10n Plugin は、それぞれの Content が何語なのかを判定します。

判定には優先順位があります。

flowchart TD
    Start["Content"]
 
    Start --> FM{"frontmatterに<br/>言語がある？"}
    FM -->|Yes| Result["言語を決定"]
    FM -->|No| Detector{"custom detectorで<br/>判定できる？"}
 
    Detector -->|Yes| Result
    Detector -->|No| File{"ファイル名で<br/>判定できる？"}
 
    File -->|Yes| Result
    File -->|No| Default["defaultLang"]

優先順位は次のとおりです。

1. Frontmatter
2. Custom Detector
3. ファイル名
4. defaultLang

上の方法で判定できた時点で、その Content の言語が決まります。

Frontmatter で指定する

最も明示的なのは Frontmatter の lang です。

---
title: こんにちは
lang: ja
publish: true
---
 
日本語の記事です。

この Content は日本語として扱われます。

ファイルの場所や名前とは別に言語を明示したい場合に利用できます。

ファイル名で分ける

同じ Directory に複数言語の記事を置く場合は、ファイル名の末尾で分けます。

たとえば、

README.md
README.ja.md

のように配置します。

README.ja.md の .ja から、その Content が日本語だと判定できます。defaultLang の言語には接尾辞を付けません。

推奨は .言語 ですが、-言語 と _言語 も同じ意味で扱われます。

この方式なら、

docs/
├─ README.md
├─ README.ja.md
├─ installation.md
└─ installation.ja.md

のように、元の記事と翻訳版を近くに置いて管理できます。

Directory では分けない

言語ごとに Directory を分ける構成（en/note.md、ja/note.md）は、言語判定には使われません。

言語判定の暗黙ルールをファイル名の接尾辞だけに絞ることで、同じ名前の記事が複数言語で存在しても WikiLink が一意に解決されます。言語はファイル名の接尾辞か、Frontmatter の lang で指定してください。

翻訳同士を対応付ける

「この日本語記事と、この英語記事は同じ Content の翻訳版」という関係は、Frontmatter の translation で表します。

たとえば日本語版を、

---
title: こんにちは
publish: true
lang: ja
translation: hello
---
 
日本語の記事です。

とします。

対応する英語版にも同じ translation を指定します。

---
title: Hello
publish: true
lang: en
translation: hello
---
 
This is the English version.

両方に、

translation: hello

があるため、同じ Content の翻訳として扱われます。

flowchart LR
    EN["Hello<br/>lang: en"]
    Group["translation: hello"]
    JA["こんにちは<br/>lang: ja"]
 
    EN --> Group
    JA --> Group

lang と translation の違い

この2つは役割が異なります。

たとえば、

lang: ja
translation: getting-started

なら、

このページの言語
  → 日本語
 
翻訳グループ
  → getting-started

という意味になります。

translation 自体は言語名ではありません。

同じ内容を表すページ同士で共通の値を使います。

翻訳が存在しない場合

すべての Content にすべての言語版を用意する必要はありません。

たとえば、

article-a.md       日本語
article-a.en.md    English
article-b.md       日本語

のように、一部の言語版だけが存在しても構いません。

article-b の英語版が存在しない場合、Riebeckite が英語ページを自動生成することはありません。

flowchart LR
    JA["日本語ページ"]
    Check{"英語版が存在？"}
 
    JA --> Check
    Check -->|Yes| EN["英語ページ"]
    Check -->|No| None["何も生成しない"]

l10n Plugin は既存の翻訳関係を扱いますが、Content 自体を翻訳する機能ではありません。

URL

l10n Plugin は Content の言語情報を使って Public URL を扱います。

つまり、多言語化は単に画面へ言語名を表示するだけではなく、

Content
  ↓
言語判定
  ↓
Public Location
  ↓
URL

まで含めて処理されます。

Site 側でファイル名から独自に URL を組み立てるのではなく、Riebeckite が解決した Public Location を利用してください。

Public Location の仕組みについては Content System を参照してください。

Site 内リンク

多言語 Site では、本文中のリンクも言語を考慮して扱われます。

たとえば日本語の記事から別の記事へ移動するとき、対応する日本語版が存在する場合は、その言語に対応したリンクとして扱えます。

flowchart LR
    JA1["日本語 Article A"]
    EN2["Article B / English"]
    JA2["Article B / 日本語"]
 
    JA1 -.-> EN2
    JA1 -->|"対応する言語"| JA2

これによって、記事本文のリンクだけ別言語のページへ戻ってしまう、といった問題を避けられます。

言語切り替え

同じ translation を持つ Content は、言語切り替えの候補になります。

たとえば、

translation: hello
 
├─ lang: en
├─ lang: ja
└─ lang: de

という Content が存在すれば、それぞれを同じ Content の別言語版として扱えます。

実際に存在する翻訳だけが候補になります。

存在しない言語版への Fallback Page は自動生成されません。

SEO

SEO Plugin と組み合わせることで、翻訳関係を hreflang として出力できます。

概念的には、

English page
   ↕
translation relationship
   ↕
日本語 page
   ↓
SEO
   ↓
hreflang

という関係です。

これによって Search Engine に同じ Content の別言語版であることを伝えられます。

おすすめの構成

英語と日本語の2言語で運用する場合は、たとえば次のようにできます。

content/
├─ getting-started.md
├─ getting-started.ja.md
├─ installation.md
├─ installation.ja.md
└─ faq.ja.md

そして翻訳関係を Frontmatter で明示します。

英語版は次のとおりです。

---
title: Getting Started
lang: en
translation: getting-started
publish: true
---

日本語版は次のとおりです。

---
title: はじめに
lang: ja
translation: getting-started
publish: true
---

翻訳がまだ存在しない faq.ja.md は、日本語だけで公開しても構いません。

導入の流れ

多言語 Site を作る場合は、次の順番で考えると分かりやすくなります。

flowchart TD
    Lang["1. 使用する言語を決める"]
    Config["2. l10nを設定"]
    Detection["3. 言語の判定方法を決める"]
    Content["4. 各言語の記事を書く"]
    Translation["5. translationで対応付ける"]
    Link["6. URL・リンクを確認"]
    SEO["7. 必要ならSEOと組み合わせる"]
 
    Lang --> Config
    Config --> Detection
    Detection --> Content
    Content --> Translation
    Translation --> Link
    Link --> SEO

まとめ

Riebeckite の多言語対応では、次の3つを分けて考えると分かりやすくなります。

lang
  → このContentは何語か
 
translation
  → どのContentと翻訳関係にあるか
 
Public Location
  → その言語のContentをどのURLで公開するか

言語は、

frontmatter
    ↓
custom detector
    ↓
ファイル名
    ↓
defaultLang

の優先順位で判定されます。

翻訳関係は translation で明示し、実際に存在する翻訳だけを利用します。存在しない翻訳を Riebeckite が自動生成することはありません。

詳しい Option や Public API は、@riebeckite/plugin-l10n の Package README と Plugin API を参照してください。