Next.js で Markdoc をローカライズする
Next.js の App Router アプリケーションで、ロケール別の Markdoc 文書と個別の画面表示用カタログを使い、ルーティング、読み込み、翻訳、描画を行います。
翻訳した記事は、ページ全体の表示と整合していることが大切です。Next.js サイトでは、ルートのロケールに応じて、Markdoc 文書とナビゲーション用の画面表示カタログをそれぞれ選択できます。このガイドでは、これらのファイルを App Router のページに組み込み、CLI で翻訳する手順を紹介します。
Markdoc を使用している既存の Next.js App Router プロジェクトを使います。この例では、サーバー上でローカルファイルを読み込むため、React のローカライズ用アダプターには依存しません。
ロケール別のファイル構成を決める #
たとえば、文書と画面表示用カタログをロケールごとにまとめる構成にできます。
src/content/
en/
pages/home.mdoc
blog/welcome.mdoc
ui.json
es/
pages/home.mdoc
blog/welcome.mdoc
ui.json
src/app/[lang]/スラッグをコンテンツの識別子として使う場合は、変更せずに維持してください。見出しを翻訳しても、home.mdoc の名前を変える必要はありません。スラッグも意図的にローカライズする場合は、ナビゲーションや別言語へのリンクに使う対応関係を明示的に管理してください。本文を翻訳するだけでは、この対応関係は作成されません。
ファイルシステムのパスを組み立てる前に、ルートのロケールと文書のスラッグが、それぞれ既知の候補に含まれていることを確認してください。翻訳がない場合は、見つからないことを示す応答を返すか、原文の言語へ明示的にフォールバックするか、方針を決めておきます。後述のホームページの例では、固定の文書名を使い、未対応のロケールやファイルの欠落に対しては、見つからないことを示す応答を返します。
Markdoc ハンドラーと表示対象のメタデータを選ぶ #
プロジェクトのルートで CLI をインストールし、連携を設定します。
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo link生成された組織とローカライゼーションエンジンの識別子を .lingo/config.json に残したまま、翻訳元の選択に必要な設定をすべて指定します。
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [
{
"pattern": "src/content/en/pages/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{
"pattern": "src/content/en/blog/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{ "pattern": "src/content/en/ui.json" }
]
}.mdoc では Markdoc が自動的に選択されますが、形式を明示すると設定の意図が伝わりやすくなります。既存のプロジェクトで Markdoc 構文を .md に保存している場合は、format: "markdoc" を明示的に設定してください。設定しない場合、拡張子による判定で通常の Markdown が選択されます。この違いは、カスタムタグや選択したコンポーネント属性の処理に影響します。
フロントマターのうち、読者に表示するフィールドを意識して選んでください。日付、著者、固定の識別子、ルーティング用メタデータは、コンテンツの運用方針で特定の変換が求められない限り、変更せずに維持します。コンポーネントのプロパティは、読者向けのテキストを含む場合に限り、翻訳対象として宣言してください。ハンドラーの動作については Markdoc、ファイル用のオプション名については CLI の設定を参照してください。文書 API のオプションでは、異なるスキーマを使用します。
画面表示用カタログはロケールごとに用意してください。他のサイトジェネレーターでの構成については、静的コンテンツを参照してください。
原文のホームページをロケール別ルートで描画する #
src/content/en/pages/home.mdoc の YAML フロントマターにタイトルと説明を記述し、その後に記事本文を続けます。src/content/en/ui.json には、ナビゲーションラベル用の {"home": "Home"} を追加してください。@markdoc/markdoc と yaml がまだプロジェクトの依存関係に含まれていない場合は、インストールします。
この最小構成の src/app/[lang]/page.tsx は、原文と翻訳先のホームページを同じ処理で読み込みます。現在の App Router が採用している、プロミスベースのルートパラメーターを使用します。
import { readFile } from "node:fs/promises";
import path from "node:path";
import React from "react";
import Markdoc from "@markdoc/markdoc";
import { parse as parseYaml } from "yaml";
import { notFound } from "next/navigation";
export const runtime = "nodejs";
export default async function Page({
params,
}: {
params: Promise<{ lang: string }>;
}) {
const { lang } = await params;
if (lang !== "en" && lang !== "es") notFound();
const root = path.join(process.cwd(), "src/content", lang);
let rawDocument: string;
let rawUi: string;
try {
[rawDocument, rawUi] = await Promise.all([
readFile(path.join(root, "pages/home.mdoc"), "utf8"),
readFile(path.join(root, "ui.json"), "utf8"),
]);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") notFound();
throw error;
}
const ast = Markdoc.parse(rawDocument);
const errors = Markdoc.validate(ast);
if (errors.some(({ error }) => ["error", "critical"].includes(error.level))) {
throw new Error("Invalid Markdoc document");
}
const metadata = parseYaml(ast.attributes.frontmatter ?? "");
const ui = JSON.parse(rawUi);
if (typeof metadata?.title !== "string" || typeof ui.home !== "string") {
throw new Error("Missing homepage title or navigation label");
}
const tree = Markdoc.transform(ast);
return (
<main lang={lang}>
<nav><a href={`/${lang}`}>{ui.home}</a></nav>
<h1>{metadata.title}</h1>
{Markdoc.renderers.react(tree, React)}
</main>
);
}まず /en を開いてください。この例では、標準の Markdoc ノードを使用しています。カスタムタグを使うサイトでは、そのサイトの実際の設定を Markdoc.validate と Markdoc.transform の両方に渡し、名前付きの React コンポーネントを Markdoc.renderers.react に渡してください。必要な変数も明示的に渡します。翻訳ハンドラーはアノテーションを保持しますが、サイトのタグスキーマを提供するものではありません。
同じ検証付きローダーを、メタデータの生成や他のルートにも展開してください。文書のスラッグが動的な場合は、既知のコンテンツ一覧から対応する項目を特定してから、パスを読み込みます。Node のファイルシステムを使うローダーでは、デプロイ成果物にコンテンツファイルを含める必要があります。本番用ビルドに含まれていることを確認してください。ファイルシステムにアクセスできないエッジ環境にデプロイする場合は、別のストレージ読み込み処理が必要です。
ロケールの決定処理とナビゲーションを揃える #
ロケールを含まないルートでは、アプリケーションで明示された優先設定を使うか、Accept-Language に基づいて対応ロケールを決定してください。優先度の重みと地域タグを解析し、パスの残りの部分を保持したまま、対応する [lang] ルートへリダイレクトします。
すでに対応ロケールを含むルート、API リクエスト、Next.js の内部アセット、静的ファイルはリダイレクトしないでください。マッチ条件が広すぎると、ループが発生したり、画像リクエストが文書ルートにリダイレクトされたりすることがあります。インストール済みの Next.js のルーティングインターセプト API で利用できる除外設定を適用してください。以前のプロジェクトではミドルウェアを使いますが、新しいバージョンでは、名称変更後のプロキシ規約を使う場合があります。古いファイル名をすべての環境に通用する手順として流用せず、インストール済みのバージョンに合わせて動作とテストを整えてください。
内部リンクと別言語へのリンクは、既知のルートの対応関係に基づいて作成してください。言語切り替えにリンクを表示する前に、各リンク先が存在することを確認します。見出しを翻訳すると、生成される識別子も変わることがあるため、見出しへのフラグメントリンクも確認してください。
文書が存在するルートだけを生成する #
静的生成では、実際のコンテンツ一覧から、対応するロケールとスラッグの組み合わせを列挙してください。それらをプロジェクトの generateStaticParams の処理に組み込み、生成されたルートを確認します。動的に読み込む場合も、リクエスト時に同じ一覧を確認し、ファイルがない場合の処理を明示的に実装してください。翻訳が存在するものと仮定して、ロケール一覧だけからすべての翻訳先ルートを生成しないでください。
不足している翻訳先ファイルを lingo push --backfill-missing --wait で翻訳します。完了後、src/content/es/pages/home.mdoc と src/content/es/ui.json が存在することを確認し、同じローダーを通して /es を開いてください。翻訳されたタイトル、説明、本文、リンク、コードフェンス、カスタムタグの構造を確認します。コード例と動作を制御する属性は、原文の意味と値を保持している必要があります。
ローカルで修正した翻訳を、内容の差異に基づく保護の対象にする場合は、--wait を付けずに送信し、取得前に lingo pull --dry-run を確認してください。完了を待って直接書き戻す方法には、この確認段階がありません。レビュー済みの翻訳を保持するの手順に従ってください。
翻訳を定期実行する前にページを検証する #
翻訳先ロケールのルートを直接開き、その後、サイト内のナビゲーションからもアクセスしてください。見出し、画面の共通部分、メタデータ、言語切り替えが、すべて意図したロケールになっていることを確認します。カスタムコンポーネントとコード例を確認し、内部リンクと見出しへのフラグメントリンクもたどってください。翻訳されたファイルに対して、プロジェクトの既存の Next.js ビルドと Markdoc の検証を実行します。
原文、承認済みの翻訳、設定、CLI の Lockfile はまとめて管理してください。その後の原文の変更には、通常の lingo push --wait ワークフローを使います。ページが正常に動作したら、マネージドの GitHub 翻訳か、書き戻す内容をレビューできる ランナーの実行手順を選んでください。そのサイクルには、コンテンツローダーの検証と Next.js のビルドも含めてください。lingo check だけでは、文書がすべて揃っていることや、カスタムタグが正しく描画されることは確認できません。