# General Translation Overview: コーディングエージェントの活用
URL: https://generaltranslation.com/ja/docs/overview/for-coding-agents.mdx
---

title: コーディングエージェントの活用
description: AIコーディングエージェントやLLMsでGeneral Translationを使う方法。機械可読なドキュメント、MCPサーバー、すぐに使えるエージェントガイドを活用します。

---

General Translationは、AIコーディングエージェントやLLMsと連携して使えるように設計されています。ライブラリはオープンソースで、設定はわかりやすく、ドキュメントは機械可読な形式で公開されています。Cursor、Claude Code、Copilotのようなエージェントなら、正確で最新のcontextに基づいて、General Translationの導入や実行を代行できます。

*自動でプルリクエストを作成する完全自動のローカライゼーションには、自前のエージェントを使うのではなく、専用エージェントの[Locadex](/docs/platform/locadex/quickstart)をご利用ください。*

## すぐ使えるエージェントガイド [#agent-guide]

一度貼り付けるだけで、エージェントに必要な情報をすべて渡せます。以下のガイドをプロジェクトルートの `AGENTS.md` (または `CLAUDE.md`、Cursor のルール、あるいはお使いのツールの指示ファイル) にコピーすると、エージェントが General Translation を正しく追加して実行します。ブロック右上のコピーボタンを使ってください。

````markdown title="AGENTS.md"
# General Translation — agent guide

これは、プロジェクトに [General Translation](https://generaltranslation.com) を追加するAIコーディングエージェント向けの手順書です。General Translation はフルスタックのローカライゼーション製品であり、オープンソースのi18nライブラリとCLIを組み合わせて、アプリとそのコンテンツをあらゆる言語に翻訳します。コードの国際化や翻訳の組み込みを行う際は、以下のルールに従ってください。

## 使用するパッケージ

スタックに合ったパッケージを選択してください：

- **Next.js（App Router または Pages Router）** → `gt-next`
- **React（SPA、例：Vite）** → `gt-react`
- **Node.js サーバー** → `gt-node`
- **任意の JavaScript ランタイム、または低レベルの制御** → `generaltranslation`（コアライブラリ）
- **コンテンツファイル（JSON、MDX、YAML など）の翻訳、またはCIでの翻訳実行** → `gt` CLI

これらはすべて無料かつオープンソースです。ライブラリは General Translation アカウントの有無にかかわらず動作しますが、API Keyを使用することで開発時のオンデマンド翻訳とホスト型 translation API が利用可能になります。

## セットアップ

ウィザードの使用を推奨します。プロジェクトルートから以下を実行してください：

```bash
npx gt init
```

これにより、適切なライブラリと `gt` CLI がインストールされ、フレームワークの設定（Next.js の場合は `withGTConfig` と GTProvider の追加）、gt.config.json の作成、API 認証情報の生成が行われます。

手動でセットアップする場合は、パッケージを自分でインストールしてください：

```bash
npm install gt-next   # or gt-react / gt-node / generaltranslation
npm install -D gt
```

次に、プロジェクトルートに gt.config.json を作成します。これがロケールの唯一の設定ソースとなります：

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": { "gt": { "output": "public/_gt/[locale].json" } }
}
```

- `defaultLocale` — ソースが記述されている言語。
- `locales` — 翻訳先の言語一覧。
- `files.gt.output` — CLIが translation files を書き出す場所（`[locale]` は言語ごとに置換されます）。このディレクトリは `.gitignore` に追加してください。これらのファイルは自動生成されます。

API 認証情報を環境変数として設定してください（Next.js の場合は `.env.local`、それ以外は `.env`）：

```bash
GT_API_KEY="gtx-dev-..."   # gtx-dev- in development, gtx-api- in production/CI
GT_PROJECT_ID="..."
```

`GT_API_KEY` をコミットしたり、ブラウザに公開したり、`NEXT_PUBLIC_` のプレフィックスを付けたりしないでください。

## 基本的な使い方

ユーザー向けの JSX を `<T>` で囲みます。ソーステキストを直接記述してください。翻訳キーは不要です：

```tsx
import { T } from 'gt-next'; // or 'gt-react'

// <T> の内側はすべてひとつの単位として翻訳される
<T>
  <h1>Welcome to my app</h1>
</T>;
```

単独の文字列（プレースホルダー、`aria-label`、`alt`、ボタンラベルなど）には `useGT()` を使用します。`useGT()` は翻訳関数を直接返します：

```tsx
import { useGT } from 'gt-next';

const gt = useGT(); // ✅ 正しい
// const { gt } = useGT(); // ❌ 誤り — useGT はオブジェクトではなく関数を返す

<input placeholder={gt('Search products')} />;
```

async App Router components では、代わりに `getGT` を使用します。`gt-next/server` は Pages Router では動作しません：

```tsx
import { getGT } from 'gt-next/server';

const gt = await getGT();
```

動的またはプライベートな値（名前、メールアドレス、IDなど）は `<Var>` で囲み、翻訳されず API に送信されないようにします。再フォーマットは必要だが翻訳は不要な値には `<Currency>`、`<DateTime>`、`<Num>` を使用します：

```tsx
import { T, Var } from 'gt-next';

// 翻訳を1つ生成し、名前はそのまま保持する
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

Node.js サーバーの場合は、一度初期化してリクエストごとに翻訳を解決します：

```js
import { initializeGT, withGT, getGT } from 'gt-node';

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// ハンドラーを withGT(locale, ...) でラップし、その内部で `const gt = await getGT()` を使用する
```

ロケールの設定はすべて gt.config.json にまとめてください。ロケールのリストをコードベース全体に散在させないようにしましょう。

## コマンド

| コマンド | 実行タイミング |
| --- | --- |
| `npx gt init` | プロジェクトのセットアップ時に一度だけ実行（依存関係のインストール、フレームワークの設定、gt.config.json の作成、認証情報の生成）。 |
| `npx gt configure` | ウィザードを使わずに gt.config.json（locales とファイル設定）を作成または更新する場合。 |
| `npx gt auth` | API 認証情報を生成または更新する場合。 |
| `npx gt translate` | General Translation API を通じてプロジェクトを翻訳する場合。CI で本番ビルドの**前**に実行してください。 |
| `npx gt generate` | 手動で翻訳するための translation file テンプレートを作成する場合（API Keyは不要）。 |

翻訳を常に最新の状態に保つため、本番ビルドに翻訳ステップを追加してください。例：`"build": "npx gt translate && next build"`。

## ルール — すべきこととすべきでないこと

すべきこと：

- ユーザー向けのテキストを記述する際は、必ず `<T>`（単独の文字列には `useGT()`/`getGT()`）で囲む。
- コミットや本番ビルドの前に `npx gt translate` を実行して、新しいテキストが翻訳されるようにする。
- ロケールのリストは gt.config.json のみで管理する。
- 動的またはプライベートな値は `<Var>` で囲み、文字列が曖昧な場合は `context` を追加する。

すべきでないこと：

- 翻訳済みの文字列をソースにハードコードしたり、言語ごとに `if`/`switch` 分岐を追加したりしない。代わりにソーステキストを翻訳する。
- 自動生成された translation files を手動で編集しない（CLIが上書きします）。
- `GT_API_KEY` をコミットしたり、クライアントに公開したりしない。
- gt.config.json 以外の場所でロケール設定を重複させない。

## リンク

- [`llms.txt`](/llms.txt) — 簡潔な機械可読ドキュメントインデックス。
- [`sitemap.md`](/sitemap.md) — すべてのドキュメントページのマップ。
- Quickstart: [React](/docs/react/react-quickstart)、[Node](/docs/node/quickstart)、[コアライブラリ](/docs/platform/core/quickstart)、[CLI](/docs/cli/quickstart)。
- [主要概念](/docs/overview/key-concepts) — ロケール、context、静的コンテンツと動的コンテンツの違い。
````

## エージェントからドキュメントを参照できるようにする [#point-agents]

エージェントが正確に回答できるよう、ドキュメントへ直接アクセスできるようにします。General Translation は、サイトのルートで機械可読なエントリポイントをいくつか公開しています。

* [`llms.txt`](/llms.txt) — ドキュメントの簡潔な [llmstxt.org](https://llmstxt.org/)-形式のインデックス。
* [`sitemap.md`](/sitemap.md) — ナビゲーション順ですべてのページをたどれるリンク付きマップ。

各ドキュメントページは **生の Markdown** としても利用できます。任意のページ URL の末尾に `.md` を追加すると (たとえば `/docs/cli/quickstart.md`) 、レンダリング済み HTML を解析する代わりに、クリーンなソースを取得できます。

ドキュメントをコンテキストとして追加するには、ドキュメントの URL または `llms.txt` のリンクをエージェントのコンテキストに貼り付けるか、ドキュメントのインデックス化に対応したツールでソースとして追加してください。

## MCP サーバー [#mcp]

General Translation は、エージェントがドキュメントを直接問い合わせできる [Model Context Protocol](https://modelcontextprotocol.io) (MCP) サーバーを提供しています。利用方法は 2 つあります。

* **ローカル (stdio)** — 公開されている [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) npm パッケージで、`npx` を使って手元のマシン上で実行します。Cursor や Claude Code など、永続的な接続を維持するツールに最適です。
* **リモート (HTTP/SSE)** — `https://mcp.gtx.dev` でホストされているエンドポイントです。SSE エンドポイントは、使用するツールが streamable HTTP をサポートしていない場合にのみ使用してください。

使用するツールが対応しているトランスポートに応じて接続を設定してください。設定の形式はどのツールでも共通です。ツールの MCP 設定ファイル (たとえば `.mcp.json`) に追加します。

<Tabs items={['Local', 'Streamable HTTP', 'SSE']}>
  <Tab value="Local">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "command": "npx",
          "args": ["-y", "@generaltranslation/mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Streamable HTTP">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "streamable-http",
          "url": "https://mcp.gtx.dev"
        }
      }
    }
    ```
  </Tab>

  <Tab value="SSE">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "sse",
          "url": "https://mcp.gtx.dev/sse"
        }
      }
    }
    ```
  </Tab>
</Tabs>

接続したら、エージェントに `generaltranslation` MCP サーバーを使うよう依頼してください。*例: 「[`<T>`](/docs/react/reference/components/t) コンポーネントの使い方を説明するために generaltranslation MCP サーバーを使ってください。」*

## エディター別のヒント [#editor-tips]

セットアップの大半はどのエージェントでも共通で、案内が異なるのは次の数か所だけです。

* **Cursor** — MCP サーバーを登録したうえで、「`generaltranslation` ツールを使って」と指示します。ドキュメントを情報源として追加するか、プロンプト内で `/llms.txt` を参照してください。
* **Claude Code** — ルートの `AGENTS.md` を自動で読み込むため、[エージェントガイド](#agent-guide) をプロジェクトの `AGENTS.md` に置くだけで事前設定として十分です。MCP サーバーを登録し、「`generaltranslation` MCP サーバーを使って」と指示してください。
* **Copilot** — リポジトリ全体のガイダンスは instructions ファイル (たとえば `.github/copilot-instructions.md`) に記述し、そこでドキュメント `/llms.txt` を参照してください。

## ベストプラクティス [#best-practices]

機械的な i18n 作業において、Agents は頼りになりますが、翻訳の品質や設定には依然として人の確認が必要です。次のように役割分担してください。

* **エージェント に任せる:** ユーザー向けの文言を `<T>` で囲むこと、単独の文字列に [`useGT()`](/docs/react/reference/hooks/use-gt) を追加すること、`gt.config.json` のひな形を作成すること、そして `npx gt init` を実行すること。
* **手作業で確認する:** エージェント が作成した[翻訳コンテキスト](/docs/overview/key-concepts#context) (用語集とディレクティブ) 、ロケール設定 (`defaultLocale` と `locales`) 、および動的な値や非公開の値が [`<Var>`](/docs/react/reference/components/var) で囲まれていること。
* **エージェント に絶対にやらせない:** 生成された翻訳ファイルを手作業で編集すること、または CLI を使って原文を翻訳する代わりに、すでに翻訳済みの文字列をハードコードすること。