> ## Content Index
> Fetch the complete content index at: https://konogaijin.com/llms.txt
> Use this file to discover other available public pages before exploring further.
# Ghost を多言語にした話 — 共有したかった
- URL: https://konogaijin.com/ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/
- Published: 2026-09-20T04:21:38.000Z
- Updated: 2026-09-20T04:21:38.000Z
- Description: こんにちは。 このブログは Ghost で作った。ブログ／ニュースレターの道具としてもプラットフォームとしてもとても良いんだけど、多言語はあまり上手くサポートしてくれない。まあ、僕が欲しい形では、ね。
- Author: Kit
- Tags: #lang-ja-jp, #translation-translation-architecture, Architecture
こんにちは。 このブログは Ghost で作った。ブログ／ニュースレターの道具としてもプラットフォームとしてもとても良いんだけど、多言語はあまり上手くサポートしてくれない。まあ、僕が欲しい形では、ね。
多言語の Ghost ブログでみんな詰まるのは、Ghost がそもそもあまり上手くやってくれないからだ。テーマは訳せる。でも多言語の記事やニュースレター向けのちゃんとした道具はない。僕はニュースレターとメンバーシップの仕組みが欲しくて Ghost を *ほんっとうに* 使いたかったので、i18n（多言語フレンドリー）にしてみた。この記事はそのやり方。本番コードを一行残らず書くつもりはない——退屈すぎる。要点を説明して、自分で発明しないといけない部品を見せて、`docker compose up` できる [最小サンプルリポジトリ](https://github.com/JoaoVictorLouro/ghost-i18n-sample?ref=konogaijin.com) を置いておく。
急いでいるなら、好きなフレーバーの LLM にこの文章を放りこんで、セットアップをコピーしてと頼めばいい。たぶんそこそこ動く（責任は負わない！）。どっちの道を選んでも、役に立ったら kudos や露出、面倒を減らしたお礼にコーヒーくらいいただけると嬉しい。
追記: これは Ghost を **セルフホスト** している人向け。Ghost(Pro) でも読み進めていいけど、余分な部品は自分でホストすることになる。それが嫌なら、ここで止めて大丈夫。
追記その2: テンプレートが *どう振る舞うか* は話す。ゼロからテーマを組む手順は教えない。それは [Ghost チームの Default template explained](https://ghost.org/tutorials/default/?ref=konogaijin.com) と [Mat Duggan の Write your own Ghost theme](https://matduggan.com/write-your-own-ghost-theme/?ref=konogaijin.com) をどうぞ。
---
Ghost は一度に一つの言語しか話さない。このサイトは四つ話す——英語（米国）、日本語、ブラジルポルトガル語、ラテンアメリカスペイン語——Ghost に翻訳モジュールが生えたふりはしない。トリックは「i18n プラグイン」一つではない。邪魔し合わない小さな仕組みが三つある。記事のまわりの文言（ナビ、ボタン、空の状態）、記事そのもの（言語ごとに Ghost の投稿を一つ、タグでつなぐ）、メールリスト（ロケールごとにニュースレター一つ）。
絵を一枚だけ覚えるならこれだ。**コンパイルしたヘルパー付きのテンプレート、言語タグ付きの投稿、言語ごとのニュースレター。** ロケール一覧を共有する。
## 目次
1. [Ghost だけでは足りない](#ghost-%E3%81%A0%E3%81%91%E3%81%A7%E3%81%AF%E8%B6%B3%E3%82%8A%E3%81%AA%E3%81%84)
2. [ほか全部がコピーするロケール一覧](#%E3%81%BB%E3%81%8B%E5%85%A8%E9%83%A8%E3%81%8C%E3%82%B3%E3%83%94%E3%83%BC%E3%81%99%E3%82%8B%E3%83%AD%E3%82%B1%E3%83%BC%E3%83%AB%E4%B8%80%E8%A6%A7)
3. [三つの層](#%E4%B8%89%E3%81%A4%E3%81%AE%E5%B1%A4)
4. [レイヤー 1 — テンプレートを訳す](#%E3%83%AC%E3%82%A4%E3%83%A4%E3%83%BC-1--%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%82%92%E8%A8%B3%E3%81%99)
5. [レイヤー 2 — 記事を訳す](#%E3%83%AC%E3%82%A4%E3%83%A4%E3%83%BC-2--%E8%A8%98%E4%BA%8B%E3%82%92%E8%A8%B3%E3%81%99)
6. [マップ用の小さな Python サーバー](#%E3%83%9E%E3%83%83%E3%83%97%E7%94%A8%E3%81%AE%E5%B0%8F%E3%81%95%E3%81%AA-python-%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC)
7. [レイヤー 3 — ニュースレターフォームをつなぐ](#%E3%83%AC%E3%82%A4%E3%83%A4%E3%83%BC-3--%E3%83%8B%E3%83%A5%E3%83%BC%E3%82%B9%E3%83%AC%E3%82%BF%E3%83%BC%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%82%92%E3%81%A4%E3%81%AA%E3%81%90)
8. [ウォークスルー: この原稿を四言語で出す](#%E3%82%A6%E3%82%A9%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%AB%E3%83%BC-%E3%81%93%E3%81%AE%E5%8E%9F%E7%A8%BF%E3%82%92%E5%9B%9B%E8%A8%80%E8%AA%9E%E3%81%A7%E5%87%BA%E3%81%99)
9. [チェックリスト](#%E3%83%81%E3%82%A7%E3%83%83%E3%82%AF%E3%83%AA%E3%82%B9%E3%83%88)
## Ghost だけでは足りない
Ghost はテンプレートを訳せる——まあ、ある程度は。組み込みの `{{t}}` ヘルパーは **Admin Settings のサイト言語** に従う。サイトを日本語にすると、すべての URL が日本語を話そうとする。それは欲しくなかった。言語ごとにパスを分けたかった。`/en-us`、`/pt-br`、`/ja-jp` といった具合。URL を見れば言語が分かる（SEO と共有に便利）。リダイレクトや判定も、良い意味で退屈になる。
Ghost には「この投稿はあの投稿の翻訳」というフィールドもない。投稿は投稿。日本語版が欲しければ、二つ目の投稿を作る。言語ピッカーで互いを見つけさせたいなら、リンクは自分で発明する。
だからこのスタックが答えるのは、別々の三つの問いだ。
- **テンプレート** はどうやって `/pt-br/` にいると知るのか。
- **記事** はどうやって正しいインデックスに乗り、兄弟投稿はどうやって互いを見つけるのか。
- **購読フォーム** はどうやって英語リストではなくポルトガル語リストに入れるのか。
## ほか全部がコピーするロケール一覧
テンプレートに触る前に、ここから始めてほしい。言語が五箇所に散らばると、一生タイポ探しをすることになる。テーマも記事ルートも翻訳マップも、**一つの一覧** からコピーしたかった。その一覧に言語を足せば、残りがついてこられるように。ランダムな Handlebars に `"japanese"` をハードコードすると、存在を忘れる。
### 言語を選び、デフォルトを一つ決める
本当に書く相手を書き出す。「いつか全言語」ではなく、維持できるもの。僕は英語（米国）、日本語、ブラジルポルトガル語、ラテンアメリカスペイン語だった。それから **デフォルトを一つ** 選ぶ。言語タグなしで出てしまった投稿の居場所であり、ブラウザが助けてくれないときの `/` の行き先。僕のは英語。
四つは必須じゃない。二つでも、もう本物の多言語サイトだ。言語は好きなだけ増やせる。というかこの仕組みは言語専用でもない。本気なら、地域でも同じことができる。
### 言語ごとに三つの名前を付ける
地味なパートで、ここで詰まる人が多い。ロケールには識別子が三つ要る。URL、ブラウザ、Ghost が同じ方言を話さないからだ。
1. **URL コード。** 小文字、ハイフン、退屈。`en-us`、`pt-br`、`ja-jp`。パスの先頭セグメント（`/pt-br/articles/…`）。安定させておく。ルート、サイトマップ、自分の頭に貼ることになる。
2. **BCP-47 タグ。** `` と `hreflang` に使う。だいたい `en-US` や `pt-BR`。ラテンアメリカスペイン語は厄介で、国が一つではないので、URL が `es-la` でも正直なコードは `es-419`。BCP タグ一覧: [Language tags on Wikipedia](https://en.wikipedia.org/wiki/IETF%5Flanguage%5Ftag?ref=konogaijin.com)。
3. **Ghost の内部タグ。** 投稿にロケール欄はないので、タグでごまかす。僕は `#lang-en-us`、`#lang-pt-br` などを使う。記事の可愛いチップに出ないよう Ghost では **internal** にする。エディタでは `#` 付きの名前を打つ。ルートやフィルタでは Ghost のスラッグになる。`#lang-pt-br` は `hash-lang-pt-br`。同じタグ、二つの綴り。それが分かると、Ghost のフィルタ構文がお化けに見えなくなる。
一覧にラベルを足してもいい。設定画面用の長い英語名、言語ピッカー用の現地語（`Português`、`日本語`）など。
一覧の一行の小さな例:
```js
{
code: "pt-br", // URL: /pt-br/
bcp47: "pt-BR", //
tagName: "#lang-pt-br",
tagSlug: "hash-lang-pt-br",
label: "Brazilian Portuguese",
nativeLabel: "Português",
}
```
言語ごとにこのオブジェクトを繰り返し、デフォルトコードを指す `DEFAULT_LOCALE` を足す。モジュールでも JSON でも YAML でも、スタックがもう使っているものでいい。形式は論点じゃない。論点は **ほかが新しい綴りを発明しないこと**。
### Ghost のタグは一度だけ作る
Ghost Admin → Tags を開き、`#lang-*` を内部タグとして作る。言語が二つなら手で十分。
ついでに、**同じ話** の翻訳がどう互いを見つけるか決める。僕は二つ目の内部タグ `#translation-{some-stable-name}` を使う。安定した名前は自分で選ぶスラッグ。`how-i-learned-to-stop-worrying` でも `translation-architecture` でも。その話の各言語版は **同じ** グループタグに、自分の `#lang-*` を足す。言語は「この投稿はポルトガル語」と言う。グループタグは「この投稿はあの英語版のポルトガル語の兄弟」と言う。
初日にグループタグは要らない。「別の言語で読む」リンクが欲しくなった瞬間に要る。ウィジェットが要らなければ飛ばしていい。
### ニュースレターグループを作る
Ghost はすでに人にメールを送れる。**知らない** のは、`/pt-br/` がポルトガル語リストに入るべきだということ。箱から出すとニュースレターは一つ。単言語ブログならそれでいい。このセットアップでは **言語ごとにニュースレター一つ**。深夜1時でも見分けがつく名前にしておく。
Ghost Admin → Settings → Newsletters を開き、ロケール表の各行にリストを作る。僕は URL コードから、でかくて分かりやすい名前にした。`Newsletter EN-US`、`Newsletter PT-BR` など。名前は自分用。Ghost はついでに id もくれる——長くて変な文字列。購読フォームで後で要る。ロケール一覧の横に小さなマップを置く:
```js
{
"en-us": "the-ghost-id-for-english",
"pt-br": "the-ghost-id-for-portuguese",
}
```
リストを作ったあと、その id をマップにコピーする。タグと同じ発想。一度やって、それから名前を発明するのをやめる。
痛みを減らす習慣がいくつかある。
- **安定した名前。** 来年 `Newsletter PT-BR` を `Novidades` に改名しても、*自分の* マップのキーは `pt-br` のまま。検索キーは URL のロケールであって、綺麗なタイトルではない。
- **送信は言語ひとつ。** 投稿のポルトガル語版を出すとき、ポルトガル語のニュースレターを付ける。その投稿に英語リストを付けると、ポルトガル語の購読者に申し込んでいない言語が届く。ガードレールはない。公開を押す前に二度見る。出す前に、出すものを読んでるよね？
まだメールを送っていないなら、このパートは飛ばしていい。タグとロケール一覧はそのままで動く。送信ボタンが本当に欲しくなった週にニュースレターを足す。Ghost がデフォルトを出したからといって、「Newsletter」という五本目の、ドキュメントにないリストを育てないこと。
### 一覧を法律にする
そのあとのルールは技術ではなく社会的なものだ。新しいロケールが出るなら、**まず一覧に** 出す。それからルート、テーマ文言、ニュースレター、言語タグをそこから生成する。「一箇所だけだし」とテンプレートに `ja-jp` を打ち始めた瞬間、五冊目のコピーが生まれる。
セットアップはこれ全部。短い言語の表、三つずつ名前、Ghost のタグ、ロケールごとにニュースレター一つ、デフォルト一つ。次の節は、その一覧がテーマと記事 URL と購読フォームに現れるだけ。
## 三つの層
```mermaid
flowchart TB
subgraph templates [Template i18n]
json[locale JSON dictionaries]
build[compile to Handlebars]
partials[ui helper and nav]
block[locale contentFor stamp]
json --> build --> partials
block --> partials
end
subgraph articles [Article translations]
tags["hash-lang-* plus hash-translation-*"]
collections[Ghost collections]
mapBuild[sidecar builds JSON map]
jsonMap["/i18n/article-translations.json"]
ui[nav picker and post switcher]
tags --> collections
tags --> mapBuild --> jsonMap --> ui
end
subgraph newsletters [Locale newsletters]
ghostNL[one Ghost newsletter per locale]
nlJson[locale to newsletter id]
form[Members subscribe form]
ghostNL --> nlJson --> form
end
```
左から右へ読む。パイプラインではない。Subscribe ボタンのラベルを変えても記事マップには触れない。日本語の下書きを出しても英語辞書は書き換わらない。`Newsletter PT-BR` に登録しても翻訳グループは増えない。
レイヤー 1 はテーマ、レイヤー 2 は投稿（それに兄弟マップを出す小さなサーバー）、レイヤー 3 は購読フォーム。
## レイヤー 1 — テンプレートを訳す
### 簡単な版
テーマは四言語で「Subscribe」と言わなければいけない。Ghost は URL からその文字列を選んでくれない。だからロケールごとに JSON 辞書を一つ置き、Handlebars にコンパイルし、レイアウトが描画する前に各ページへ今のロケールをスタンプする。
Ghost 本体の `locales/en.json`（や `pt-BR.json`、…）と混ぜないこと。あれは `{{t}}` の餌で、まだ Admin の **サイト** 言語に従う。自分の辞書は、URL（または投稿の `#lang-*` タグ）に従う **コンパイル済み** ヘルパーの餌。フォルダ二つ、仕事二つ。
### ロケールをスタンプする
Ghost のカスタムルートは、URL を **名前付きテンプレート** に向けられる。だから各ロケールのホームは小さなラッパー。`home-en-us.hbs` はホームページを複製しない。「このページは `en-us` / `en-US`」と言って `home.hbs` を include するだけ。記事インデックスと about も同じ（`index-pt-br.hbs` → `index.hbs`）。ラッパーが要るのは、`routes.yaml` の `template:` が Ghost のファイルの選び方だから。パスからロケールを推測してはくれない。
そのスタンプは Handlebars の content ブロック:
```handlebars
{{#contentFor 'locale'}}pt-br{{/contentFor}}
{{#contentFor 'bcp47'}}pt-BR{{/contentFor}}
{{!< index}}
```
記事はロケールごとのテンプレート名をそうは使えない——全部 `post.hbs`。代わりに小さなパーシャルが投稿の内部タグを歩く。`#lang-ja-jp` が見えた？ テンプレートファイルは同じでも、ページは日本語になる。
レイアウトはそれをブラウザが読める形にコピーし、パスの先頭セグメントも覗く。だから `` が `/ja-jp/…` と揃う。
`/` に当たっても、レイアウト用の言語は選ばれない。小さな判定ページが `navigator.languages` を見て `/en-us/`、`/ja-jp/`、`/pt-br/`、`/es-la/` へリダイレクトする。本物のホームは全部プレフィックスの下。
### 文言の置き場所
編集するコピーは、テーマの横にロケールごとの JSON ファイル一つ:
```
themes/your-theme/locales/en-us.json
themes/your-theme/locales/ja-jp.json
themes/your-theme/locales/pt-br.json
themes/your-theme/locales/es-la.json
```
英語ではキーはこんな感じ:
```json
{
"Subscribe": "SUBSCRIBE_TO_FEED",
"No posts": "NO_SIGNAL"
}
```
ポルトガル語ファイルは同じキー、違う値。テンプレートはそういう文をハードコードしない。キーを聞く:
```handlebars
{{> "ui" key="Subscribe"}}
```
### ランタイム参照ではなくコンパイルする理由
前の節で `{{t}}` に会った。`/pt-br/` にはついていけない。ブラウザで JSON を取る手もあるけど、最初の描画が英語でチラつき、検索エンジンはポルトガル語のナビを見ず、どのテンプレートにも JavaScript の山が生える。SEO に悪い、初回ロードはもっと悪い、ただ醜い。
だからコンパイルする。小さなビルドが辞書を読んで、全言語がすでに入った Handlebars を書く。普通のページではロケールブロックにマッチ（`{{#match (block "locale") "pt-br"}}…`）。投稿では `#lang-*` タグにマッチ。テンプレートは相変わらず `{{> "ui" key="Subscribe"}}` に見える。中身は生成された `if / else if` の木。
つまりテーマに新しいコピー／文言を足すたびに、ビルドして、Ghost でテーマをリロードする。 面倒なのは分かってる。でもテーマに新しいテキストを足す機会なんて、そもそもそんなにないはず。（記事じゃないんだし。）
その生成パーシャルは成果物として扱え。手で彫るファイルではない。コンパイル済みヘルパーを手で直すと、次のビルドが丁寧に午後を壊す。
実務の細部: コンパイル済みヘルパーはコンパクトに——文字列の中に余計な改行を入れない。`aria-label` や `placeholder` に放り込むし、属性の中の Handlebars の空白は、欲しくない贈り物だ。
### 例: ボタンの名前を変える
英語の購読 CTA は `OPEN_CHANNEL` のまま、ポルトガル語は `ABRIR_CANAL` にしたい。
1. テンプレートがすでに使っているキーで、ポルトガル語のロケールファイルを直す。
2. コンパイルを走らせて、Handlebars ヘルパーに新しい文字列を拾わせる。
3. Ghost でテーマをリロードする。
Ghost の投稿には触っていない。ニュースレターにも触っていない。`/pt-br/` の読者は新しいラベルを見る。`/en-us/` は見ない。
## レイヤー 2 — 記事を訳す
### 簡単な版
記事は本文が四つ入った一つのエントリではない。**Ghost の投稿が四つ**（実際に書いた言語の数だけ）。言語タグが各投稿を正しいインデックス URL に乗せる。共有の翻訳タグが、同じ話だとサイトに教える。そのタグから作った小さな JSON マップが、「別の言語で読む」リンクを動かす。URL は一つずつ一つの言語のまま。検索エンジンがちゃんと順位を付けられる。
### 言語タグと URL
Ghost の collections（`routes.yaml` の中）が、どの投稿がどのパスの下に出るかを決める。デフォルト以外のロケールは素直なタグフィルタ。**デフォルト** ロケールは残り物のバケツ: ほかの言語でタグ付けされて *いない* もの全部。英語を `tag:hash-lang-en-us` でフィルタすると、古いタグなし投稿がインデックスから消える。反転フィルタこそがポイント全部。
```yaml
collections:
/pt-br/articles/:
permalink: /pt-br/articles/{slug}/
template: index-pt-br
filter: tag:hash-lang-pt-br
/en-us/articles/:
permalink: /en-us/articles/{slug}/
template: index-en-us
filter: tag:-hash-lang-ja-jp+tag:-hash-lang-pt-br+tag:-hash-lang-es-la
```
日本語とスペイン語も同じ発想。`tag:hash-lang-ja-jp`、`tag:hash-lang-es-la`。ロケールごとに collection を繰り返す。
英語の原稿にも `#lang-en-us` は付ける。テーマ、hreflang、マップが日本語と同じ見方でロケールを見られるように。反転フィルタは、**インデックス** がはぐれ者に優しくあるためだけ。
`Architecture` のような公開タグはトピック。見えるチップ。言語ではない。投稿は同時に `#lang-pt-br` \+ `Architecture` \+ `#translation-translation-architecture` でいい。
スラッグは記事と一緒に訳す。英語パスに `-ja` / `-pt` / `-es` をボルトで足して使い回さない。URL に言語と中身を反映させたい。SEO に大事:
- English: `i-made-ghost-work-with-multiple-languages`
- Japanese: `ghost-wo-tagengo-ni-shita-hanashi`
- Portuguese: `fiz-o-ghost-funcionar-com-varios-idiomas`
- Spanish: `hice-que-ghost-funcionara-en-varios-idiomas`
ソフトウェアが兄弟をつなぐのに使うのは、まだ **タグ**。スラッグは人間と検索用。
### 例: 一つの話、四つの投稿
| Locale | Ghost slug | Language tag | Shared group tag | Public URL |
| ------ | ------------------------------------------- | ------------ | ------------------------------------- | ------------------------------------------------------------ |
| en-us | i-made-ghost-work-with-multiple-languages | #lang-en-us | #translation-translation-architecture | /en-us/articles/i-made-ghost-work-with-multiple-languages/ |
| ja-jp | ghost-wo-tagengo-ni-shita-hanashi | #lang-ja-jp | #translation-translation-architecture | /ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/ |
| pt-br | fiz-o-ghost-funcionar-com-varios-idiomas | #lang-pt-br | #translation-translation-architecture | /pt-br/articles/fiz-o-ghost-funcionar-com-varios-idiomas/ |
| es-la | hice-que-ghost-funcionara-en-varios-idiomas | #lang-es-la | #translation-translation-architecture | /es-la/articles/hice-que-ghost-funcionara-en-varios-idiomas/ |
言語タグがないと、日本語本文が英語インデックスに漏れる（英語は「ja/pt/es ではないもの全部」だから）。グループタグがないと、無関係な投稿が四つ。ピッカーは日本語の兄弟ではなく `/ja-jp/` のホームへ送る。
ページも両方のタグを持てば、このマップに入れる。About は collection の投稿ではなくロケールルート（`/pt-br/about/`）であることが多いけど、マップは気にしない——公開済みの投稿 **と** ページをスキャンする。
### 翻訳マップ
誰かが公開コンテンツを歩いて、**両方** のタグがある投稿だけ残す必要がある。下書きは公開マップに出ない。言語タグはあるがグループタグがない公開済み英語投稿も、スイッチャーからは見えない（`/en-us/articles/` には出る）。
結果はテーマが `fetch()` できる JSON として出す:
```
GET /i18n/article-translations.json
```
この記事の削った例:
```json
{
"updated_at": "2026-09-19T00:00:00.000Z",
"by_url": {
"https://example.com/en-us/articles/i-made-ghost-work-with-multiple-languages/": "translation-architecture",
"https://example.com/ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/": "translation-architecture"
},
"groups": {
"translation-architecture": {
"en-us": {
"url": "/en-us/articles/i-made-ghost-work-with-multiple-languages/",
"title": "I made Ghost work with multiple languages"
},
"ja-jp": {
"url": "/ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/",
"title": "Ghost を多言語にした話"
}
}
}
}
```
`by_url` は「今この絶対 URL に立っている。どのグループ？」`groups` は「そのグループで、日本語のパスとタイトルは？」`groups` のパスはサイト相対。`by_url` のキーは絶対、スキームとホスト込み。
`window.location.href` で引かない。クエリ文字列、ハッシュ、末尾スラッシュの欠落、`www` と裸ホストで外れる。origin + pathname からキーを作り、末尾 `/` を強制して、Ghost が保存したものと揃える。
Ghost はこのファイルを作ってくれない。手で作り続けるのは嫌だったので、小さなサーバー／アプリにやらせた。
### 誰がこれを使うか
二つ。同じタグから。
1. **人。** 「別の言語で読む」リンク（と投稿のヘッダーピッカー）が JSON を取って兄弟 URL を指す。兄弟がなければ、その言語のホームか記事一覧へ落とす。
2. **Google。** ページの `` に `hreflang` を置いて、四つの URL が同じ話だと検索エンジンに教える。Ghost は翻訳タグでフィルタした `{{#get "posts"}}` でその投稿を列挙できる。`limit="all"` ではなく `limit="100"` —— Ghost 6 はどのみち “all” を無視する。
スイッチャーが空なら:
- 兄弟はまだ下書き？
- 両方の投稿に **同じ** グループタグ、そして `#lang-*` はちょうど一つずつ？
- 生の `href` ではなく origin + pathname（末尾スラッシュ）で引いた？
- sidecar は内部タグを本当に *見られる* API を使っている？（次の節。）
## マップ用の小さな Python サーバー
このマップを手で書いて維持するのは苦痛なので、Ghost の横で小さな Python プロセスを動かしている。
Ghost には API が二つある。公開の **Content** API は内部タグ（`#lang-*`、`#translation-*`）を隠すので、マップは空で返ってくる。代わりに **Admin** API を使う。Custom integration を作り、Admin キーをコピーし、サーバーに置く——テーマにもブラウザにも絶対入れない。
Admin API キーは Ghost Admin → Integrations → 自分の integration からコピーする。**ちょうど二部品** でなければいけない。key id、コロン、それから **hex** の secret。下の JWT は `split(":", 1)` して、後半に `bytes.fromhex` する。Admin API の JSON から文字列を組み立てるなら、`type` が `admin` の `api_keys` を見る。ときどき `secret` がすでに `id:hex`。そこにまた `id` を付けると三つになり、`fromhex` が `non-hexadecimal number found` で死に、マッププロセスは「動いてる」顔をしながら何も出さない。コロンを数える。セグメントは二つ。右が hex。
サーバーの仕事: Admin に公開済みの投稿とページを聞き、両方のタグがある行だけ残し、上の JSON を吐く。標準ライブラリだけ。Docker で Ghost のネットワークに乗せる。
環境変数:
- `GHOST_URL` — このコンテナが Ghost に届く経路（よくあるのは `http://ghost:2368`）。
- `SITE_URL` — 訪問者が見る公開 origin、末尾スラッシュなし（`https://your-blog.example`）。マップのキーはこれで作る。`GHOST_URL` ではない。
- `ADMIN_API_KEY` — Ghost Admin API キー、`id:secret`。Content API キーではない。
リクエストごとにマップを作り直していい。個人ブログなら遅くて正直。大きくなったら一分メモリにキャッシュ。それでもまだ性能や速い更新が欲しければ、Ghost の Webhooks で再構築してキャッシュする。
### `app.py`
これを `app.py` として置く。標準ライブラリだけ——短命の Admin JWT は `hmac`、`pip install` なし。
```python
#!/usr/bin/env python3
from __future__ import annotations
import base64
import hashlib
import hmac
import json
import os
import time
import urllib.parse
import urllib.request
from datetime import datetime, timezone
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
GHOST_URL = os.environ["GHOST_URL"].rstrip("/")
SITE_URL = os.environ.get("SITE_URL", GHOST_URL).rstrip("/")
ADMIN_API_KEY = os.environ["ADMIN_API_KEY"]
PORT = int(os.environ.get("PORT", "8080"))
LANG_PREFIX = "hash-lang-"
GROUP_PREFIX = "hash-translation-"
def b64url(data: bytes) -> str:
return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
def admin_token() -> str:
# ADMIN_API_KEY is "id:hexsecret". If `secret` from the Admin API already
# includes a colon, it is the full key — do not prefix the id again.
key_id, secret_hex = ADMIN_API_KEY.split(":", 1)
now = int(time.time())
header = b64url(
json.dumps(
{"alg": "HS256", "typ": "JWT", "kid": key_id},
separators=(",", ":"),
).encode()
)
payload = b64url(
json.dumps(
{"iat": now, "exp": now + 300, "aud": "/admin/"},
separators=(",", ":"),
).encode()
)
signing = f"{header}.{payload}".encode()
sig = b64url(hmac.new(bytes.fromhex(secret_hex), signing, hashlib.sha256).digest())
return f"{header}.{payload}.{sig}"
def fetch_all(kind: str) -> list[dict]:
items: list[dict] = []
page = 1
while True:
query = urllib.parse.urlencode(
{
"filter": "status:published",
"include": "tags",
"fields": "id,title,slug,url",
"limit": "50",
"page": str(page),
}
)
url = f"{GHOST_URL}/ghost/api/admin/{kind}/?{query}"
req = urllib.request.Request(
url,
headers={
"Accept-Version": "v6.0",
"Authorization": f"Ghost {admin_token()}",
},
)
with urllib.request.urlopen(req, timeout=30) as response:
payload = json.loads(response.read().decode())
items.extend(payload.get(kind, []))
pages = payload.get("meta", {}).get("pagination", {}).get("pages", 1)
if page >= pages:
break
page += 1
return items
def locale_and_group(tags: list[dict]) -> tuple[str | None, str | None]:
locale = group = None
for tag in tags or []:
slug = tag.get("slug") or ""
if slug.startswith(LANG_PREFIX):
locale = slug.removeprefix(LANG_PREFIX)
if slug.startswith(GROUP_PREFIX):
group = slug.removeprefix(GROUP_PREFIX)
return locale, group
def build_map(entries: list[dict]) -> dict:
groups: dict = {}
by_url: dict = {}
for entry in entries:
locale, group = locale_and_group(entry.get("tags") or [])
if not locale or not group:
continue
raw = entry.get("url") or f"/{locale}/articles/{entry['slug']}/"
path = (
urllib.parse.urlparse(raw).path
if raw.startswith("http")
else (raw if raw.startswith("/") else f"/{raw}")
)
if not path.endswith("/"):
path = f"{path}/"
groups.setdefault(group, {})[locale] = {
"url": path,
"title": entry.get("title"),
}
by_url[f"{SITE_URL}{path}"] = group
return {
"updated_at": datetime.now(timezone.utc).isoformat(),
"by_url": by_url,
"groups": groups,
}
class Handler(BaseHTTPRequestHandler):
def do_GET(self) -> None:
path = self.path.split("?", 1)[0]
if path == "/health":
body = b'{"ok":true}'
elif path == "/article-translations.json":
body = json.dumps(
build_map(fetch_all("posts") + fetch_all("pages"))
).encode()
else:
self.send_error(404)
return
self.send_response(200)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Cache-Control", "no-store")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def log_message(self, fmt: str, *args) -> None:
print(fmt % args)
if __name__ == "__main__":
print(f"translation map on :{PORT}")
ThreadingHTTPServer(("0.0.0.0", PORT), Handler).serve_forever()
```
### Docker
`Dockerfile`:
```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY app.py .
EXPOSE 8080
CMD ["python", "-u", "app.py"]
```
Compose で Ghost の隣:
```yaml
services:
ghost:
# your existing Ghost service
translation-map:
build: ./translation-map
environment:
GHOST_URL: http://ghost:2368
SITE_URL: https://your-blog.example
ADMIN_API_KEY: ${GHOST_ADMIN_API_KEY}
depends_on:
- ghost
```
追記: これは本番の完全なセットアップではない。必要に合わせて直していい。 この件は ghost のドキュメントを読むのを勧める: \[[https://docs.ghost.org/install/docker\]](https://docs.ghost.org/install/docker%5D?ref=konogaijin.com)(Docker Ghost Setup) と \[[https://docs.ghost.org/hosting\]](https://docs.ghost.org/hosting%5D?ref=konogaijin.com)(Docker Hosting Guide)
### テーマにつなぐ
レイアウトの中:
```html
```
投稿ページでその URL を `fetch` して、それから:
```js
const path = location.pathname.endsWith('/') ? location.pathname : `${location.pathname}/`;
const canonical = `${location.origin}${path}`;
const groupId = map.by_url[canonical];
const siblings = groupId ? map.groups[groupId] : null;
```
今のパスではない `url` を持つロケールすべてにリンクを描く。言語ピッカーも、読者が今選んだロケールで同じ引き方をする。兄弟がなければ `/{locale}/` か `/{locale}/articles/` にフォールバック。
## レイヤー 3 — ニュースレターフォームをつなぐ
言語ごとに Ghost のニュースレターを一つ作り、id をコピーしたところまで済んでいる。このレイヤーは **フォーム** が正しい id を選ぶ方法と、公開時にリストを付ける方法だけ。
サインアップは Ghost Members がやる。フォームに id を渡す:
```html
```
ロケール → id のマップを、テーマが読める場所に置く（テーマ配下の静的 JSON、または小さなインラインスクリプト——ブラウザから Admin API は呼ばない）。それからパスの先頭セグメントから、Ghost が本当に気にする属性をセットする:
```js
const locale = location.pathname.split('/').filter(Boolean)[0]; // "pt-br"
form.setAttribute('data-members-newsletter', newsletterIds[locale]);
```
`/pt-br/` の訪問者は `Newsletter PT-BR` に入る。アカウント画面では、有効なニュースレターを全部チェックボックスにして、バイリンガルが複数に入れるようにする。
**公開** するとき、その投稿を対応するリストに付ける。英語版 → `Newsletter EN-US`。ポルトガル語版 → `Newsletter PT-BR`。ニュースレター未設定の下書きは誰にもメールしない。リストを間違えると受信箱の言語も間違う。ガードレールはない。しくじるな。
## ウォークスルー: この原稿を四言語で出す
この記事が英語ソースだとする。
**English.** 投稿を作る。タイトルと本文は `en-US`。スラッグは `i-made-ghost-work-with-multiple-languages`。タグ: `#lang-en-us`、`#translation-translation-architecture`、チップが欲しければ公開トピックタグ。公開時に `Newsletter EN-US` を割り当てる。出る場所は `/en-us/articles/i-made-ghost-work-with-multiple-languages/`。テンプレートが英語なのは言語タグのおかげ。スイッチャーは兄弟ができるまで隠れたまま。
**Japanese.** **新しい** 投稿（英語の二つ目の本文ではない）。タイトル、抜粋、HTML、**そしてスラッグ** を訳す。本文中のコード、href、製品名はそのまま。スラッグは `ghost-wo-tagengo-ni-shita-hanashi`。タグ: `#lang-ja-jp` と **同じ** `#translation-translation-architecture`。公開時に `Newsletter JA-JP`。URL: `/ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/`。
ポルトガル語（`fiz-o-ghost-funcionar-com-varios-idiomas` / `#lang-pt-br` / `Newsletter PT-BR`）とスペイン語（`hice-que-ghost-funcionara-en-varios-idiomas` / `#lang-es-la` / `Newsletter ES-LA`）も繰り返す。
英語ページをリロードする。ウィジェットは 日本語 / Português / Español を出すはず。英語 URL のヘッダーピッカーは日本語ホームではなく日本語の兄弟へ飛ぶ。検索エンジンは Ghost のタグクエリから `hreflang` を見る。`/es-la/` で購読した読者はスペイン語の送信を受け取る。同じ話のメールが四つではない。
スペイン語でグループタグを飛ばすと、スペイン語は `/es-la/articles/…` に住むけど、ほか三ページはリンクしない。スペイン語で言語タグを飛ばすと、英語インデックスに出ることがある。ニュースレターを飛ばすと、アーカイブは動く。リストは送らない。
## チェックリスト
**各 Ghost サイトで**
1. 三つずつ名前の付いたロケール一覧と、デフォルト一つ。
2. Ghost の内部 `#lang-*` タグ（兄弟が欲しくなったら `#translation-*` も）。
3. ロケールごとにニュースレター一つ。id をテーマが読めるマップにコピー。
4. `routes.yaml` の collections（デフォルトロケールは反転フィルタ）と、`locale` / `bcp47` をスタンプするラッパーテンプレート。
5. JSON 辞書 + `ui` ヘルパー用のコンパイル。まだ使うなら Ghost 本体の `locales/en.json` は `{{t}}` 用に残す。
6. Admin API の sidecar。`/i18n/article-translations.json` を公開 origin にプロキシ。Admin キーが `id:hex`（二部品）で、二重の `id:id:hex` ではないことを確認。
7. `routes.yaml` が `/` を `locale-detect` に向けているなら、`/` をヘルスチェック扱いする前にカスタムテーマを有効化する。
**言語を増やしたいとき**
ロケール一覧 → `#lang-*` タグ → ニュースレター + id → ロケール JSON + コンパイル → collection + ラッパーテンプレート → マップに新しい `hash-lang-*` プレフィックスを教える。
**記事ごと**
1. ロケールごとに Ghost の投稿一つ——一つの本文に四言語は入れない。
2. 投稿ごとに `#lang-*` タグはちょうど一つ。
3. リンクしたい兄弟すべてに同じ `#translation-{group-id}`。
4. 公開タグはトピック専用。
5. スラッグは記事と一緒に訳す（`english-slug-ja` ではない）。
6. その版をメールするなら、公開時に `Newsletter {LOCALE}` を付ける。
7. 兄弟を出したら投稿をリロードし、origin + pathname を `by_url` と照合する。