CLI

Better Translate にロケールファイルの構築と更新を任せたい場合は、@better-translate/cli を使用してください。

ランタイムパッケージの利用に CLI は必須ではありません。任意です。

1. パッケージをインストールする

npm install -D @better-translate/cli

CLI はプロバイダー非依存です。アプリ側で AI SDK のプロバイダーパッケージを直接インストールし、設定します。

2. ソースロケールファイルを作成する

src/messages/en.json を作成します：

1{2  "home": {3    "title": "Hello",4    "description": "Welcome to the app"5  }6}

空の {} から始めて、bt extract に入力してもらうこともできます。

3. CLI 設定を作成する

better-translate.config.ts を作成します：

1import { createOllama } from "ollama-ai-provider-v2";2import { defineConfig } from "@better-translate/cli/config";34const ollama = createOllama({5  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/api",6});78export default defineConfig({9  sourceLocale: "en",10  locales: ["es", "fr"],11  model: ollama("qwen3:4b"),12  messages: {13    entry: "./src/messages/en.json",14  },15});

Ollama を使う場合は ollama-ai-provider-v2 をインストールしてください。ホスト型プロバイダーを使う場合は、@ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/moonshotai など、該当パッケージをインストールします。

デフォルトの Ollama API URL はローカルです：http://localhost:11434/api

OpenAI、Anthropic、Moonshot AI などのホスト型プロバイダーでも同様に動作します。CLI はプロバイダーヘルパーを同梱しなくなりました。

4. コード内の文字列をマークする

翻訳キーを手で命名する代わりに、ソース文言をそのまま書き、{ bt: true } を付けます：

1import { t } from "@better-translate/core";23export function navLabel() {4  return t("Home", { bt: true });5}

ランタイムでは { bt: true } は文字列をそのまま返します。次の extract で CLI がこれらの呼び出しを適切なキーに置き換えます。

params など他のオプションも渡せます。extract 後も保持されます：

1// あなたが書く:2t("Hello world", { bt: true })3t("Hello {name}", { bt: true, params: { name: "" } })45// bt extract がファイルを書き換えた後:6t("components.nav.helloWorld")7t("components.nav.helloName", { params: { name: "" } })

キーの名前空間はソースファイルのパスから決まります（components/nav.tsx → components.nav）。bt: true は書き換え時に必ず削除されます。

5. ソースキーを抽出する

npx bt extract

t(..., { bt: true }) 呼び出しをスキャンし、不足しているキーをソースロケールファイルに追加し、呼び出しをプレーンな厳密キーに書き換えます。

CLI はプロジェクトルートの better-translate.config.ts を自動で見つけます。設定ファイルが別の場所にある場合のみ --config フラグが必要です。

6. ジェネレーターを実行する

npx bt generate

ソースファイルの隣にターゲットロケールファイルを作成します。

markdown.rootDir が有効で、翻訳済みの .md や .mdx の作成・上書きが発生する場合、CLI は変更前に確認を求めます。プロンプトをスキップするには --yes または -y を使います：

npx bt generate --yes

翻訳済み Markdown を書き込む必要がある非対話実行では --yes が必須です。

7. 未使用キーを削除する

npx bt purge

コードベース内の t("...") 呼び出しで参照されなくなった翻訳キーをスキャンし、すべてのロケールファイルから削除します。削除前に各キーごとに確認を求めます：

1? Purge unused key "home.oldTitle"? (y/N) y2? Purge unused key "sidebar.legacy"? (y/N) n

y で全ロケールから削除、n（または Enter）で保持します。

プロンプトなしで未使用キーを一括削除するには：

npx bt purge --yes

書き込みせずに削除対象をプレビューするには：

npx bt purge --dry-run

動的キー: コードで t(`section.${id}`) のような動的キーを使う場合、CLI は静的に解決できません。警告を出し、検出されたプレフィックスを共有するキーを保護するか、キーを unsafe とマークしてスキップし、まだ使われている可能性のあるものを黙って削除しません。

8. 生成ファイルをアプリで使う

ファイルができたら、手書きのロケールファイルと同様に @better-translate/core の設定へ import します。

Markdown

ローカライズされた Markdown の生成も必要なら、markdown.rootDir オプションを追加します：

1import { createOllama } from "ollama-ai-provider-v2";2import { defineConfig } from "@better-translate/cli/config";34const ollama = createOllama({5  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/api",6});78export default defineConfig({9  sourceLocale: "en",10  locales: ["es", "fr"],11  model: ollama("qwen3:4b"),12  messages: {13    entry: "./src/messages/en.json",14  },15  markdown: {16    rootDir: "./content/docs",17  },18});

コマンドリファレンス

例

動作する完全な例は GitHub リポジトリ にあります：

• nextjs-example
• react-vite-example
• core-elysia-example