<T> リファレンス

<T> コンポーネントと gt-next ライブラリについての詳細な解説です。

概要

この記事では、gt-nextライブラリの<T>コンポーネントの使用方法について詳しく説明します。必要に応じてこのページを自由にスキップしてください。以下の内容をカバーします：

<T>コンポーネントとは
デザインパターン
プロダクションでの考慮事項
いくつかの例
一般的な落とし穴

Variable ComponentsやBranching Componentsの使用方法をお探しの場合は、それぞれの記事を参照してください。

`<T>` コンポーネントとは何ですか？

<T> コンポーネントは、gt-next ライブラリでテキストとコンテンツを翻訳するための主要な方法です。テキストとJSX構造のインライン翻訳を可能にし、アプリケーション内の翻訳をより直接的に管理する方法を提供します。これは、翻訳コンテンツをより直接的に制御できるため、開発者にとってより便利な場合が多いです。

<T> コンポーネントは、静的テキスト、JSX構造、およびコンテキストに応じた翻訳をサポートします。翻訳が利用できない場合、アプリケーションのデフォルトのロケールでコンテンツを表示することで優雅にフォールバックします。

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

デザインパターン

このセクションでは、<T> コンポーネントで使用される一般的なデザインパターンについて詳しく説明します。これは、文字列の翻訳、事前のコンテンツ翻訳、プライバシーの懸念など、<T> コンポーネントに関連するが同様に重要なトピックにも触れます。

`<GTProvider>` で `<T>` コンポーネントをラップする

<T> は静的なテキストと JSX 構造を翻訳するために使用されます。クライアントサイドのコンポーネントの場合、<T> は必ず上位レベルで <GTProvider> でラップされている必要があります。私たちのアドバイスは、アプリケーションをルートレベルで <GTProvider> でラップして、このコンテキストを提供することです。

import { GTProvider } from 'gt-next';
import { getLocale } from "gt-next/server";
 
export default async function RootLayout({ children }) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider> // [!code highlight]
      </body>
    </html>
  );
}

例外: サーバーサイド `<T>` コンポーネント

サーバーサイドレンダリングの場合、<GTProvider> は <T> コンポーネントに対してオプションです。

import { GTProvider } from 'gt-next';
import { getLocale } from "gt-next/server";
 
export default function RootLayout({ children }) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <T> こんにちは、世界！ </T>  // [!code highlight]
        
        <GTProvider>{children}</GTProvider> // [!code highlight]
      </body>
    </html>
  );
}

`<T>` コンポーネント内の変数

変数コンポーネントは、<T> コンポーネント内で (1) 動的な値を表示するため、または (2) 翻訳されるべきでないコンテンツをマークするために使用できます。ユーザーの名前のようなものを考えてみてください。それは (1) 人によって異なり、(2) 言語が変わっても変わるべきではありません。

DynamicGreeting.js

import { T, Var } from 'gt-next';
 
export default function DynamicGreeting({ user }) {
  return (
    <T>
      こんにちは、<Var>{user.name}</Var>! // [!code highlight]
    </T>
  );
}

多くの変数コンポーネントがあります: <Var>, <Num>, <Currency> および <DateTime>。これらの一部は、ユーザーのロケールに基づいてコンテンツを自動的に再フォーマットします。他のものは単にコンテンツを「翻訳しない」とマークします。また、これらのコンポーネントは、コンテンツを再フォーマットするために必ずしも <T> コンポーネントでラップされる必要はありません。

変数コンポーネントの使用に関するこの記事で詳細を読むことができます。

`<T>` コンポーネント内の分岐

分岐コンポーネントは、翻訳の条件に基づいて異なるコンテンツを表示するために使用できます。これには、<Plural> および <Branch> コンポーネントが含まれます。これらのコンポーネントを使用する理由は、より最適化された翻訳プロセスを可能にするためです。

例えば、<Plural> コンポーネントは、翻訳が行われる際に複数形にすべき文をマークすることができます。

Count.js

import { T, Plural } from 'gt-next';
 
export default function Count({ num }) {
  return (
    <T>
      <Plural
        n={num} // <-- チェックする変数
        singular={<p>1つのアイテムがあります。</p>}  
        plural={<p>複数のアイテムがあります。</p>}  
      />
    </T>
  );
}

これは、アプリケーション全体で複数形のロジックを標準化するのにも役立ちます。

使用するコンポーネントに応じて、異なるオプションを指定できます。分岐コンポーネントの記事で詳細を読むことができます。

文字列の翻訳

文字列だけを翻訳したい場合は、useGT(), getGT(), または tx() を使用できます。

useGT() および getGT() は、ビルド時に文字列を翻訳するために使用されます。

Greeting.js

function Greeting() {
  const t = useGT();  // client side
  const t = await getGT(); // server side
  return <p>{t('Hello, my friend!')}</p>; 
}

tx() は、実行時に文字列を翻訳するために使用されます。

FavoriteFlavor.js

function async FavoriteFlavor({ flavor }) {
  return <p>{await tx(`Your favorite ice cream flavor is ${flavor}`)}</p>; 
}

詳細については、文字列の翻訳に関するガイドを参照してください。

`<T>` コンポーネントに id を追加する

便利なデバッグのコツは、<T> コンポーネントに id プロップを追加することです。これにより、アプリケーションで使用されている翻訳を追跡することができます。また、翻訳エディタを使用して、再デプロイせずに翻訳を変更することもできます。

Greeting.js

import { T } from 'gt-next';
 
export default function Greeting() {
  return (
    <T id="greeting">
      Hello, world!
    </T>
  );
}

本番環境での考慮事項

本番環境へのデプロイ

本番環境にデプロイする前に、翻訳コマンドを実行して、すべての翻訳が実行時に利用可能であることを確認してください。 CDパイプラインに追加するか、ビルドスクリプトの一部として追加することをお勧めします。

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate --languages fr es ja && next build",
  }
}

以上です！アプリケーションをフランス語、スペイン語、日本語に翻訳することに成功しました。

アプリケーションのデプロイに関する詳細なガイドについては、デプロイメントガイドを参照してください。コマンドに関する詳細情報については、CLIツールリファレンスガイドを参照してください。

動作: 開発 vs 本番

開発環境では、<T> コンポーネントはオンデマンドでコンテンツを翻訳します。これは、コンポーネントがレンダリングされると、即座に翻訳を実行することを意味します。他の言語での開発を容易にするために、このようにしています。

この動作を有効にするには、環境にDev APIキーを追加するだけです。

本番環境では、<T> コンポーネントはビルド時にコンテンツを翻訳します。これは、アプリケーションをデプロイする前に翻訳コマンドを実行する必要があることを意味します。

ヒント: 開発環境で本番環境の動作をシミュレートしたい場合は、開発ビルドで本番APIキーを使用するだけです。

プライバシーの懸念

いくつかの例外を除き、<T> コンポーネントでラップされたすべてのコンテンツは、翻訳のために一般翻訳APIに送信されます。これは、ユーザー名やアカウント番号などの機密データをレンダリングする場合には望ましくないかもしれません。

この問題を回避するには、変数コンポーネントを使用してプライベート情報を処理してください。これにより、機密データが一般翻訳APIに送信されることはありません。変数コンポーネントでラップされたすべてのコンテンツのローカライズはローカルで処理されます。

例

基本的な使用法

<T> の最も簡単な使用例は、静的なテキストを翻訳することです。

import { T } from 'gt-next';
 
export default function BasicUsage() {
  return (
    <T>
      Hello, world!
    </T>
  );
}

この例では、ユーザーのロケールに基づいて "Hello, world!" が翻訳されることを保証します。例えば、スペイン語のロケールでは、"¡Hola, mundo!" と表示されるかもしれません。

コンテキスト

<T> コンポーネントは、翻訳を洗練するための追加のコンテキストをサポートしています。コンテキストプロップを追加することで、提供されたコンテキストに応じて同じ id が異なる翻訳に解決されるようになります。

import { T } from 'gt-next';
 
export default function FormalGreeting() {
  return (
    <T context="formal">
      Hi there!
    </T>
  );
}

例えば、コンテキスト "formal" は "Good day, everyone!" のような翻訳をもたらすかもしれませんが、同じ id がコンテキストなしでは他の言語で "Hi there!" になるかもしれません。もちろん、基本言語では変更はありません。

ネストされたコンポーネント

<T> コンポーネントは、JSX 構造も翻訳できます。 <T> の子要素はすべて翻訳されます。

import { T } from 'gt-next';
import CustomButton from './CustomButton';
 
export default function Page() {
  return (
    <T>
      This will be translated
      <div>
        <div>
          <div>
            <div>
              <CustomButton>This text will also be translated!</CustomButton>
            </div>
          </div>
        </div>
      </div>
    </T>
  );
}

よくある落とし穴

直接の子孫のみ

<T> コンポーネントは、直接子として渡されたテキストのみを翻訳します。つまり、コンポーネント内に <T> に直接渡されていないコンテンツがある場合、それは翻訳されません。

例を使って説明しましょう：

function UntranslatedContent() {
  return (
    <p>このコンテンツは翻訳されません</p>
  );
}
 
export default function DisplayGreetings() {
  return (
    <T>
      <h1>こんにちは、このテキストは翻訳されます</h1>
      <UntranslatedContent />
    </T>
  );
}

この例では、<UntranslatedContent> 内のコンテンツは翻訳されません。 <T> 内に直接あるコンテンツのみが翻訳されます。例えば、<h1> タグとその子孫です。

これは、React がコンポーネントをレンダリングする方法によるものです。少し複雑ですが、要点は、React はコンポーネントの内容をレンダリングするまで知らないということです。したがって、<UntranslatedContent> のようなコンポーネントの内容は翻訳されません。しかし、2つの <T> タグの間に直接あるテキストは翻訳されます。

注意: 良い指針として、ファイル内の2つの <T> の間に文字通りあるコンテンツは翻訳されます。翻訳されていないコンテンツを翻訳するために別の <T> を追加することは常に可能ですが、<T> コンポーネントをネストすることは推奨されません。

解決策は？

最初の本能としては、<UntranslatedContent> 内に追加の <T> コンポーネントを追加することかもしれませんが、これは推奨されません。これについては下記で詳しく説明します。

解決策は、常に <T> コンポーネントでテキストを直接ラップすることです。例えば：

function TranslatedContent() {
  return (
    <T>
      <p>このコンテンツは<b>翻訳されます</b></p>
    </T>
  );
}
 
export default function DisplayGreetings() {
  return (
    <>
      <T>
        <h1>こんにちは、このテキストは翻訳されます</h1>
      </T>
      <TranslatedContent />
    </>
  );
}

変数はどうですか？

変数は少し複雑です。なぜなら、それらは値を変更する傾向があるからです。動的な値を表示するためにはVariable Componentsを使用し、条件付きロジックにはBranching Componentsを使用することをお勧めします。

実行時に動的なコンテンツを翻訳したい場合は、tx() と <Tx> をチェックしてください。

ネストされた `<T>` コンポーネント

<T> コンポーネントのネストは許可されていません。 React のレンダリングシステムのため、これは予期しない動作やパフォーマンスの問題を引き起こす可能性があります。

やってはいけないことの例を以下に示します：

function SomeComponent() {
  return (
    <T>
      こんにちは、友よ！
    </T>
  );
}
 
export default function NestedTranslation() {
  return (
    <T>
      <T> {/* これはやめましょう！ */} // [!code highlight]
        こんにちは、世界！
      </T>
      <SomeComponent /> {/* これもカウントされます。やめましょう！ */} // [!code highlight]
    </T>
  );
}

ここでの解決策は、最も外側の <T> コンポーネントを削除することです。

条件付きコンテンツ

変数コンテンツのレンダリングと同様に、<T> コンポーネント内の条件付きコンテンツは適切に処理する必要があります。コンテンツの翻訳を最適化するために、条件付きコンテンツをBranching Componentでラップすることが常に最善の方法です。

import { T, Branch } from 'gt-next';
 
export default function Header({ user }) {
  return (
    <T>
      <h2>
        <Branch
          branch={user.hasAccount}
          true={<p>お帰りなさい、{user.name}さん！</p>}
          false={<p>続行するにはログインしてください。</p>}
        />
      </h2>
    </T>
  );
}

メモ

<T> コンポーネントは任意のJSXコンテンツを翻訳するために使用されます。
クライアントコンポーネントでの翻訳を有効にするには、アプリを <GTProvider> でラップしてください。
<T> はビルド時にコンテンツを翻訳します。実行時ではありません。開発中は利便性のためにオンデマンド翻訳が行われますが、本番環境ではそうではありません。

次のステップ

可変コンポーネントの記事と分岐コンポーネントのガイドを探索してください。
アプリケーションでの文字列の翻訳について学びましょう。
実行時の翻訳については、tx()と<Tx>をチェックしてください。

<T> リファレンス

このページについて