# General Translation React SDKs (gt-react, gt-next): t
URL: https://generaltranslation.com/ja/docs/react/reference/functions/t-function.mdx
---

title: t
description: General Translation の `gt-react` で、モジュールスコープで文字列を同期的に翻訳します。t の API リファレンス。

---

`t` 関数は、クライアントサイドの `gt-react` アプリ向けの、同期・モジュールレベルの文字列翻訳関数です。[`useGT`](/docs/react/reference/hooks/use-gt) (React context が必要) や [`msg`](/docs/react/reference/functions/msg) (後で解決できるよう文字列をエンコードする) とは異なり、`t` は翻訳済みの文字列を直接返し、React コンポーネントの外を含め、ブラウザーコード内のどこからでも呼び出せます。

*`gt-react` と `gt-tanstack-start` で利用できます。例では `gt-react` から import しています。TanStack Start の場合は `gt-tanstack-start` から import してください。*

*注意: `gt-next` と `gt-react-native` からは export されません。`gt-next` では、同期コンポーネントでは [`useGT`](/docs/react/reference/hooks/use-gt) を、非同期の App Router コンポーネントでは [`getGT`](/docs/react/nextjs/reference/functions/get-gt) を使用してください。*

## 概要 [#overview]

`gt-react` から `t` をインポートし、文字列を引数にして呼び出します。

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

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

タグ付きテンプレートリテラルとしても使用できます:

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

const greeting = t`Hello, ${name}!`;
```

*注: `t` は、[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) で設定されたクライアントキャッシュから翻訳を取得します。モジュールスコープで `t` を呼び出すモジュールより前に、初期化が実行されていることを確認してください。server-rendered アプリでモジュールスコープから `t` を呼び出すことは禁止されています。開発時には例外がスローされ、Production ではエラーがログに記録されてデフォルトロケールの値にフォールバックします。*

## 仕組み [#how-it-works]

* **同期的なモジュールスコープでの翻訳。** アクティブなロケールの翻訳が読み込まれると、`t` はそれをオーバーヘッドなしで同期的に参照します。React context を使わないため、コンポーネント内だけでなく、モジュールスコープ (定数、ルートテーブル) でも使えます。
* **ロード時に解決されます。** 翻訳はモジュールの評価時に解決されるため、**ロケールを切り替えるにはページ全体の再読み込みが必要です**。新しいロケールを反映するには、ブラウザがモジュールを再実行する必要があります。このパターンは クライアントサイド アプリでのみ機能します。
* **変数は翻訳されません。** 補間値は翻訳済みの string に挿入されますが、それ自体は翻訳されません。
* **サーバーでの挙動。** レンダリング戦略が `server-render` の場合、つまりリクエスト時の condition store が初期化される前に、モジュールスコープで `t` を呼び出すことは禁止されています。開発環境ではエラーがスローされ、本番環境ではエラーがログに記録されて `defaultLocale` の値にフォールバックします。server-side で翻訳する場合は、[`useGT`](/docs/react/reference/hooks/use-gt) のような context ベースの hooks を使用してください。

## タグ付きテンプレートリテラル [#tagged-template]

`t` は、より自然な構文で記述できるタグ付きテンプレートとして使用できます。以下は同等です。

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

t('Hello, {name}!', { name: 'Alice' });
t`Hello, ${name}!`;
```

タグ付き形式では、変数がテンプレートから直接補間されるため、ICU 形式のプレースホルダーやオプションオブジェクトは必要ありません。

### グローバル登録 [#macros]

すべてのファイルで `t` をインポートする代わりに、アプリのエントリポイントで `macros` エントリを一度だけインポートして、グローバルに登録します:

```tsx
import 'gt-react/macros';
```

これにより `globalThis.t` が設定され、明示的に import しなくても tagged template をどこでも使えるようになります。

```tsx
// インポート不要
const labels = {
  save: t`Save`,
  cancel: t`Cancel`,
};
```

## パラメーター [#parameters]

| パラメーター                | 説明            | 型                      | 任意  | デフォルト |
| --------------------- | ------------- | ---------------------- | --- | ----- |
| [`message`](#message) | 翻訳する文字列。      | `string`               | いいえ | —     |
| [`options`](#options) | 補間変数と翻訳オプション。 | `GTTranslationOptions` | はい  | —     |

### `message` [#message]

**型** `string` · **必須**

翻訳する文字列です。tagged template として使用する場合は、代わりにテンプレート文字列を指定します。

### `options` [#options]

**型** `GTTranslationOptions` · **任意**

`$context` や `$id` などの、補間に使用する変数やオプションです。[`InlineTranslationOptions`](/docs/react/reference/types/inline-translation-options) を参照してください。

## 戻り値 [#returns]

**型** `string`

アクティブなロケールに対応する翻訳済みの文字列。翻訳がない場合はソース文字列。

## 例 [#examples]

```tsx title="constants.ts"
import { t } from 'gt-react';

export const ERROR_MESSAGES = {
  notFound: t('Page not found'),
  unauthorized: t('You do not have permission to view this page'),
  serverError: t('Something went wrong. Please try again later.'),
};
```

```tsx title="routes.ts"
import { t } from 'gt-react';

export const routes = [
  { path: '/', label: t('Home') },
  { path: '/dashboard', label: t('Dashboard') },
  { path: '/settings', label: t('Settings') },
];
```

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

const message = t('Hello, {name}!', { name: 'Alice' });
// 変数の値は挿入されるだけで、翻訳されません。
```

## メモ [#notes]

* `t` は同期的で、モジュールスコープで呼び出せます。React context は使用しません。
* ロケールの切り替えには、ページ全体の再読み込みが必要です。
* コンポーネント内の文字列を翻訳するには [`useGT`](/docs/react/reference/hooks/use-gt) を使用します。後で解決できるように文字列をエンコードするには [`msg`](/docs/react/reference/functions/msg) を使用します。