はじめに

General Translation React SDK は、React アプリケーション向けのオープンソースの国際化（i18n）ライブラリです。

本 SDK は、他の一般的な i18n ライブラリと同等の機能を備え、React アプリケーションを簡潔かつ保守しやすい形で国際化するための包括的なツールセットを提供します。

SDK は General Translation プラットフォームがなくても単体で利用でき、他の i18n ライブラリと同様に動作します。

一方で、当社プラットフォームと連携することで、次のような拡張機能も利用できます:

• 開発時の翻訳ホットリロード
• 自動 AI 翻訳
• General Translation プラットフォームとの翻訳同期
• 当社の翻訳 CDN（コンテンツ配信ネットワーク）とのネイティブ統合

コンセプト

SDKを理解するうえで押さえておくべき主要なコンセプトは5つあります。

<GTProvider> コンポーネント

<GTProvider> コンポーネントは、現在の言語や関連する翻訳を含む翻訳コンテキストをアプリケーションに提供します。

import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* アプリケーションの内容 */}
      </div>
    </GTProvider>
  );
}

重要: プロバイダーはアプリケーション全体をラップし、可能な限りコンポーネントツリーの高い位置、たとえばルートの App コンポーネントに配置してください。

詳しくは、GTProvider の APIリファレンスをご覧ください。

<T> コンポーネント

<T> コンポーネントは、アプリケーション内のコンテンツを翻訳するための推奨手段です。

任意の JSX 要素をラップできる React コンポーネントで、要素の内容をサポート対象の言語に自動的にレンダリングします。

例

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

<T>
  <div>
    <h1> 画像はこちらです </h1>
    <img src="https://example.com/image.png" alt="例" />
  </div>
</T>

<T>
  フォーマットは `<T>` コンポーネントで簡単に行えます。
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

<T> コンポーネントは、動的なコンテンツのフォーマットのために、<Num>、<DateTime>、<Currency> などの variable components と組み合わせて利用できます。

詳しくは、<T> コンポーネントガイドを参照して、<T> コンポーネントのさまざまな活用方法をご確認ください。

useGT フック

useGT フックは、いくつかのトレードオフはあるものの、<T> コンポーネントと同様に使える React のフックです。

このフックは、文字列を翻訳する関数を返します。

const t = useGT();

t('こんにちは、世界！');

<T> コンポーネントと比べると、useGT フックはコードベースでより柔軟に使えます。

たとえば、ネストした文字列を含む複雑なデータ構造がある場合は、<T> コンポーネントより扱いづらくなります。

const t = useGT();
const data = {
  title: t('こんにちは、世界！'),
  description: t('これは説明です。'),
};

useGT フックの詳細は、strings ガイドをご参照ください。

msg 関数

msg 関数は、複数のコンポーネントで使われる、または設定オブジェクトに保存される翻訳対象の文字列をマークするために利用します。

これは、ナビゲーションのラベル、フォームメッセージ、あるいはアプリケーション内の複数箇所に表示されるテキストなどの共有コンテンツに特に有用です。

// 翻訳対象の文字列にマークを付ける
import { msg } from 'gt-react';

const navItems = [
  { label: msg('ホーム'), href: '/' },
  { label: msg('概要'), href: '/about' },
  { label: msg('お問い合わせ'), href: '/contact' }
];

// Decode and use the marked strings
import { useMessages } from 'gt-react';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

msg 関数は翻訳メタデータ付きで文字列をエンコードし、useMessages はそれをデコードします。

msg 関数の詳細は、shared strings ガイドをご覧ください。

useTranslations フック

useTranslations は、指定したキーの翻訳を取得するための関数を返す React のフックです。

const dictionary = {
  hello: {
    world: 'こんにちは、世界！',
  },
};

const translate = useTranslations();
translate('hello.world');

この挙動は、react-i18next や next-intl などの他の翻訳ライブラリと似ています。

useTranslations フックの詳細は、dictionaries ガイドをご覧ください。

詳細は、useTranslations APIリファレンス を参照してください。

次のステップ

• SDK を使って React プロジェクトをセットアップする方法を学ぶ: クイックスタート
• <T> コンポーネントで JSX コンテンツを翻訳する方法を学ぶ: JSX 翻訳ガイド
• useGT フックで文字列を翻訳する方法を学ぶ: 文字列翻訳ガイド
• msg 関数で共有文字列を扱う方法を学ぶ: 共有文字列ガイド