# 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)をご利用ください。* ## 開始プロンプト [#start-prompt] 以下のプロンプトを使うと、プロジェクトに General Translation を追加するエージェントセッションを開始できます。エージェントはドキュメントのエントリポイントを読み、[`gt login`](/docs/cli/reference/commands/login) でサインインし、プロジェクトを選択して最初の翻訳を実装し、動作を検証します。エージェントは [`gt login`](/docs/cli/reference/commands/login) を通じて General Translation プラットフォームを利用するため、このプロンプトでは API キーの入力を求めず、最初にこのコマンドを実行します。[generaltranslation.com](https://generaltranslation.com) の **Setup for Agents** ボタンを押すと、このテキストがそのままコピーされます。同じテキストは [`/agent-prompt.md`](/agent-prompt.md) でもプレーンテキストとして提供されています。プロンプトで指定している [`init`](/docs/cli/reference/commands/init) コマンドは、新規作成した `create-next-app` 上で `gt` 2.24.0 を使用して検証済みです。このコマンドは対話なしで `gt-next` をインストールし、ルートレイアウトに [`GTProvider`](/docs/react/reference/components/gt-provider) を、`next.config.ts` に `withGTConfig` を追加します。さらに `loadTranslations.js` と `gt.config.json` を作成し、最後に成功イベントを出力して終了します。 ````markdown title="agent-prompt.md" # Get started with General Translation I landed on https://generaltranslation.com and clicked "Setup for Agents". Help me add General Translation to my app, website, or content, and get a real translation working. Inspect the project you have access to, choose the appropriate integration with me, and implement it. Continue through setup, translation, and verification rather than stopping at a plan. ## About General Translation General Translation (GT) combines open-source internationalization libraries, a translation CLI, and a hosted translation platform. Source content stays in your code or content files. The libraries render translations and format locale-sensitive values; the platform generates and manages translations. Locadex is an optional hosted agent that connects to GitHub and maintains localization through pull requests. - Website: https://generaltranslation.com - Dashboard: https://dash.generaltranslation.com - Open-source libraries and CLI: https://github.com/generaltranslation/gt - Documentation entry point: https://generaltranslation.com/llms.txt - Complete documentation index: https://generaltranslation.com/llms-index.txt - API specification: https://generaltranslation.com/openapi.yaml Fetch the documentation entry point first, then the quickstart and references relevant to this project. Documentation pages are available as raw Markdown by appending `.mdx` to the page URL. Use the complete index when you need a page that is not in the curated index. Read current docs and installed command help instead of guessing APIs, flags, or framework setup. `gt auth` is not a command in current releases; use `gt login`. `gt generate` writes source templates without calling the API and is registered when the CLI detects `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, `gt-node`, `gt-vue`, `gt-flask`, or `gt-fastapi`. Use `gt translate` for hosted translation. ## Work with me Read this entire prompt before acting. Respect the repository's instructions, package manager, architecture, design system, and existing changes. First inspect the repository for the framework, router, app directory, existing i18n library, GT configuration, source language, and build scripts. In a monorepo, identify the specific app or content directory; do not run setup at the workspace root. Do not ask me things you can determine from the code. If the intended project is unclear, ask one question: "What would you like to translate?" Offer concrete choices: this app or website, documentation or content files, a backend service, a connected content platform, or a small new demo. Include "Not sure, help me decide." Prefer your interactive question tool when available. If no repository is open, help me open one or choose a small demo before scaffolding anything. Ask for missing decisions one at a time: source language, target languages, and the first page or workflow to translate. Preserve existing locale choices; do not assume the source language is English or invent target markets. If I want help choosing, propose one target language for the first working example. Reuse an existing i18n setup where appropriate instead of automatically migrating the entire application. Explain the next meaningful step briefly, then do the work. Ask when a choice affects which organization/project you use, creates an unwanted duplicate, or changes the agreed scope. Once I have chosen the project, languages, and scope, proceed with the setup and translation needed for that outcome. ## Choose the right integration Read the matching quickstart before making framework changes: | Project | Integration | Quickstart | | --- | --- | --- | | Next.js App Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-quickstart.mdx | | Next.js Pages Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-pages-router-quickstart.mdx | | React SPA, including Vite | `gt-react` | https://generaltranslation.com/docs/react/react-spa-quickstart.mdx | | Server-rendered React | `gt-react` | https://generaltranslation.com/docs/react/react-quickstart.mdx | | TanStack Start | `gt-tanstack-start` | https://generaltranslation.com/docs/react/tanstack-start-quickstart.mdx | | React Native or Expo | `gt-react-native` | https://generaltranslation.com/docs/react/react-native-quickstart.mdx | | Vue | `gt-vue` | https://generaltranslation.com/docs/vue/quickstart.mdx | | Node.js backend | `gt-node` | https://generaltranslation.com/docs/node/quickstart.mdx | | Python backend | Follow the Python SDK guide | https://generaltranslation.com/docs/python/quickstart.mdx | | JSON, MDX, Markdown, YAML, or existing translation files | `gt` CLI | https://generaltranslation.com/docs/cli/quickstart.mdx | | Lower-level JavaScript translation | `generaltranslation` | https://generaltranslation.com/docs/platform/core/quickstart.mdx | For Mintlify, Sanity, Storyblok, or Google Drive, fetch https://generaltranslation.com/docs/integrations/llms.txt and follow that integration's quickstart. Do not apply a React setup wizard to a content integration. If I want GT to continuously maintain localization through GitHub, read https://generaltranslation.com/docs/platform/locadex/quickstart.mdx and walk me through connecting the repository and creating the appropriate automation. Do not enable auto-merge or change paid plans without my direction. ## Run the CLI without questions The CLI is interactive. When `init` or `configure` is missing an answer, it does not fail: it asks the question in the terminal and waits, with no timeout. In an agent session that wait never ends. So in this session: - Always pass `--no-interactive`. With it, a missing answer is a hard error that lists the flags still needed and changes no file. - Pass a flag for every question before you run the command. `--defaults` accepts the recommended local choices in one flag; you still need `--locales` and, outside local Vite and TanStack Start setups, `--dev-credentials` or `--no-dev-credentials`. Pass explicit `--default-locale`, `--locadex` or `--no-locadex`, `--react-setup` or `--no-react-setup`, and `--file-formats` values only when you want to override the defaults. Local Vite and TanStack Start setups default to `--no-live-translations`; pass `--live-translations` to opt in. Never combine the `--[no-]live-translations` and `--[no-]dev-credentials` flag families. - Pass `--json` to `init` and `configure`. It implies `--no-interactive`, writes one result event to stdout and the rendered screen to stderr. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` have no `--json` flag; `translate` prints a progress screen with terminal control sequences, so judge it by its exit code and by the files it writes: `public/_gt/.json`, `gt-lock.json` and `gt.config.json`. - If a command prints a question and stops, you are inside an interactive prompt. End the process and rerun it with `--no-interactive` and the missing flag. Never type an answer into it, and never run a command whose questions you have not answered with flags. - `gt login` is the one step that needs a person: it opens a browser and waits for the sign-in to finish. If no browser can open from this session, run it with `--no-browser`, give me the URL it prints, and wait for me to confirm. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` ask nothing when their flags are complete; a missing required flag is an error. ## Sign in with `gt login` Use account login for local CLI authentication. Do not begin by asking me to find and paste an API key. The examples below use `npx gt@latest` to avoid an old local CLI. Use the project's package manager or a current installed `gt` binary when appropriate. Inspect the version and available commands first: ```bash npm view gt version npx gt@latest --help npx gt@latest login --help ``` The CLI has no `--version` flag. `translate` prints "CLI Version: x.y.z" in its banner; `init --json` prints no banner. Read the published version with `npm view gt version` and the installed one from `node_modules/gt/package.json`. This workflow requires a CLI release with `login`, `whoami`, and `api-key create`. If the installed CLI lacks them, check the latest published release. If they are still unavailable, explain the release blocker and continue with local integration work that does not require credentials. Do not silently substitute the older `gt auth` flow, invent flags, or install an unpublished branch into my project. Check for an existing session with `npx gt@latest whoami`. If sign-in is needed, run: ```bash npx gt@latest login ``` Let me complete signup/sign-in and authorization in the browser. Keep the command running while approval is pending. In a remote or headless terminal, use: ```bash npx gt@latest login --no-browser ``` Show me the verification URL and code returned by that command; wait for successful authorization, then verify with `npx gt@latest whoami`. Do not ask for my password or extract OAuth tokens. Login authenticates the CLI; it does not by itself configure the app's project or create its runtime credentials. ## Select a project and create the credentials we need Reuse an existing configured project if it is the intended one. Check for conflicting project IDs in configuration and environment variables without printing secret values. Do not overwrite existing credentials or create another key unnecessarily. サポート対象の新規アプリでは、ログイン後にアプリのディレクトリからセットアップウィザードを実行し、すべての質問にフラグで回答します。Next.js App Router アプリをローカルでセットアップし、翻訳をリポジトリに保存して既存のプロジェクトを再利用する場合は次のとおりです: ```bash npx gt@latest init --no-interactive --json --defaults \ --default-locale --locales \ --no-locadex --react-setup --file-formats none \ --no-dev-credentials --project-id ``` This run asks nothing, installs gt-next, adds GTProvider to the root layout, adds withGTConfig to next.config.ts, creates loadTranslations.js and gt.config.json, and ends with `{"type":"result","command":"init","outcome":"success"}`. The wizard does not wrap any page text in ``, even though its completedSteps list says "wrapped JSX content". Internationalize every page yourself in step 4 of the implementation section. The wizard runs biome on the files it changes and may replace the project's indentation with tabs; restore the project's formatting. Ignore the warning "Unexpected export type in ./next.config.ts" when withGTConfig() was added correctly. Review the wizard's changes against the framework quickstart: automatic framework setup is experimental. `--defaults` covers local storage and the translations directory; pass `--storage` and `--translations-dir` only for other values. `--no-dev-credentials --project-id ` writes projectId to gt.config.json and creates no env file. Use it when no development key is wanted. If you already have a development key, add `NEXT_PUBLIC_GT_PROJECT_ID` and `NEXT_PUBLIC_GT_DEV_API_KEY` to `.env.development.local` yourself. `--dev-credentials --project-id ` saves a new development key and the project ID to `.env.local` instead; `--create-project --org-id --project-name ` creates the project first. `--no-react-setup` is for an app that already has the GT library; on an app without one it fails with "No GT runtime is installed, so select at least one file format to translate", which is right, since there would be nothing to translate. Pass `--locadex` only if we agreed to use hosted automation. Before a production build, move the development key (`NEXT_PUBLIC_GT_DEV_API_KEY` or `GT_DEV_API_KEY`) from `.env.local` to `.env.development.local`: `next dev` loads that file and `next build` does not, and a production build refuses to run with a development key present. A production build that ships local translation files needs no key. If the app already has framework setup, configure it directly from the docs. Use the authenticated CLI to discover resources: ```bash npx gt@latest api /v2/projects npx gt@latest api /v2/orgs ``` Follow pagination when present by passing `nextCursor` as `?cursor=`. `/v2/orgs` lists the organizations the signed-in user belongs to (an API key sees only its own). Creating a project also needs the `org:projects:create` permission in that organization; when `project create` is refused, ask me which organization to use or create the project in the Dashboard at https://dash.generaltranslation.com. Use actual returned IDs. Ask me to select when the destination is ambiguous. If my new account has no suitable organization, guide me through creating one at https://dash.generaltranslation.com, then retry discovery. When a new project is needed in the chosen organization: ```bash npx gt@latest project create \ --org-id \ --name \ --default-locale ``` Use the returned project ID. `project create` may require an organization key; read `npx gt@latest project create --help` first and fall back to creating the project in the Dashboard. For endpoint details or a missing higher-level command, inspect `npx gt@latest api --spec` and the current API docs before making a request. Local CLI operations can use the login session. Create separate project keys only where a runtime or unattended CI workflow needs one. Inspect `npx gt@latest api-key create --help` first. The command requires a key name and explicit permissions. A development runtime key needs `project:translations:generate`; a standard file translation workflow needs `project:files:read`, `project:files:write`, and `project:translations:enqueue`. Verify any additional operations against the API specification; do not grant every permission by default. `gt api-key create` prints the secret once to stdout. Capture that output directly into protected, ignored local configuration or the intended secret store without displaying it in tool output, chat, or logs. Use `--project-id` for the selected project, `--name` for its purpose, and `--permission` for the required permissions. Confirm success and the variable names without showing the key. Keep these credential roles distinct: - CLI/CI and server credentials use `GT_API_KEY` and `GT_PROJECT_ID`. Never put `GT_API_KEY` in browser code or a public-prefixed variable. - Development runtime translation uses `GT_DEV_API_KEY` and a project ID. Browser frameworks may need their documented public prefix, such as `VITE_GT_DEV_API_KEY`; for Next.js the wizard writes `NEXT_PUBLIC_GT_PROJECT_ID` and `NEXT_PUBLIC_GT_DEV_API_KEY`, and the CLI reads that project ID too, so `GT_PROJECT_ID` is only needed in CI. Only expose the narrowly scoped development key where the framework guide requires it; do not ship development credentials in production browser bundles. - OAuth credentials belong in the CLI's credential store. Do not copy them into the app or CI. Ensure local environment files are ignored by Git. Use placeholders in committed examples. Preserve unrelated environment settings. Logging in locally does not authenticate CI or a deployed server. ## Implement a complete first translation 1. Install the integration that matches the detected stack. For an existing project, make targeted changes and preserve its current behavior. 2. Create or update `gt.config.json` with the agreed source and target locales, source paths, and file mappings. Use the current configuration reference: https://generaltranslation.com/docs/cli/reference/config.mdx. Preserve existing settings. Configure translation output and loading together; for example, a Vite SPA's imported translation files must live within its source tree. Do not copy one framework's output path or provider setup into another framework. Add the translation output directory (for example `public/_gt/`) to `.gitignore` when translations are not committed. 3. Follow the framework's initialization and routing guide. Next.js App Router and Pages Router differ; React SPAs use `initializeGTSPA` before rendering; server runtimes need request-aware locale handling. Read the installed version's APIs before implementing them. 4. Internationalize the agreed page or workflow, including visible text, validation, placeholders, accessible labels, and metadata where relevant. In React, use `` for coherent static JSX. For standalone strings in gt-next, use `useGT()` in client components and in synchronous server components, and `getGT()` from `gt-next/server` in async server components and in `generateMetadata`. `useGT()` returns the function directly. For Next.js metadata, replace the static `metadata` export with `export async function generateMetadata()` that calls `getGT()` from `gt-next/server` and returns the translated title and description. Use `` or the framework's interpolation API for dynamic values; keep private values out of translation source. Use locale-aware number, date, currency, and plural handling. Follow the matching Vue, Node, or Python APIs for those stacks. 5. Add a language switcher to a suitable place in an app's existing UI. In gt-next, `` from `gt-next` renders directly inside a server component page; it carries its own client boundary. Give it an `aria-label` through `useGT()`. Preserve navigation and verify the selected locale survives navigation or reload as documented. For a backend or content-only project, verify locale selection and translated output through its actual API or content workflow instead. 6. Add useful context for ambiguous copy. Use the `context` prop on `` and the `$context` option in `gt()` and `getGT()` calls. `$context` on `` is a deprecated alias that the CLI flags when it scans the source. Preserve product names and terminology. Do not send secrets or runtime user data as translation source. For content files, preserve frontmatter, links, variables, and formatting according to the format guide. 7. Inspect the translation scope with `npx gt@latest translate --dry-run`, then run `npx gt@latest translate` for the agreed languages and scope. If this would unexpectedly translate a large corpus or exceed the agreed scope, clarify that before submitting it. `gt translate` also writes `gt-lock.json` and a `_versionId` into `gt.config.json`; commit both. Use the connected-platform workflow instead when the integration requires one. ## Verify and finish 型チェック（`npx tsc --noEmit`）と本番環境向けビルド（`next build`）を実行してください。lint とテストは、プロジェクトにすでに定義されている場合にのみ実行してください。ブラウザツールが使える場合は、アプリを起動して、翻訳が実際にどう表示・動作するかを確認してください。ソースロケールとターゲットロケールを切り替え、ページ遷移や再読み込みを行い、補間とレイアウトを確認します。`Accept-Language` ヘッダーも Cookie もないリクエストはデフォルトロケールでレンダリングされ、翻訳の参照ごとに "gt-next: No locale could be determined" という警告が 1 件ずつログに出力されます。ヘッダーを付けずに curl を実行した場合、これは想定どおりの動作です。ターゲットロケールを確認するには、`Accept-Language: ` または `Cookie: generaltranslation.locale=` を送信してください。選択した言語で必要な場合は、長いテキストや右から左（RTL）のレイアウトも確認してください。バックエンドやコンテンツ系のプロジェクトでは、実際に翻訳されたレスポンスやファイルを確認してください。ブラウザでの検証を実施できなかった場合は、検証済みと報告しないでください。 セットアップや Runtime のエラーを解消してから、インテグレーションを完了としてください。行き詰まった場合は、プロジェクトやキーを何度も作り直すのではなく、関連するリファレンスを取得し、コマンドのエラー内容を調べてください。 事前生成された翻訳を使用するアプリケーションでは、既存のビルドより前に翻訳が実行され、生成されたファイルを Runtime で利用できるように本番環境のワークフローを整えてください。既存のビルドステップはそのまま残し、CI の secret 名をドキュメントに記載し、選択したインテグレーションのローカルファイルまたは CDN に関する要件を確認してください。翻訳がコミット済みで CI 用のキーがない場合は、ビルドスクリプトを変更しないでください。ソーステキストを変更するたびに、ログインセッションを使ってローカルで `npx gt@latest translate` を実行し、`public/_gt/.json`、`gt-lock.json`、`gt.config.json` をコミットしてください。`npx gt translate` をビルドスクリプトに追加するのは、ファイル書き込みと翻訳キューの権限を持つ `GT_API_KEY` が CI に設定されている場合に限ります。`--publish` は、選択した CDN ワークフローで必要な場合にのみ使用してください。私が依頼しない限り、本番環境へのデプロイやプルリクエストのマージは行わないでください。 最後に、簡潔な引き継ぎ内容をまとめてください。変更内容、設定したプロジェクトとロケール、実行方法、実際に検証した内容、私が対応すべき残りの作業を記載してください。関連するドキュメントと Dashboard へのリンクは含めますが、認証情報は含めないでください。目指すのは、私のプロジェクトで翻訳が正しく動作し、今後も最新の状態に保つ方法が明確になっていることです。 ```` ## すぐ使えるエージェントガイド [#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` - **TanStack Start** → `gt-tanstack-start` - **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 For a new setup, run from the app directory with `--no-interactive` and a flag for every question. Without `--no-interactive`, a missing answer opens a question in the terminal and the command waits for it; with it, a missing answer is an error that lists the flags still needed and changes no file: ```bash npx gt init --no-interactive --json --defaults --default-locale en --locales fr es --no-locadex --react-setup --file-formats none --no-dev-credentials ``` For a local Vite or TanStack Start setup, replace `--no-dev-credentials` with `--no-live-translations`. Do not pass both credential flag families. The wizard detects the framework, creates or updates `gt.config.json`, and can select/create a project and provision a development runtime key. Creating a project or key without a tooling key or saved login signs in first, which a person must approve. Framework rewrites are experimental and need review. Review [init flags and side effects](/docs/cli/reference/commands/init) before running it. 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. For a manually configured app, have the developer run `npx gt login`, then bind an existing project with `projectId` in the config or `GT_PROJECT_ID` in the environment. Login does not select a project or write env files; do not rerun init just to authenticate. For CI, commit the config and inject a separately scoped tooling key through the CI secret store: ```bash GT_API_KEY="your-api-key" # 生成だけでなく CLI ワークフロー全体の権限を付与 GT_PROJECT_ID="your-project-id" ``` CLI login, runtime development keys, and CI tooling keys are separate. SDKs do not read CLI sessions; init's development runtime key does not replace `GT_API_KEY`. Never commit keys or include them in deployed browser/mobile bundles. Read [CLI credentials](/docs/cli/guides/configuring#credentials) before configuring authentication. Require human approval for login and key creation; `--no-browser` and quiet mode do not make login unattended. ## 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()` を呼び出します ``` Keep all locale configuration in `gt.config.json` — do not scatter locale lists across the codebase. ## Commands | Command | When to run | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npx gt init` | Guided setup; runs headless with `--no-interactive` and flags. Can change framework files, dependencies, config, and runtime credentials. | | `npx gt configure` | Configuration without the React rewrite; accepts the same flags except framework setup. May install dependencies and provision runtime credentials. Write config manually for config-only changes. | | `npx gt login` | Have the developer approve account access for CLI work. | | `npx gt translate` | To translate the project via the General Translation API. Run in CI **before** building for production; add `--save-local` only when local edits should sync first. | | `npx gt generate` | To write source templates for manual translation without calling the API. Available for the supported packages listed in the [`gt generate`](/docs/cli/reference/commands/generate) reference. | | `npx gt translate --dry-run` | To inspect the translation scope without calling the API or writing translation files. | | `npx gt api --list` | To list the API operations bundled with the installed CLI. | | `npx gt api --spec ` | To inspect one bundled API operation by operation ID, specification path, or concrete request path. Omit the endpoint for the full specification. | | `npx gt api ` | To make an authenticated raw API request from a script or terminal. | | `npx gt project create --org-id --name --default-locale ` | With approval, create a project using a signed-in user or Organization key authorized for org:projects:create. | | `npx gt project status ` | To inspect a translation or project context-generation job. | 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 `` (or `useGT()`/`getGT()` for standalone strings) as you write it. - With authorization to send content for hosted translation, 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 ``, and add `context` when a string is ambiguous. - After deliberately editing a generated translation file, run `npx gt save-local` before downloading translations again, or pass `--save-local` to the next translation run. Don't: - Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead. - Edit generated translation files without syncing the changes; a later download can overwrite unsaved edits. - Commit or expose API keys, capture key-creation stdout in shared logs, or mint credentials without explicit approval. - Duplicate the locale configuration outside `gt.config.json`. ## Links - [`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) — ロケール、コンテキスト、静的コンテンツと動的コンテンツ。 - アカウント関連のコマンド: [`gt login`](/docs/cli/reference/commands/login)、[`gt api-key create`](/docs/cli/reference/commands/api-key-create)。 - 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 にしたもの。 * [`agent-prompt.md`](/agent-prompt.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] プロジェクトの最新情報や Context Management については、`https://api.gtx.dev/mcp` でホストされている [Model Context Protocol](https://modelcontextprotocol.io) (MCP) サーバー をご利用ください。トランスポートには streamable HTTP を使用します。 このサーバーの Context Management ツールを使うと、Context Group、その用語集の用語や カスタムプロンプト、インポートとエクスポート、プロジェクトへの割り当てについて、一覧表示・作成・更新を行えます。これらのツールは [Context Management API](/docs/platform/openapi/reference/context-management/list-groups) と同じ機能を備えています。 ホスト版のサーバーでは [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-`) と Organization キー (`gtx-org-`) を使用できます。既存の `gtx-dev-` キーは、引き続きプロジェクトキーとして認証されます。各ツールは、要求された操作に対するキーの権限を確認します。エージェントが必要とするツールに合わせて、[カスタムキー権限](/docs/platform/dashboard/reference/api-keys)を設定してください。 `list_orgs` で Organization ID を、`list_projects` でプロジェクト ID を確認します。これらの検出用ツールには、リソースの権限は不要です。返された ID は、`orgId` および `projectId` として他のツールに渡してください。プロジェクトキーと Organization キーで検出できるのは、それぞれに紐づくリソースのみです。また、プロジェクトキーの場合は、`projectId` を省略すると自身のプロジェクトが使用されます。 Context Management ツールを使用するには、`org:context:read` または `org:context:write` が必要です。Organization キーに対応する **Context** 権限を付与するか、MCP の OAuth サインイン時に同じ Organization の Context へのアクセスを承認してください。プロジェクトキーではこれらのツールを使用できません。`list_context_groups` と `create_context_group` には `orgId` を渡し、既存のグループを操作するツールには `groupId` を渡してください。 MCP リクエストの本文は最大 100 MiB です。ツールによっては、入力に対してさらに小さい上限が適用される場合があります。 接続したら、エージェントに `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` のひな形を作成すること。ただし、キーやプロジェクトを作成する `--dev-credentials` または `--create-project` を指定して [`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.