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

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 のセットアップ