コーディングエージェントでセットアップする
CLI のエージェント向けガイドで、Claude Code、Codex、Cursor にプロジェクトへの Lingo.dev のセットアップを任せましょう。コピーして使えるプロンプト、AGENTS.md ブロック、lingo agent setup、lingo agent-guide を紹介します。
CLI には、Claude Code、Codex、Cursor などのコーディングエージェント向けガイドが付属しています。以下のプロンプトのいずれかをエージェントに渡してください。エージェントは lingo agent-guide を実行し、タスクに合ったガイドを読んで、CLI を使ってリポジトリ内で作業します。エンジンの用語集や GitHub App の接続など、アカウントに関する作業には Lingo.dev MCP server を使います。
ガイドは CLI に付属しているため、エージェントは常に実行中のバージョンに合ったガイドを読みます。翻訳を始める前に計画と見積もりを提示し、承認を待ちます。
プロンプト #
プロジェクトのルートで、エージェントにプロンプトを貼り付けてください。
Lingo.dev を最初からセットアップする #
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.エージェントは次の作業を行います。
- Lingo.dev の MCP ツールが使えるか確認します。使えない場合はサーバーを追加し、再起動してプロンプトをもう一度貼り付けるよう案内します。
- 技術構成を把握し、アプリが読み込むすべてのソースファイルを見つけ、その構成に対応するガイド(Rails、iOS、Android、Markdoc、メール、国際化ライブラリ、ドキュメントサイト)に沿って作業します。
- サインインを求めます。案内が表示されたら、ご自身のターミナルで
npx @lingo.dev/cli@latest loginを実行してください。会話には絶対に API キーを貼り付けないでください。 lingo initとlingo linkを実行します。プロジェクトに既存の翻訳がある場合は、プレースホルダーの破損、未翻訳のテキスト、用語の不統一を確認し、承認された箇所だけを修正します。- 計画と
lingo push --estimateを提示し、承認を得てから翻訳します。 - 新しいロケールをアプリに登録し、GitHub App の接続を提案します。
GitHub App を接続する #
Connect the Lingo.dev GitHub App to this repository. Run npx @lingo.dev/cli@latest agent-guide github and follow it.プロジェクトが未設定の場合、エージェントはまずセットアップを行います。次に、GitHub App がリポジトリにアクセスできるか確認し、できない場合は設定を修正するためのリンクを提示します。アプリが翻訳するタイミングを、マージ後かプルリクエスト内かで選べます。同意を得てから、設定を含むプルリクエストを作成します。
AGENTS.md ブロック #
lingo init と lingo agent setup は、プロジェクトのルートにある AGENTS.md に短いブロックを書き込みます。これにより、以降のすべてのエージェントセッションに、ローカライズ作業の前にガイドを読むよう伝えます。
<!-- lingo:begin -->
## Lingo.dev localization
This project is localized with Lingo.dev. The config is `.lingo/config.json` next to this file. Lingo.dev commands and workflows change between versions, so do not rely on what you remember about them.
Before any localization task (translating content, adding a locale, connecting GitHub, changing the glossary or tone of voice), run `npx @lingo.dev/cli agent-guide` from this directory and follow the guide it names. The guides ship with the CLI and describe the version you run.
This block is written by `lingo init` and `lingo agent setup`. Text between the markers is replaced on the next run; keep your own notes outside them.
<!-- lingo:end -->AGENTS.mdが存在しない場合は作成されます。マーカーの外側のテキストは保持され、次回以降の実行ではマーカーの間のテキストだけが置き換えられます。- 既存の
CLAUDE.mdにもブロックが追加されます。ただし、ブロックを含むAGENTS.mdをインポートしている場合(@AGENTS.md)は追加されません。CLAUDE.mdが新規作成されることはありません。 - ファイルを読み取れない場合、リンク先がプロジェクト外にある場合、またはマーカーが対になっていない場合は、警告を表示し、ファイルは変更しません。ファイルを修正して
lingo agent setupを再実行してください。 - ブロックを追加しない場合は、
lingo init --no-agents-mdを実行してください。
AGENTS.md または CLAUDE.md にブロックがないプロジェクトでエージェントが Lingo.dev のコマンドを実行すると、CLI は lingo agent setup -y を実行するよう促すメッセージを標準エラー出力に一行表示します。人が実行する場合や CI では表示されません。
lingo agent setup #
lingo agent setupこのマシン上のコーディングエージェント(Claude Code、Codex、Cursor、およびこのコマンドを実行しているエージェント)に Lingo.dev MCP server が設定されているか確認します。未設定のエージェントについては、それぞれ変更が必要な設定ファイルを示します。エージェントの設定を編集することはありません。MCP のセットアップの手順に沿ってサーバーを追加してください。プロジェクト内では、確認を求めたうえで AGENTS.md ブロックも書き込みます。
| フラグ | 動作 |
|---|---|
--client <name> | 検出されていなくても、指定したエージェントだけを確認します。claude-code、codex、cursor のいずれかを指定できます。繰り返し指定できます。 |
--dry-run | 変更予定の内容を表示し、何も書き込みません。 |
--status | 検出されたエージェントの設定状況を表示します。--client は無視されます。 |
-y, --yes | 確認せずにブロックを書き込みます。 |
確認対象のエージェントがない場合は、何も書き込まずに失敗します。
lingo agent-guide #
lingo agent-guide # the agent guide and the list of guides
lingo agent-guide setup # one guide名前を指定しない場合は、すべてのエージェントが最初に参照するガイド(CLI または MCP、サインイン、未完了の初期設定について)と、ガイドの一覧を出力します。名前を指定すると、そのガイドを出力します。該当する名前がない場合は、終了コード 1 で終了し、このバージョンで利用できるガイドの一覧を出力します。lingo guide は、@lingo.dev/react の利用者にガイドを提供します。
人が介在しないセッション #
クラウドや CI のセッションでは、エージェントがサインインせずに済むように LINGO_API_KEY を設定してください。この場合、エージェントはタスクのうち CLI で行う部分を実行し、MCP server のセットアップは行いません。最後のメッセージに、アカウントを使って行う必要がある残りの作業を一覧で表示します。これらはウェブアプリ、または MCP server が設定されたエージェントで完了できます。
請求関連の理由で翻訳が拒否された場合、CLI は、人の対応が必要なとき(クレジット不足、エンジンの上限到達、必要な機能がプランで利用できない場合)は終了コード 9、一日あたりのトークン割り当てを使い切ったときは終了コード 75 で終了します。理由と請求ページへのリンクも表示します。ガイドでは、どちらの終了コードでも処理を停止するようエージェントに指示しています。
エージェントからのレポート #
ガイドの改善に役立てるため、手順が失敗したときとタスクが終了したときに、lingo agent report を使って短いレポートを Lingo.dev に送信するようエージェントに求めています。レポートには、ガイドと手順、一〜二文の要約、エージェント名、関連付けられた組織とエンジンが含まれます。CLI は認証情報と機密値を取り除き、各テキストを 500 文字以内に切り詰めます。レポートが原因でタスクが失敗することはありません。誰もサインインしていない場合や、テレメトリが無効な場合(LINGO_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1、OTEL_SDK_DISABLED=true)は何も送信しません。