Core

@better-translate/core はあらゆる TypeScript プロジェクトで動作します。フレームワークの依存も、ランタイムの要件もありません。Next.js、Astro、React、Bun、Node.js、スクリプト、またはその他の TypeScript 環境であっても、同じ設定と同じ API を使用できます。

アダプターは、フレームワーク固有のヘルパー（ロケール対応ルーティング、React コンテキスト、リクエストごとのヘルパーなど）を追加するコアの拡張機能です。ただし、すべては同じコアの上に構築されています。

コアを直接使用する場合

フレームワーク固有のヘルパーが不要な場合は、アダプターなしでコアを使用します。これには、サーバー、API、スクリプト、共有ライブラリ、またはセットアップにアダプターが存在しない TypeScript 環境が含まれます。

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

npm install @better-translate/core

2. 翻訳ファイルを1つ作成する

src/i18n.ts を作成します：

1import { configureTranslations } from "@better-translate/core";23const en = {4  home: {5    title: "Hello",6    description: "This is the English version.",7  },8} as const;910const es = {11  home: {12    title: "Hola",13    description: "Esta es la version en espanol.",14  },15} as const;1617export const translator = await configureTranslations({18  availableLocales: ["en", "es"] as const,19  defaultLocale: "en",20  fallbackLocale: "en",21  messages: { en, es },22});

トップレベル await をサポートしない TypeScript 環境（たとえば CommonJS）では、この初期化を async な起動関数の中に移動して、解決済みの translator をそこから公開してください。

3. どこでも翻訳機能を使用する

1import { translator } from "./i18n";23translator.t("home.title"); // "Hello"4translator.t("home.title", { locale: "es" }); // "Hola"5translator.t("home.description", { locale: "es" });

4. 後で別のロケールを追加する

1const fr = {2  home: {3    title: "Bonjour",4    description: "Ceci est la version francaise.",5  },6} as const;78export const translator = await configureTranslations({9  availableLocales: ["en", "es", "fr"] as const,10  defaultLocale: "en",11  fallbackLocale: "en",12  messages: { en, es, fr },13});

フォールバック動作

アクティブなロケールにキーが存在しない場合、better-translate はフォールバックロケールを試します。フォールバックにも存在しない場合、キー文字列そのものを返します。

→ ロケール値が見つからない → フォールバックロケール値
→ フォールバック値も見つからない → キー文字列

非同期ローダー

プリロードしたくない言語のロケールローダーを登録します。ロードされたロケールは、最初の成功した読み込み後にキャッシュされます。

1const translator = await configureTranslations({2  availableLocales: ["en", "fr"] as const,3  defaultLocale: "en",4  messages: { en },5  loaders: {6    fr: async () => import("./messages/fr").then((m) => m.default),7  },8});910// 必要に応じて fr をロードし、キャッシュする11await translator.loadLocale("fr");

5. CLI で文字列を自動抽出する

手動でキーを命名する代わりに、{ bt: true } で文字列をマークし、CLI に自動的に抽出・キー化させます：

1import { t } from "@better-translate/core";23// ソース文字列を直接記述 — CLI が適切なキーに変換します4t("Hello world", { bt: true });

npx bt extract を実行して、文字列をソースロケールファイルに同期し、呼び出しを適切なキーに書き換えます。完全なセットアップについては CLI ドキュメントを参照してください。

次のステップ

例

core-elysia-example — シンプルな TypeScript/Node.js セットアップ