# 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

Instructions for AI coding agents adding [General Translation](https://generaltranslation.com) to a project. General Translation is a full-stack localization product: open-source i18n libraries plus a CLI that translate an app and its content into any language. Follow these rules when internationalizing code or wiring up translations.

## What to use

Pick the package that matches the stack:

- **Next.js (App Router or Pages Router)** → `gt-next`
- **React (SPA, e.g. Vite)** → `gt-react`
- **Node.js server** → `gt-node`
- **Any JavaScript runtime, or lower-level control** → `generaltranslation` (the Core library)
- **Translating content files (JSON, MDX, YAML, and more) or running translation in CI** → the `gt` CLI

All of these are free and open-source. The libraries work with or without a General Translation account; an API key unlocks on-demand translation in development and the hosted translation API.

## Setup

Prefer the wizard. From the project root, run:

```bash
npx gt init
```

It installs the right library and the `gt` CLI, wires up the framework (for Next.js, adds `withGTConfig` and `GTProvider`), creates `gt.config.json`, and generates API credentials.

For manual setup, install the packages yourself:

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

Then create `gt.config.json` in the project root — this is the single source of truth for locales:

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

- `defaultLocale` — the language the source is written in.
- `locales` — the languages to translate into.
- `files.gt.output` — where the CLI writes translation files (`[locale]` is replaced per language). Add this directory to `.gitignore`; the files are generated.

Set API credentials as environment variables (in `.env.local` for Next.js, `.env` otherwise):

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

Never commit `GT_API_KEY`, expose it to the browser, or prefix it with `NEXT_PUBLIC_`.

## Core usage

Wrap user-facing JSX in `<T>`. Write source copy directly — no translation keys needed:

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

// Everything inside <T> is translated as a unit
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Use `useGT()` for standalone strings (placeholders, `aria-label`, `alt`, button labels). `useGT()` returns the translation function directly:

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

const gt = useGT(); // ✅ correct
// const { gt } = useGT(); // ❌ wrong — useGT returns the function, not an object

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

In async App Router components, use `getGT` instead. `gt-next/server` does not work with the Pages Router:

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

const gt = await getGT();
```

Wrap dynamic or private values (names, emails, IDs) in `<Var>` so they are not translated and never sent to the API. Use `<Currency>`, `<DateTime>`, and `<Num>` for values that should be reformatted but not translated:

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

// Generates one translation, keeps the name unchanged
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

For Node.js servers, initialize once and resolve translations per request:

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

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// wrap handlers in withGT(locale, ...); then `const gt = await getGT()` inside them
```

Keep all locale configuration in `gt.config.json` — do not scatter locale lists across the codebase.

## Commands

| Command | When to run |
| --- | --- |
| `npx gt init` | Once, to set up a project (installs deps, configures the framework, creates `gt.config.json`, generates credentials). |
| `npx gt configure` | To create or update `gt.config.json` (locales and files) without the full wizard. |
| `npx gt auth` | To generate or refresh API credentials. |
| `npx gt translate` | To translate the project via the General Translation API. Run in CI **before** building for production. |
| `npx gt generate` | To create translation file templates to translate manually (no API key needed). |

Add translation to the production build so translations stay current, for example: `"build": "npx gt translate && next build"`.

## Rules — do and don't

Do:

- Wrap every new piece of user-facing copy in `<T>` (or `useGT()`/`getGT()` for standalone strings) as you write it.
- Run `npx gt translate` before committing or building for production so new copy is translated.
- Keep the locale list in `gt.config.json` only.
- Wrap dynamic and private values in `<Var>`, and add `context` when a string is ambiguous.

Don't:

- Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead.
- Hand-edit generated translation files (the CLI overwrites them).
- Commit `GT_API_KEY` or expose it to the client.
- Duplicate the locale configuration outside `gt.config.json`.

## Links

- [`llms.txt`](/llms.txt) — 簡潔な機械可読ドキュメントインデックス。
- [`llms-full.txt`](/llms-full.txt) — より大きなコンテキストを読み込めるツール向けの完全なドキュメントコンテンツ。
- [`sitemap.xml`](/sitemap.xml) — 公開済みの全ページのマップ。
- 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 は、ドキュメントホストのサイトルートおよび `/docs` 配下で、機械可読なエントリポイントをいくつか公開しています。

* [`llms.txt`](/llms.txt) — ドキュメントの簡潔な [llmstxt.org](https://llmstxt.org/)-形式のインデックス。
* [`llms-full.txt`](/llms-full.txt) — 生成された OpenAPI リファレンスを除く、ドキュメント全文を 1 つのファイルにまとめたもの。
* [`sitemap.xml`](/sitemap.xml) — 公開されているすべてのページの機械可読なマップ。

ドキュメントホストでは、これらのファイルを `/docs/llms.txt` と `/docs/llms-full.txt` でも配信しています。各ドキュメントページは **生の Markdown** としても利用できます。任意のページ URL の末尾に `.md` または `.mdx` を追加すると (たとえば `/docs/cli/quickstart.mdx`) 、レンダリング済み 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 作業において、エージェントは頼りになりますが、翻訳の品質や設定には依然として人の確認が必要です。次のように役割分担してください。

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