GTProvider
<GTProvider> コンポーネントの APIリファレンス
概要
<GTProvider> コンポーネントは、その children に General Translation (GT) のコンテキストを提供し、翻訳済みのコンテンツにアクセスできるようにします。
アプリケーションでクライアントサイドの翻訳を行う場合には必須です。
使うタイミング
- クライアント側で翻訳を有効にするため、アプリケーション全体を
<GTProvider>でラップします。 - dictionaries を扱う場合は、必要に応じて
idを指定してクライアントに送信する dictionary データを絞り込み、大規模な dictionaries のパフォーマンスを最適化します。 <GTProvider>コンポーネントは、インラインの<T>と dictionaries の両方で使用します。
リファレンス
Props
Prop
Type
説明
| Prop | 説明 |
|---|---|
children | クライアント側で翻訳を実行したり翻訳情報にアクセスする必要がある任意のコンポーネント、またはそれらの親コンポーネント。<T>、useGT、その他の翻訳ユーティリティを使用するコンポーネントを含めてください。 |
projectId? | General Translation のクラウドサービスで必要となるプロジェクトの ID。 |
id? | クライアントへ送信するデータを絞り込むための、入れ子になった dictionary の ID。大規模で dictionary が肥大化しているプロジェクトで有用です。 |
dictionary? | プロジェクトの翻訳用 dictionary。 |
locales? | プロジェクトで承認された対応ロケールの一覧。 |
defaultLocale? | 他のロケールが見つからない場合に使用する既定のロケール。 |
locale? | 既に設定済みの場合の現在のロケール。 |
cacheUrl? | 翻訳を取得するためのキャッシュサービスの URL。 |
runtimeUrl? | 翻訳を取得するためのランタイムサービスの URL。 |
renderSettings? | 翻訳のレンダリング設定。 |
_versionId? | 翻訳取得に使用するバージョン ID。 |
devApiKey? | 開発環境用の APIキー。 |
metadata? | コンテキストに渡す追加のメタデータ。 |
返り値
このコンポーネントに渡された children を含む React.JSX.Element | undefined を返します。
例
基本的な使い方
アプリケーション全体を <GTProvider> で包んで、翻訳機能を有効化します。
翻訳を有効にするために、対応ロケールの一覧 を必ず設定してください。
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import { GTProvider } from "gt-react";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider locales={['es', 'fr']}> // スペイン語とフランス語を有効にする // [!code highlight]
<App />
</GTProvider> // [!code highlight]
</StrictMode>
);Dictionaries
<GTProvider> コンポーネントに dictionary を渡し、その後は useTranslations フックで取得することもできます。
import dictionary from "./dictionary.js";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
<App />
</GTProvider>
</StrictMode>
);dictionaries の使い方について詳しくは、このガイドをご覧ください。
設定の追加
<GTProvider> コンポーネントに直接 props を渡したくない場合は、設定ファイルを作成してコンポーネントに渡すことができます。
さらに、gtx-cli translate コマンド とも直接統合できるため、パラメータとして locales などを手動で指定する必要はありません。
{
"projectId": "your-project-id",
"locales": ["es", "fr"],
"defaultLocale": "en-US",
"_versionId": "translation-version-id" // 以前の翻訳にロールバックできるようにする（CLI により自動生成）
}あとはこれをそのまま <GTProvider> コンポーネントに渡すだけです。
import config from "../gt.config.json";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider {...config}> // [!code highlight]
<App />
</GTProvider>
</StrictMode>
);カスタム翻訳ローダー
loadTranslations プロップを使うと、任意のソースから翻訳を読み込めます。
カスタム API など、既定とは異なるソースから翻訳を読み込みたい場合に便利です。
import loadTranslations from "./loadTranslations";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<GTProvider locales={['es', 'fr']} loadTranslations={loadTranslations}> // [!code highlight]
<App />
</GTProvider>
</StrictMode>
);レンダリング設定
レンダリング設定は、翻訳の読み込み時の挙動を制御します。
フィールドは timeout と method の2つです。
timeoutは、フォールバックを表示する前に翻訳の読み込みを待つ時間（ミリ秒）（既定値:8000ms）です。methodは、翻訳の読み込みに使用する方式（"skeleton"、"replace"、"default"）です。
<GTProvider renderSettings={{ method: "skeleton", timeout: 1000 }}>
<App />
</GTProvider>各レンダー設定は、読み込み時の動作が異なります:
"skeleton" は、翻訳が読み込まれるまで null を返します。
"replace" は、翻訳が読み込まれるまで fallback コンテンツを返します。
"default" は、翻訳が読み込まれるまで null を返します。ただし、fallback locale の言語が現在の locale と同じ場合（例: en-US と en-GB）は例外です。
この場合は、翻訳が読み込まれるまで即座に fallback コンテンツを返します。
注意事項
<GTProvider>は、すべての<T>コンポーネント とその他の翻訳関連の関数を必ず包む（ラップする）必要があります。詳しくはこちらをご覧ください。
次のステップ
- テキストやコンポーネントを翻訳するための
<T>コンポーネントについてさらに詳しく学びましょう。
このガイドはどうでしたか？