本文へスキップ
本文へスキップ

ドキュメント / スタートガイド / クイックスタート

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

React クイックスタート

React アプリの i18next ロケールファイルを verbatra で翻訳します。インストールから最初のドイツ語の文字列が画面に出るまでを説明します。

このページを終えると、React アプリに、verbatra が locales/en.json から翻訳したドイツ語の文字列が表示されます。以降の実行では、ロックファイルのおかげで変更された分だけが翻訳されます。必要なものは、Node.js ^22.22.0 || >=24、React プロジェクト、10 分ほどの時間です。最初の 4 つの手順には、アカウントも API キーも必要ありません。

すでにロケールファイルとコーディングエージェントがある場合は、代わりに AI エージェントで verbatra をセットアップするのプロンプトをエージェントに渡します。エージェントはプロジェクトにあるファイルに合わせて作業し、費用が発生する前に止まります。

手順

CLI をインストールする

npm install --save-dev @verbatra/cli

verbatra は開発用のツールで、アプリに同梱されることはありません。以下のコマンドは npx を使います。pnpm、yarn、bun を使う場合は、代わりに pnpm verbatra、yarn verbatra、bun run verbatra を実行します。

ソースロケールファイルを追加する

locales/en.json がすでにある場合は、この手順を飛ばします。ない場合は、文字列を 2 つ入れて作成します。そのうち 1 つにはプレースホルダーを含めます。

locales/en.json
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}

設定ファイルを作成する

npx @verbatra/cli init --format i18next-json --provider gemini --yes

--format の i18next-json は、react-i18next のファイルフォーマットです。init はロケールファイルを探し、まだない場合はパターン locales/{locale}.json を書き込みます。--yes を付けると、init が検出した内容をそのまま採用し、質問を表示しません。作成された verbatra.config.ts は en から de へ翻訳します。言語を増やすには、targetLocales にコードを追加します。

API キーなしで実行をプレビューする

npx @verbatra/cli translate --dry-run
出力
verbatra: 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_KEY= の後ろに API キーを貼り付けます。まだ API キーがない場合、Gemini には無料枠があります。Google AI Studio で作成します。ほかのプロバイダーとその環境変数は、プロバイダーにあります。

npx @verbatra/cli translate

verbatra は 2 つの文字列を Gemini に送り、すべてのプレースホルダーが残っているかをチェックして、locales/de.json を書き込みます。表現はモデルによって変わります。たとえば次のようになります。

locales/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 sync

check はプロバイダーを呼び出さず、ロケールが同期していなければ終了コード 1 で終了します。そのため、pull request をゲートで止められます。

アプリでロケールを読み込む

react-i18next を追加します。

npm install i18next react-i18next

次に、2 つのファイルを読み込み、あいさつを表示します。

src/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import de from "../locales/de.json";
import en from "../locales/en.json";

i18n.use(initReactI18next).init({
  lng: "de",
  fallbackLng: "en",
  resources: { en: { translation: en }, de: { translation: de } },
});
src/Greeting.tsx
import { useTranslation } from "react-i18next";

export function Greeting() {
  const { t } = useTranslation();
  return <p>{t("greeting", { name: "Ada" })}</p>;
}
src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { Greeting } from "./Greeting";
import "./i18n";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <Greeting />
  </StrictMode>,
);

アプリを起動すると、あいさつが 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 のユーザープロファイルに追加することもできます。どちらか一方の方法だけを使い、両方は使わないでください。

VS Code に追加

次のステップ

GitHub で編集

このページの内容