Crofty on nsys.dev 技術ブログ

多言語サイトの設計 ― テキストを 3 種類に分けて持つ

Mon, 15 Jun 2026 13:00:00 +0900

シリーズ・第 3 回 — 「個人で出版ツールを作って配るまで」（全 5 回予定）。前回は出力を契約する話でした。一覧はシリーズの記事一覧から。今回のテーマは「多言語対応をどう設計するか」です。

「サイトを多言語にする」と聞くと、まず本文の翻訳を思い浮かべます。でも実際にやってみると、翻訳が要るテキストは本文だけではありませんでした。ナビのラベル、プロフィール、設定値。それぞれ性質が違い、同じ入れ物に押し込むと無理が出ます。

うまくいったのは、テキストを種類ごとに分けて、それぞれに合った持ち方をする設計でした。今回はその話です。例として Hugo（crofty が内部で使うもの）を挙げます。

テキストは 3 種類に分かれる

多言語サイトのテキストを整理すると、だいたい次の 3 種類になります。住む場所も、翻訳の仕組みも別です。

種類	例	持ち方
本文	記事	言語ごとのファイル
固定文言	ナビ、ボタン、「Support」	言語 → 文字列の翻訳テーブル
設定・データ	サイト設定、プロフィール	フィールド単位で「共通」か「言語ごと」

ひとつずつ見ます。

本文 ― 言語ごとのファイル

記事は、ひとつのフォルダ（ページバンドル）に言語別のファイルを並べます。

content/posts/my-article/
  index.md       … 日本語（既定言語）
  index.en.md    … 英語
  photo.avif     … 同梱する画像

ビルドすると /posts/my-article/ と /en/posts/my-article/ の両方ができ、言語の切り替えはページ同士のリンクで済みます。JavaScript は要りません。

ひとつだけ小さな罠があります。画像（ページではないファイル）は既定言語のパスにしか出力されないので、英語版から相対参照すると 404 になります。英語版だけ、絶対パスで既定言語側を指せば直ります。

![図](photo.avif)                     <!-- 日本語：相対でよい -->
![図](/posts/my-article/photo.avif)   <!-- 英語：絶対パスで指す -->

固定文言 ― 翻訳テーブル

ナビゲーションやボタンのラベルのような、記事に依らない固定の文言は、本文に混ぜません。言語から文字列を引く「翻訳テーブル」でまとめて持ちます。

出力を契約する ― 配ったあとも中身を変えられるようにする

Mon, 15 Jun 2026 11:00:00 +0900

シリーズ・第 2 回 — 「個人で出版ツールを作って配るまで」（全 5 回予定）。前回は全体像と前提を共有しました。各回は単独でも読めます。一覧はシリーズの記事一覧から。今回のテーマは「配ったあとも、中身を変えられるようにしておく」です。

自分だけで使う道具なら、いつでも自由に作り変えられます。問題は、公開して他の人が使い始めたあとです。

たとえば設定キーをひとつ改名しただけで、その古いキーを使っていた利用者の環境は動かなくなります。配ったあとは、利用者が頼っている部分を気軽に変えられない。「外から見えるものは、いつか誰かが当てにする」——これは Hyrum の法則として知られる、ごく当たり前の現象です。

そこで配る前に決めておきます ― 何を約束として固定し、どこは自由に変えてよいことにするか。crofty はその約束を「出力」に置きました。

入力か、出力か

ここでの「入力」と「出力」は、道具（crofty）が受け取るもの（あなたが書く記事や設定）と、生み出すもの（dist）です。約束をどちらに置くか、二択になります。

	入力を契約する	出力を契約する
固定するもの	設定キー・ファイル構成・テーマ内部	生成 HTML に必ず入る項目
内部の変更	利用者の環境が壊れやすい	契約さえ守れば自由
つらくなる例	キー名の改名、部品の作り替え	契約を破ったときだけ

入力を契約すると内部実装が約束になり、出力を契約すると作り方が自由になります。crofty が選んだのは後者です。

「契約」の正体 ― 実物を見る

言葉だけだと抽象的なので、実物を見ます。crofty が生成する記事ページの <head> には、必ず次が入っています。

<!-- 生成された HTML（抜粋） -->
<html lang="ja">
  <head>
    <title>記事タイトル · サイト名</title>
    <link rel="canonical" href="https://example.com/posts/hello/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- ＋ フィード(/feed.xml)があり、外部へ勝手に通信するタグは無い -->
  </head>

この「必ず入っている項目」こそが契約です。lang や canonical が欠けたページを、crofty は出力しません。逆に、ここに無いもの（テーマの作り方、HTML の組み立て方）は、自由に変えてよい部分です。

固定するのは真ん中の一本（出力契約）だけ。上の実装は動かしてよい

文書ではなく、機械で守る

契約は文章で書くだけだと、いつか実装とずれて腐ります。そこで crofty doctor が、ビルドした dist が契約を満たしているか毎回チェックします。

書いたものを自分の手元に置く ― Markdown から記事を出す小さな出版ツールを作りました

Mon, 15 Jun 2026 10:00:00 +0900

シリーズ・第 1 回 — 「個人で出版ツールを作って配るまで」（全 5 回予定）。各回は単独でも読めますが、まとめて辿るならシリーズの記事一覧からどうぞ。今回は全体像と前提の共有で、個々の設計判断は次回以降に取り上げます。

書いたものは、どこに残るでしょうか。

普段、文章を書く場所の多くは、誰かのプラットフォームの上です。読んでもらいやすい一方で、記事の住所（URL）も、見た目も、読者との接点も、その場所の仕様に委ねることになります。サービスが方針を変えたり、畳んだりすれば、書いたものもそれに従うしかありません。

それ自体が悪いわけではないのですが、「長く手元に残しておきたい文章」については、もう少し自分の側に置いておきたい。そう思ったのが、小さな出版ツール crofty を作りはじめたきっかけでした。

このシリーズでは、その crofty を作って配るまでに考えたこと・つまずいたことを、テーマごとに分けて残していきます。今回はその土台として、「何をしたかったのか」と「全体の流れ」をまとめます。

何をしたかったか

やりたかったことは、ひとことで言うと「自分のコンテンツを所有したまま出版する」ことでした。具体的には、次の 4 つです。

自分のドメインで出す — 記事の住所（URL）を、自分の側に持っておく
Markdown で書く — プレーンテキストなら、どこにでも移せて、長く読める
静的サイトにする — データベースを持たず表示が速い。仕組みを入れ替えても記事はそのまま
エッジから配信する — 世界中どこからでも、軽く開ける

平たく言えば、「書いたものが、それを作る道具より長生きする」状態にしておきたかった、ということです。

なぜ既存のツールそのままではないのか

ここで正直な疑問があります。静的サイトを作る道具（いわゆる SSG）はすでに優秀なものが揃っていて、たとえば Hugo はとても速くて安定しています。実際、crofty も内部では Hugo を使っています。では、なぜわざわざ別の道具を作ったのか。

理由は、「出版」は書くこと自体だけでは終わらないからです。実際にやってみると、書く前後にこまごました工程がついてきます。

記事を書く土台を用意する（最初のセットアップ）
体裁が整っているかを確かめる
出力が、配信先で正しく開ける形になっているかを確かめる
配信する
後から見た目や設定を見直す

これらを、その都度ばらばらの手順でやるのではなく、コマンド 1 つずつの薄い手順にまとめておきたかった。crofty は、Hugo を置き換えるものではなく、その上に薄くかぶせた小さな道具です。土台は素の Hugo のままなので、いつでも crofty を外して、ただの Hugo プロジェクトとして扱えます。この「いつでも自分の手元に戻せる」感覚も、最初から大事にしていました。

なお、「道具を変えても記事は自分のもの」をどう保証するかは、それ自体で 1 本の記事になるテーマなので、次回にゆずります。

全体の流れ

実際の流れは、とてもシンプルです。Markdown を書いて、組み立てて、配る。ほぼそれだけです。

書く → 組み立てる → 配る、という一本道

登場するコマンドも、役割で並べるとこれだけです。