# gt-react: General Translation React SDK: 概要
URL: https://generaltranslation.com/ja/docs/react/introduction.mdx
---
title: 概要
description: General TranslationのReact SDKの概要
---

{/* 自動生成: このファイルは直接編集しないでください。代わりに、content/docs-templates/ 内のテンプレートを編集してください。 */}


## はじめに

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

React アプリケーションを簡単かつ保守しやすい形で国際化できる包括的なツール群を提供しており、他の主要な i18n ライブラリと同等の機能を備えています。

この SDK は、General Translation プラットフォームを使わずにスタンドアロンで利用でき、他の i18n ライブラリと同様に動作します。

一方で、より高度な機能を利用するために、General Translation プラットフォームと統合することもできます。

* 開発時の翻訳のホットリロード
* AI による自動翻訳
* General Translation プラットフォームとの翻訳の同期
* 翻訳 CDN とのネイティブ統合

## 概念

SDK について理解しておくべき主な概念は 5 つあります。

<Steps>
  <Step>
    [`<GTProvider>`](/docs/react/api/components/gtprovider) コンポーネント
  </Step>

  <Step>
    [`<T>`](/docs/react/api/components/t) コンポーネント
  </Step>

  <Step>
    [`useGT`](/docs/react/api/strings/use-gt) フック
  </Step>

  <Step>
    共有文字列用の [`msg`](/docs/react/api/strings/msg) 関数
  </Step>

  <Step>
     (任意) [`useTranslations`](/docs/react/api/dictionary/use-translations) フック
  </Step>
</Steps>

## `<GTProvider>` コンポーネント

[`<GTProvider>`](/docs/react/api/components/gtprovider) コンポーネントは、現在の言語や関連する翻訳を含む翻訳コンテキストをアプリケーションに提供します。

```tsx
import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* アプリケーションのコンテンツ */}
      </div>
    </GTProvider>
  );
}
```

**重要:** このプロバイダーはアプリケーション全体をラップするようにし、ルートの App コンポーネントなど、できるだけコンポーネントツリーの上位に配置してください。

詳細は [`GTProvider`](/docs/react/api/components/gtprovider) の API リファレンスを参照してください。


## `<T>` コンポーネント

[`<T>`](/docs/react/api/components/t) コンポーネントは、アプリケーション内のコンテンツを翻訳するための推奨手段です。

これは React コンポーネントで、任意の JSX 要素をラップして使用でき、要素の内容を対応言語で自動的にレンダリングします。

<Callout type="info">
  可能な限り [`<T>`](/docs/react/api/components/t) コンポーネントを使用することをおすすめします。翻訳において最も高い柔軟性を確保できるためです。

  [`<T>`](/docs/react/api/components/t) コンポーネントは、文字列とは異なり HTML コンテンツも翻訳できるため、文字列の翻訳よりもはるかに強力です。
</Callout>

### 例

```tsx
<T>
  <div>Hello, world!</div>
</T>
```

```tsx
<T>
  <div>
    <h1> Here is an image </h1>
    <img src="https://example.com/image.png" alt="Example" />
  </div>
</T>
```

```tsx
<T>
  Formatting can be done easily with the `<T>` component.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>
```

[`<T>`](/docs/react/api/components/t) コンポーネントは、動的なコンテンツをフォーマットするために、[`<Num>`](/docs/react/api/components/num)、[`<DateTime>`](/docs/react/api/components/datetime)、[`<Currency>`](/docs/react/api/components/currency) などの [変数コンポーネント](/docs/react/guides/variables) と組み合わせて使用できます。

[`<T>`](/docs/react/api/components/t) コンポーネントのさまざまな使い方については、[`<T>` コンポーネントガイド](/docs/react/guides/t) を参照してください。


## `useGT` フック

[`useGT`](/docs/react/api/strings/use-gt) フックは React のフックで、いくつかのトレードオフはあるものの、[`<T>`](/docs/react/api/components/t) コンポーネントと同様に使えます。

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

```tsx
const gt = useGT();

gt('Hello, world!');
```

[`<T>`](/docs/react/api/components/t) コンポーネントと比べると、[`useGT`](/docs/react/api/strings/use-gt) フックを使うことで、コードベース内でより柔軟に扱えます。

たとえば、文字列がネストされた複雑なデータ構造がある場合は、[`<T>`](/docs/react/api/components/t) コンポーネントは使いにくくなります。

```tsx
const gt = useGT();
const data = {
  title: gt('Hello, world!'),
  description: gt('This is a description'),
};
```

[`useGT`](/docs/react/api/strings/use-gt) フックの詳細は、[文字列](/docs/react/guides/strings) ガイドを参照してください。


## `msg` 関数

[`msg`](/docs/react/api/strings/msg) 関数は、複数のコンポーネントで使い回したり、設定オブジェクトに保存したりする文字列を翻訳対象としてマークするために使用します。

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

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

const navItems = [
  { label: msg('Home'), href: '/' },
  { label: msg('About'), href: '/about' },
  { label: msg('Contact'), href: '/contact' }
];
```

```tsx
// マークされた文字列をデコードして使用する
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`](/docs/react/api/strings/msg) 関数は文字列を翻訳メタデータ付きでエンコードし、[`useMessages`](/docs/react/api/strings/use-messages) はそれをデコードします。

<Callout type="info">
  アプリケーション全体で一貫した翻訳が必要な共有コンテンツには [`msg`](/docs/react/api/strings/msg) を使用してください。コンポーネント固有のコンテンツには、[`<T>`](/docs/react/api/components/t) または [`useGT`](/docs/react/api/strings/use-gt) の使用を推奨します。
</Callout>

詳細は、`msg` 関数を説明した [共有文字列](/docs/react/guides/shared-strings) ガイドを参照してください。


## `useTranslations` フック

[`useTranslations`](/docs/react/api/dictionary/use-translations) は、指定したキーに対応する翻訳を取得するための関数を返す React フックです。

```tsx title="dictionary.ts"
const dictionary = {
  hello: {
    world: 'Hello, world!',
  },
};
```

```tsx title="App.tsx"
const translate = useTranslations();
translate('hello.world');
```

この挙動は、[`react-i18next`](https://react.i18next.com/) や [`next-intl`](https://next-intl-docs.vercel.app/) などの他の翻訳ライブラリと似ています。

<Callout type="warn">
  アプリケーションで [`useTranslations`](/docs/react/api/dictionary/use-translations) フックを使用することは推奨していません。[`useTranslations`](/docs/react/api/dictionary/use-translations) フックを頻繁に使うと、コードベースの保守性が低下し、
  大きな技術的負債につながります。

  代わりに、[`<T>`](/docs/react/api/components/t) コンポーネントまたは [`useGT`](/docs/react/api/strings/use-gt) フックの使用を推奨します。

  別の i18n ライブラリから移行する場合、[`useTranslations`](/docs/react/api/dictionary/use-translations) フックはドロップイン置換として使えるため、コードベースを段階的に移行する際に役立ちます。
</Callout>

[`useTranslations`](/docs/react/api/dictionary/use-translations) フックの詳細は、[dictionaries](/docs/react/guides/dictionaries) ガイドを参照してください。

さらに詳しくは、[useTranslations API リファレンス](/docs/react/api/dictionary/use-translations) を参照してください。

***


## 次のステップ

* SDK を使った React プロジェクトのセットアップ方法については、[Quickstart](/docs/react) を参照してください
* [`<T>`](/docs/react/api/components/t) コンポーネントを使って JSX コンテンツを翻訳する方法については、[JSX Translation Guide](/docs/react/guides/t) を参照してください
* [`useGT`](/docs/react/api/strings/use-gt) フックを使って文字列を翻訳する方法については、[String Translation Guide](/docs/react/guides/strings) を参照してください
* [`msg`](/docs/react/api/strings/msg) 関数を使った共有文字列については、[Shared Strings Guide](/docs/react/guides/shared-strings) を参照してください