# General Translation Changelog: gt-react 10.12.0: t() を使用したモジュールレベルでの翻訳
URL: https://generaltranslation.com/ja/blog/gt-react_v10_12_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Ernest McCarter
Published: 2026-03-16

## 概要

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

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

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

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

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

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

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

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

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

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

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

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

## 仕組み

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

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

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

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

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

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

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

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

<Callout>
  **Experimental:** この機能は現在、クライアントサイド専用の React アプリケーションでのみ利用できます。
</Callout>

## 変数

[`t()`](/docs/react/reference/functions/t-function) は、[`msg()`](/docs/react/reference/functions/msg) と同様に変数の補間をサポートします。

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

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

## 適している場面

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

留意点:

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

## 設計上の注意

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

***

## API リファレンス

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.