<T> コンポーネント

Next.js アプリで JSX コンテンツを国際化するための主要な手段が、<T> コンポーネントです。JSX 要素をラップし、ユーザーの locale に基づいて自動的に翻訳します。

クイックスタート

静的な JSX コンテンツは、<T> でラップするだけで変換できます：

import { T } from 'gt-next';

// 変更前
function Greeting() {
  return <p>こんにちは、世界！</p>;
}

// 変更後
function Greeting() {
  return <T><p>こんにちは、世界！</p></T>;
}

<T> 内の動的コンテンツには、Variable Components と Branching Components を使用してください。

基本的な使い方

<T> コンポーネントは、children として任意の JSX コンテンツを受け取ります。

// Simple text
<T>アプリへようこそ</T>

// HTML elements
<T><h1>ページのタイトル</h1></T>

// Complex nested JSX
<T>
  <div className="alert">
    <span>重要：</span>必ずよくお読みください。
  </div>
</T>

設定 options

コンテキストの追加

あいまいな用語に対して、翻訳時のコンテキストを提供します：

<T context="notification popup, not bread">
  トーストをクリックして閉じます
</T>

翻訳IDの設定

一貫性のある翻訳のために、明示的なIDを使用します:

<T id="welcome-message">
  おかえりなさい、ユーザーさん！
</T>

`<T>` を使用するタイミング

<T> は 静的コンテンツにのみ 使用してください：

// ✅ 静的コンテンツは動作します
<T><button>こちらをクリック</button></T>
<T><h1>当サイトへようこそ</h1></T>

// ❌ 動的コンテンツは動作しません
<T><p>{username} さん、こんにちは</p></T>
<T><p>きょうは {new Date()} です</p></T>

// ✅ 動的コンテンツには Variable コンポーネントを使用します
<T>
  <p><Var>{username}</Var> さん、こんにちは</p>
</T>

Variable コンポーネントと Branching コンポーネントは、動的コンテンツ向けに <T> 内で動作するよう設計されています。詳しくは、Variable Components および Branching Components のガイドをご覧ください。

例

シンプルなエレメント

// Basic text
<T>こんにちは、世界！</T>

// Button with text
<T><Button>送信</Button></T>

// Heading with styling
<T><h1 className="text-2xl font-bold">ようこそ</h1></T>

複合コンポーネント

// ナビゲーションメニュー
<T>
  <nav className="navbar">
    <a href="/about">会社情報</a>
    <a href="/contact">お問い合わせ</a>
  </nav>
</T>

// アラートメッセージ
<T>
  <div className="alert alert-warning">
    <AlertIcon className="w-5 h-5" />
    <span>セッションは5分後に期限切れになります</span>
  </div>
</T>

variables を使う

// 静的テキストと動的値の組み合わせ
<T>
  <p><Var>{user.name}</Var>さん、お帰りなさい！</p>
</T>

// 異なる種類の内容を含むフォーム
<T>
  <label>
    メールアドレス：<input type="email" placeholder="メールアドレスを入力してください" />
  </label>
</T>

Variable Components Guide で <Var> コンポーネントについてさらに詳しく学べます。

本番環境の設定

ビルドプロセス

ビルドパイプラインに翻訳を追加する:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

開発環境と本番環境での挙動

開発: Dev API key を使用すると、コンポーネントのレンダー時にオンデマンドで翻訳が実行されます。開発中は翻訳がリアルタイムに反映されます。
本番: すべての翻訳はビルド段階で事前生成され、アプリケーションの公開後に表示されます。

開発中のライブ翻訳を有効にするには、環境変数に開発用の APIキーを設定してください。Dashboard の API Keys で作成できます。

プライバシーに関する考慮事項

<T> コンポーネント内のコンテンツは、翻訳のために GT API に送信されます。機密データについては、Variable Components を使用し、機密情報はローカルに留めてください。

// 安全 — 機密データはローカルに保存されます
<T>
  お帰りなさい、<Var>{username}</Var>
</T>

よくある問題点

コンポーネントの境界

<T> は直下の children のみを翻訳し、他のコンポーネント内の内容は翻訳しません。

// ❌ 誤り - コンポーネント内のテキストは翻訳されません
function MyComponent() {
  return <p>これは翻訳されません</p>;
}

<T>
  <h1>これは翻訳されます</h1>
  <MyComponent /> {/* コンポーネント内のテキストは翻訳されません */}
</T>

// ✅ 正解 - 各コンポーネントを個別にラップします
function MyComponent() {
  return <T><p>これは翻訳されます</p></T>;
}

<T><h1>これは翻訳されます</h1></T>
<MyComponent />