コーディングエージェントでセットアップする

Max PrilutskiyCEO 兼 共同創業者読了目安 1分

CLIには、Claude Code、Codex、Cursorなどのコーディングエージェント向けガイドが付属しています。以下のプロンプトのいずれかをエージェントに渡してください。エージェントはlingo agent-guideを実行し、タスクに合ったガイドを読んで、CLIを使ってリポジトリ内で作業します。エンジンの用語集やGitHub Appの接続など、アカウントに関する作業にはLingo.dev MCP serverを使います。

ガイドはCLIに付属しているため、エージェントは常に実行中のバージョンに対応したガイドを参照します。翻訳を始める前に計画と見積もりを提示し、承認を待ちます。

プロンプト #

プロジェクトのルートでエージェントにプロンプトを貼り付けてください。

Lingo.devをゼロからセットアップする #

text
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.

エージェントは次の作業を行います。

  1. Lingo.devのMCPツールが使えるか確認します。使えない場合はサーバーを追加し、エージェントを再起動してプロンプトをもう一度貼り付けるよう求めます。クラウドやCIのエージェントは、この手順とブラウザでのサインインを省略します。無人セッションを参照してください。
  2. 技術構成を把握し、アプリが読み込むすべてのソースファイルを見つけ、その構成に対応するガイドに沿って作業します(Rails、iOS、Android、Markdoc、メール、国際化ライブラリ、ドキュメントサイト)。
  3. サインインを求めます。指示が表示されたら、自分のターミナルでnpx @lingo.dev/cli@latest loginを実行してください。APIキーは決して会話に貼り付けないでください。
  4. lingo initとlingo linkを実行します。プロジェクトに既存の翻訳がある場合は、プレースホルダーの破損、未翻訳のテキスト、用語の不統一を確認し、承認された箇所だけを修正します。
  5. 計画とlingo push --estimateを提示し、承認を受けてから翻訳します。
  6. 新しいロケールをアプリに登録し、GitHub Appの接続を提案します。

GitHub Appを接続する #

text
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に短いブロックを書き込みます。これにより、以後のすべてのエージェントセッションで、ローカライズ作業の前にガイドを読む必要があることが伝わります。

markdown
<!-- 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を再実行してください。エージェントが検出されない場合は--client <name>を追加してください。
  • ブロックの追加を省略するには、lingo init --no-agents-mdを実行してください。

AGENTS.mdまたはCLAUDE.mdにブロックがないプロジェクトでエージェントがLingo.devのコマンドを実行すると、CLIはlingo agent setup -yの実行を促すメッセージを標準エラー出力に一行表示します。人が操作する場合やCIでの実行時には表示されません。

lingo agent setup #

bash
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確認せずにブロックを書き込みます。

--statusを指定しておらず、確認対象のエージェントもない場合は、何も書き込まずに失敗します。--clientでエージェントを指定してください。

lingo agent-guide #

bash
lingo agent-guide           # the agent guide and the list of guides
lingo agent-guide setup     # one guide

名前を指定しない場合は、すべてのエージェントが最初に読むガイド(CLIまたはMCP、サインイン、未完了の初期設定)と、ガイドの一覧を表示します。名前を指定すると、そのガイドを表示します。不明な名前を指定すると終了コード1で終了し、このバージョンで利用できるガイドの一覧を表示します。@lingo.dev/reactを使う人向けには、lingo guideに専用のガイドがあります。

無人セッション #

クラウドや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)は、何も送信されません。