# General Translation Overview: コーディングエージェントの活用 URL: https://generaltranslation.com/ja/docs/overview/for-coding-agents.mdx Docs index: https://generaltranslation.com/llms.txt 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 を正しく追加して実行します。ブロック右上のコピーボタンを使うか、[`/AGENTS.md`](/AGENTS.md) から同じガイドを直接取得してください。 ````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` - **Vue 3** → `gt-vue` - **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 ``. Write source copy directly — no translation keys needed: ```tsx import { T } from 'gt-next'; // or 'gt-react' // Everything inside is translated as a unit

Welcome to my app

; ``` 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 ; ``` 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 `` so they are not translated and never sent to the API. Use ``, ``, and `` for values that should be reformatted but not translated: ```tsx import { T, Var } from 'gt-next'; // Generates one translation, keeps the name unchanged Hello, {name}! ; ``` 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'] }); // ハンドラーを withGT(locale, ...) でラップし、その内部で `const gt = await getGT()` を呼び出します ``` すべてのロケール設定は `gt.config.json` にまとめてください。ロケールのリストをコードベース全体に散在させないでください。 ## コマンド | コマンド | 実行するタイミング | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npx gt init` | プロジェクトのセットアップ時に一度だけ (依存関係のインストール、フレームワークの設定、`gt.config.json` の作成、認証情報の生成)。 | | `npx gt configure` | 完全なウィザードを使わずに `gt.config.json` (ロケールとファイル) を作成または更新する場合。 | | `npx gt auth` | API 認証情報を生成または更新する場合。 | | `npx gt translate` | General Translation API 経由でプロジェクトを翻訳する場合。本番ビルドの**前**に CI で実行してください。ローカルの編集内容を先に同期する必要がある場合にのみ `--save-local` を追加します。 | | `npx gt generate` | 手動で翻訳するための翻訳ファイルのテンプレートを作成する場合 (API キー不要)。 | | `npx gt api --spec` | インストール済みの CLI に同梱された OpenAPI 仕様を確認する場合。 | | `npx gt api ` | スクリプトやターミナルから認証済みの生の API リクエストを送信する場合。 | | `npx gt project create --org-id --name --default-locale ` | 組織キーを使ってプロジェクトを作成する場合。 | | `npx gt project status ` | 翻訳ジョブやプロジェクトのコンテキスト生成ジョブを確認する場合。 | 翻訳を常に最新に保つため、本番ビルドに翻訳を組み込んでください。例: `"build": "npx gt translate && next build"`。 ## ルール — すべきこと・すべきでないこと すべきこと: - ユーザーに表示される新しい文言は、記述する際に必ず `` (単独の文字列の場合は `useGT()`/`getGT()`) でラップする。 - 新しい文言が翻訳されるよう、コミット前または本番ビルド前に `npx gt translate` を実行する。 - ロケールのリストは `gt.config.json` にのみ記載する。 - 動的な値やプライベートな値は `` でラップし、文字列が曖昧な場合は `context` を追加する。 - 生成された翻訳ファイルを意図的に編集した場合は、翻訳を再度ダウンロードする前に `npx gt save-local` を実行するか、次回の翻訳実行時に `--save-local` を渡す。 すべきでないこと: - 翻訳済みの文字列をソースにハードコードしたり、言語ごとの `if`/`switch` 分岐を追加したりすること。代わりにソースの文言を翻訳してください。 - 変更を同期せずに生成された翻訳ファイルを編集すること。後のダウンロードで保存されていない編集内容が上書きされる可能性があります。 - `GT_API_KEY` をコミットしたり、クライアントに公開したりすること。 - `gt.config.json` の外でロケール設定を重複させること。 ## リンク - [`llms.txt`](/llms.txt) — 厳選された機械可読なドキュメントのエントリーポイント。 - [`llms-index.txt`](/llms-index.txt) — すべてのドキュメントページの網羅的なインデックス。 - [`llms-full.txt`](/llms-full.txt) — より大きなコンテキストを読み込めるツール向けの完全なドキュメント内容。 - [React インデックス](/docs/react/llms.txt)、[CLI インデックス](/docs/cli/llms.txt)、[OpenAPI インデックス](/docs/platform/openapi/llms.txt) — よくあるタスクに絞ったエントリーポイント。 - [`AGENTS.md`](/AGENTS.md) — このドロップインガイドの生の Markdown 版。 - [`openapi.yaml`](/openapi.yaml) — General Translation API の正式な仕様。 - [`sitemap.md`](/sitemap.md) — すべてのドキュメントページとブログ記事の Markdown インデックス。 - [`sitemap.xml`](/sitemap.xml) — 公開されているすべてのページの標準的なサイトマップ。 - クイックスタート: [React](/docs/react/react-quickstart)、[Vue](/docs/vue/quickstart)、[Node](/docs/node/quickstart)、[Core ライブラリ](/docs/platform/core/quickstart)、および [CLI](/docs/cli/quickstart)。 - [主要な概念](/docs/overview/key-concepts) — ロケール、コンテキスト、静的コンテンツと動的コンテンツ。 - CLI リファレンス: [`gt api`](/docs/cli/reference/commands/api)、[`gt project create`](/docs/cli/reference/commands/project-create)、[`gt project status`](/docs/cli/reference/commands/project-status)。 ```` ## エージェントにドキュメントを参照させる [#point-agents] 回答の正確性を保つために、エージェントにドキュメントへの直接アクセスを与えましょう。General Translation は、ドキュメントホストのサイトルートおよび `/docs` 配下で、機械可読なエントリポイントをいくつか公開しています。 * [`llms.txt`](/llms.txt) — 主要な Quickstart と用途別インデックスを厳選してまとめた、[llmstxt.org](https://llmstxt.org/) 形式のエントリポイント。 * [`llms-index.txt`](/llms-index.txt) — 公開されているすべてのドキュメントページを網羅したリンクインデックス。 * [`llms-full.txt`](/llms-full.txt) — 生成された OpenAPI リファレンスを除く、ドキュメント全文を 1 つのファイルにまとめたもの。 * [`AGENTS.md`](/AGENTS.md) — 上記のそのまま使えるガイドを raw Markdown にしたもの。 * [`sitemap.md`](/sitemap.md) — すべてのドキュメントページとブログ記事の Markdown インデックス。 * [`sitemap.xml`](/sitemap.xml) — 公開されているすべてのページの標準 XML サイトマップ。 エージェントが必要とする製品領域がすでに分かっている場合は、スコープを絞ったインデックスを使用してください。 * [Overview](/docs/overview/llms.txt) * [Platform](/docs/platform/llms.txt) ([Dashboard](/docs/platform/dashboard/llms.txt)、[Locadex](/docs/platform/locadex/llms.txt)、[Core](/docs/platform/core/llms.txt)、[OpenAPI](/docs/platform/openapi/llms.txt) の用途別インデックスあり) * [CLI](/docs/cli/llms.txt) * [React](/docs/react/llms.txt) * [Vue](/docs/vue/llms.txt) * [Node.js](/docs/node/llms.txt) * [Python](/docs/python/llms.txt) * [Integrations](/docs/integrations/llms.txt) API 関連の作業では、インタラクティブなエンドポイントページをスクレイピングするのではなく、[OpenAPI operation バンドル](/docs/platform/openapi/llms-full.txt)または正式な [`openapi.yaml`](/openapi.yaml) 仕様を使用してください。 ドキュメントホストは、`/docs/llms.txt`、`/docs/llms-index.txt`、`/docs/llms-full.txt` を含むルートのファイルを `/docs` 配下でも配信します。すべてのドキュメントページは **raw Markdown** として取得できます。ページ URL に `.md` または `.mdx` を付加すると、レンダリングされた HTML を解析せずにクリーンなソースを取得できます。生成されたインデックスや検出用メタデータでは `.mdx` を使用します (例: `/docs/cli/quickstart.mdx`)。 ドキュメントを context として追加するには、ドキュメントの URL または `llms.txt` のリンクをエージェントの context に貼り付けるか、ドキュメントのインデックス作成に対応したツールでドキュメントを source として追加してください。 ## MCP サーバー [#mcp] エージェント が標準入出力経由のローカルな [Model Context Protocol](https://modelcontextprotocol.io) (MCP) connection でドキュメントを取得する必要がある場合は、公開されている [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) package をご利用ください。 ```json title=".mcp.json" { "mcpServers": { "generaltranslation-docs": { "command": "npx", "args": ["-y", "@generaltranslation/mcp@latest"] } } } ``` この package は、ドキュメントを一覧表示・取得するためのツールを提供します。よりシンプルにドキュメントへアクセスするには、エージェント を [機械可読なドキュメント](#point-agents)に直接向けてください。 プロジェクトの最新情報については、`https://api.gtx.dev/mcp` でホストされている MCP サーバー をご利用ください。トランスポートには streamable HTTP を使用します。 ホスト版のサーバーでは [Google Drive MCP ツール](/docs/integrations/google-drive/reference/mcp-tools) も提供しており、接続済みの プロジェクト の検索、Google Docs や Google Slides の翻訳、翻訳済み copy の進捗の polling が可能です。 お使いのツールの MCP config file (例: `.mcp.json`) に connection を追加してください。トランスポート名や設定フィールドはクライアントによって異なる場合があります。 ```json title=".mcp.json" { "mcpServers": { "generaltranslation": { "type": "http", "url": "https://api.gtx.dev/mcp" } } } ``` ### リモート API での認証 MCP クライアントの OAuth サインインフローで接続するか、シークレットヘッダー設定で `Authorization: Bearer ` を指定してください。API キーによる接続では、本番用のプロジェクトキー (`gtx-api-`)、開発用のプロジェクトキー (`gtx-dev-`)、および Organization key (`gtx-org-`) を使用できます。開発用キーを許可するかどうかは各ツールが決定します。runtime translation と [Google Drive MCP ツール](/docs/integrations/google-drive/reference/mcp-tools) は開発用キーを受け付けますが、他のツールは拒否する場合があります。 サーバーは、保護対象リソースおよび認可サーバーのメタデータを公開します。OAuth 対応クライアントは動的に登録を行い、Proof Key for Code Exchange (PKCE) を用いた Authorization Code フローで、Dashboard の同意画面を開きます。識別情報のクレームには `openid` と `profile` をリクエストし、クライアントがリフレッシュトークンを必要とする場合は `offline_access` をリクエストします。 `list_projects` でプロジェクト ID を確認し、それを `projectId` としてプロジェクト系ツールに渡してください。本番用のプロジェクトキーの場合は、`projectId` を省略すると自身のプロジェクトが使用されます。 接続したら、エージェントに `generaltranslation` MCP サーバーを使用するよう指示してください。例:「自分のプロジェクトを一覧表示して、そのうち 1 つのロケール設定を表示して。」 ## エディター別のヒント [#editor-tips] セットアップの大半はどのエージェントでも共通で、案内が異なるのは次の数か所だけです。 * **Cursor** — MCP サーバーを登録したうえで、「`generaltranslation` ツールを使って」と指示します。ドキュメントを情報源として追加するか、プロンプト内で `/llms.txt` を参照してください。 * **Claude Code** — ルートの `CLAUDE.md` を自動で読み込むため、[エージェントガイド](#agent-guide) をプロジェクトの `CLAUDE.md` にコピーしてください。MCP サーバーを登録し、「`generaltranslation` MCP サーバーを使って」と指示してください。 * **Copilot** — リポジトリ全体のガイダンスは指示ファイル (たとえば `.github/copilot-instructions.md`) に記述し、そこでドキュメント `/llms.txt` を参照してください。 ## ベストプラクティス [#best-practices] 機械的な i18n 作業において、エージェントは頼りになりますが、翻訳の品質や設定には依然として人の確認が必要です。次のように役割分担してください。 * **エージェントに任せる:** ユーザー向けの文言を [``](/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`) 、および動的な値や非公開の値が [``](/docs/react/reference/components/var) で囲まれていること。 * **エージェントに絶対にやらせない:** 変更を同期せずに生成された翻訳ファイルを編集すること、または CLI を使って原文を翻訳する代わりに、すでに翻訳済みの文字列をハードコードすること。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.