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 } は文字列を変更せずに返します。CLI は次の抽出時にこれらの呼び出しを適切なキーに置き換えます。

params などの他のオプションも渡すことができます — これらは抽出後も保持されます：

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

翻訳されたマークダウンファイルを書き込む必要がある非対話型の実行では、--yes を渡す必要があります。

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

npx bt purge

これにより、コードベースで t("...") 呼び出しに参照されていない翻訳キーがスキャンされ、すべてのロケールファイルから削除されます。CLI は削除する前に各キーを個別に確認するよう求めます：

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 は静的に解析できません。警告を表示し、検出されたプレフィックスを共有するキーを保護するか、キーを安全でないとしてマークしてスキップします。まだ使用中かもしれないものを黙って削除することはありません。

8. アプリで生成されたファイルを使用する

ファイルが存在した後、手書きのロケールファイルと同じように @better-translate/core の設定にインポートしてください。

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});

コマンドリファレンス

Examples

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

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