料金ブログダッシュボード
Components

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 のクラウドサービスに必要な projectId。
id?クライアントに送信するデータを絞り込むための入れ子の dictionary の id。大規模で dictionary が膨大なプロジェクトで有用です。
dictionary?プロジェクトの翻訳用 dictionary。
locales?プロジェクトで承認された対応ロケールの一覧。
defaultLocale?他にロケールが見つからない場合に使用する既定のロケール。
locale?すでに設定されている場合の現在のロケール。
cacheUrl?翻訳を取得するためのキャッシュサービスのURL。
runtimeUrl?翻訳を取得するためのランタイムサービスのURL。
renderSettings?翻訳のレンダリング設定。
_versionId?翻訳を取得するための versionId。
devApiKey?開発環境向けのAPIキー。
metadata?コンテキストに渡す追加のメタデータ。

返り値

このコンポーネントに渡された children を含む React.JSX.Element | undefined。

例

基本的な使い方

アプリに翻訳機能を追加するには、アプリケーション全体を <GTProvider> でラップします。 翻訳を有効にするために、対応ロケールの一覧 を必ず追加してください。

index.js
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 フックから参照することもできます。

index.js
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 コマンド とも連携しているため、対応ロケールなどをパラメーターで手動指定する必要はありません。

gt.config.json
{
  "projectId": "your-project-id",
  "locales": ["es", "fr"],
  "defaultLocale": "en-US",
  "_versionId": "translation-version-id" // 以前の翻訳へロールバックできます（CLI により自動生成）
}

あとはこれを <GTProvider> コンポーネントに渡すだけです。

index.js
import config from "../gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

カスタム翻訳ローダー

loadTranslations プロップを使うと、任意のソースから翻訳を読み込めます。 たとえばカスタム API など、別のソースから翻訳を取得する必要がある場合に便利です。

index.js
import loadTranslations from "./loadTranslations";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} loadTranslations={loadTranslations}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

レンダリング設定

レンダリング設定は、翻訳の読み込み挙動を制御します。 フィールドは2つあります：timeout と method。

  • timeout は、フォールバックを表示する前に翻訳の読み込みを待機する時間（ミリ秒）です（既定値：8000ms）。
  • method は、翻訳の読み込みに使用する方式です（"skeleton"、"replace"、または "default"）。
index.js
<GTProvider renderSettings={{ method: "skeleton", timeout: 1000 }}>
  <App />
</GTProvider>

各レンダー設定は読み込み時の挙動が異なります: "skeleton" は翻訳が読み込まれるまで null を返します。 "replace" は翻訳が読み込まれるまでフォールバックコンテンツを返します。 "default" は、フォールバックの locale が現在の locale と同じ言語（例: en-US と en-GB）でない限り、翻訳が読み込まれるまで null を返します。 この場合は、翻訳が読み込まれるまで直ちにフォールバックコンテンツを返します。

注意事項

  • <GTProvider> は、すべての <T> コンポーネントおよびその他の翻訳関連の関数を必ずラップする必要があります。詳しくはこちらをご覧ください。

次のステップ

このガイドはいかがですか?

T

<T> コンポーネントのAPIリファレンス

Var

<Var> コンポーネントの APIリファレンス

このページについて

概要
いつ使うか
リファレンス
Props
説明
返り値
例
基本的な使い方
Dictionaries
設定の追加
カスタム翻訳ローダー
レンダリング設定
注意事項
次のステップ