ドキュメント / スタートガイド / クイックスタート
機械翻訳されたページ
Next.js クイックスタート
verbatra で Next.js アプリの next-intl ロケールファイルを翻訳します。インストールから最初のドイツ語の文字列が画面に表示されるまでを扱います。
このページを終えると、Next.js アプリに、verbatra が messages/en.json から翻訳したドイツ語の文字列が表示されます。以降の実行では、ロックファイルのおかげで変更された分だけが翻訳されます。必要なものは、Node.js ^22.22.0 || >=24、Next.js プロジェクト、10 分ほどの時間です。最初の 4 つの手順には、アカウントも API キーも必要ありません。
すでにロケールファイルとコーディングエージェントがある場合は、代わりに AI エージェントで verbatra をセットアップするのプロンプトをエージェントに渡します。エージェントはプロジェクトにあるファイルに合わせて作業し、費用が発生する前に止まります。
手順
CLI をインストールする
npm install --save-dev @verbatra/cliverbatra は開発用のツールで、アプリに同梱されることはありません。以下のコマンドは npx を使います。pnpm、yarn、bun を使う場合は、代わりに pnpm verbatra、yarn verbatra、bun run verbatra を実行します。
ソースロケールファイルを追加する
messages/en.json がすでにある場合は、この手順を飛ばします。ない場合は、文字列を 2 つ入れて作成します。そのうち 1 つにはプレースホルダーを含めます。
{
"greeting": "Hello, {name}!",
"cart": {
"empty": "Your cart is empty."
}
}設定ファイルを作成する
npx @verbatra/cli init --format next-intl-json --provider gemini --yes--format の next-intl-json は、next-intl のファイルフォーマットです。init はロケールファイルを探し、まだない場合はパターン messages/{locale}.json を書き込みます。--yes を付けると、init が検出した内容をそのまま採用し、質問を表示しません。作成された verbatra.config.ts は en から de へ翻訳します。言語を増やすには、targetLocales にコードを追加します。
API キーなしで実行をプレビューする
npx @verbatra/cli translate --dry-runverbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)ドライランはプロバイダーを生成しません。そのため API キーは不要で、費用はかからず、何も書き込まれません。
翻訳する
cp .env.example .env.env を開き、GEMINI_ の後ろに API キーを貼り付けます。まだ API キーがない場合、Gemini には無料枠があります。Google AI Studio で作成します。ほかのプロバイダーとその環境変数は、プロバイダーにあります。
npx @verbatra/cli translateverbatra は 2 つの文字列を Gemini に送り、すべてのプレースホルダーが残っているかをチェックして、messages/de.json を書き込みます。表現はモデルによって変わります。たとえば次のようになります。
{
"greeting": "Hallo, {name}!",
"cart": {
"empty": "Dein Warenkorb ist leer."
}
}すべてのロケールが同期していることを確認する
npx @verbatra/cli check[ok] checking the locales (0.0s)
verbatra check
de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in synccheck はプロバイダーを呼び出さず、ロケールが同期していなければ終了コード 1 で終了します。そのため、pull request をゲートで止められます。
アプリでロケールを読み込む
next-intl を追加します。
npm install next-intl次に、2 つのファイルを読み込み、あいさつを表示します。
import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";
const nextConfig: NextConfig = {};
export default createNextIntlPlugin()(nextConfig);// with a src/ folder: src/i18n/request.ts, importing ../../messages
import { getRequestConfig } from "next-intl/server";
export default getRequestConfig(async () => {
const locale = "de";
return {
locale,
messages: (await import(`../messages/${locale}.json`)).default,
};
});import { useTranslations } from "next-intl";
export default function Home() {
const t = useTranslations();
return <p>{t("greeting", { name: "Ada" })}</p>;
}アプリを起動すると、あいさつが Hallo, Ada! と表示されます。
ここで起きたこと
verbatra.lock.jsonが各ソース文字列のハッシュを記録します。そのため、次回の実行では新しい文字列と変更された文字列だけが送られます。ロックファイルと来歴を参照してください。- プレースホルダーが失われた結果は保留され、書き込まれません。翻訳の安全性を参照してください。
ロケールファイル、verbatra.lock.json、verbatra.provenance.json は、まとめてコミットします。
任意:コーディングエージェントを接続する
npx @verbatra/cli init --agent設定ファイルがすでにある場合、init --agent は変更を加えず、エージェント用のファイルだけを追加します。追加されるのは、AGENTS.md の verbatra のルール(指示ファイルが CLAUDE.md だけの場合は CLAUDE.md)と、検出した各コーディングエージェントのプロジェクト設定に登録する verbatra MCP サーバー(課金はオフ)です。どのエージェントにどのファイルを書き込むか、また --client でエージェントを自分で指定する方法は、コーディングエージェントを設定するにあります。--dry-run を付けると、ファイルを書き込まずに表示します。
CLI を使わずに、MCP サーバーだけを VS Code のユーザープロファイルに追加することもできます。どちらか一方の方法だけを使い、両方は使わないでください。
次のステップ
言語を追加する
ターゲットロケールを追加し、1 回の実行で埋めます。
CI で verbatra を実行する
ロケールがドリフトしたら pull request を失敗させます。
技術スタックを選ぶ
ほかのすべてのフレームワークのフォーマット ID とファイルのレイアウト。