概要

gt-react で、ブラウザ上でモジュールレベルの文字列翻訳を同期的に行える t() 関数が新たにエクスポートされるようになりました。

これまで gt-react で文字列を翻訳するには、useGT のような React のReact コンテキストベースのフックを使う必要がありました。フックはコンポーネント内では有効ですが、よくあるケースであるモジュールレベルでの文字列翻訳、つまり React コンポーネントの外、レンダリング前、通常のユーティリティファイル内での翻訳には対応できません。

t() はそのギャップを埋めます。これは同期関数で、ブラウザコード内のどこからでも呼び出せます。

import { t } from 'gt-react/browser';

const greeting = t('Hello, world!');

フックも非同期処理もコンポーネントツリーも不要です。

このアプローチを採る理由

このPRの狙いは、翻訳の仕組みをReact コンテキストベースのアプローチから切り離せないか試すことにあります。コンポーネントツリーの外で動作することで、t() はより柔軟なパターン、特にモジュールレベルでの翻訳を可能にします。文字列はレンダリングする場所ではなく、定義した場所で翻訳できます。

ただし、これにはトレードオフがあります。

• クライアントサイド専用です。 t() が動作するのはクライアントサイドのReactアプリケーションだけです。アプリのレンダリング前に翻訳を読み込むため、ブラウザでのモジュール実行に依存します。
• 言語を切り替えるにはページ全体の再読み込みが必要です。 翻訳はモジュールの読み込み時に確定するため、ロケールを切り替えるにはモジュールを再実行する必要があります。つまり、ページ全体の再読み込みが発生します。セッションの途中で言語をその場で切り替えることはできません。

一方で、開発体験は大きく向上します。文字列をフックでラップしたり、コンポーネントレベルで受け渡したり、非同期境界を扱ったりする必要はありません。必要なのは関数呼び出しだけです。

既存のReact コンテキストベースのアプローチ (useGT、<T> など) がなくなるわけではありません。これは、こうしたトレードオフを許容できるプロジェクト向けの追加の選択肢です。

仕組み

t() は、あらかじめ読み込まれた翻訳データから同期的に翻訳を解決します。これらの翻訳データは、新しい非同期セットアップ関数 bootstrap() によって初期化され、アプリがレンダリングされる前に現在のロケール向けの翻訳がすべて読み込まれます。

最初に bootstrap() を実行するよう、アプリのエントリーポイントを変更する必要があります。通常は main.tsx ですが、index.html でエントリーポイントを変更することもできます。

// bootstrap.tsx (新しいエントリーポイント)
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';

async function getTranslations(locale: string) {
  return import(`./_gt/${locale}.json`);
}

await bootstrap({
  ...gtConfig,
  getTranslations,
});

await import('./main.tsx');

getTranslations 関数は非同期です。最初に翻訳を読み込み、その後で React アプリをインポートして実行します。これにより、t() をモジュールレベルで使えます。つまり、どのモジュールから t() を呼び出す時点でも、翻訳はすでに利用可能です。

これはクライアントサイドの React アプリでのみ動作します。ブラウザで読み込むと、モジュールレベルのコードが再実行されるためです。また、翻訳済みの内容を切り替えるにはモジュールを再実行する必要があるため、ロケールを切り替えるにはページ全体の再読み込みが必要です。

変数

t() は、msg() と同様に変数の補間をサポートします。

import { t } from 'gt-react/browser';

t('Hello, {name}!', { name: 'John' });  // → "Hola, John!"

適している場面

t() は、React コンポーネントツリーの外で翻訳が必要な場合に適しています。たとえば、定数ファイル、ユーティリティ関数、設定オブジェクト、ルーター定義、またはブラウザでモジュールスコープとして実行されるものです。

留意点:

• これはまだ gt-react システムの他の部分とは統合されていません。 上で説明したブートストラップ設定を行う必要があります。独立したアプローチです。
• クライアントサイド専用です。 サーバーサイドでの翻訳には、useGT のような React コンテキストベースのフックを使用してください。

設計上の注意

t() はブラウザ専用です。サーバー上で呼び出されると (window が未定義の環境) 、警告を出力し、元の文字列にフォールバックします。これは意図的な動作です。サーバー側で翻訳する場合は、既存の React コンテキストベースのフックを使用してください。

API リファレンス

パラメータ、戻り値の型、セットアップの詳細については、完全な t() API リファレンスを参照してください。