코딩 에이전트로 설정하기

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 처음부터 설정하기 #

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 도구가 있는지 확인합니다. 없으면 서버를 추가하고, 에이전트를 다시 시작한 뒤 프롬프트를 다시 붙여 넣도록 요청합니다.
  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를 다시 실행하세요.
  • 블록 작성을 건너뛰려면 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동의를 묻지 않고 블록을 작성합니다.

확인할 에이전트가 없으면 아무것도 작성하지 않고 실패로 종료합니다.

lingo agent-guide #

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

이름을 지정하지 않으면 모든 에이전트가 처음 참고하는 안내서(CLI 또는 모델 컨텍스트 프로토콜, 로그인, 미완료 온보딩)를 출력하고 안내서 목록을 표시합니다. 이름을 지정하면 해당 안내서를 출력합니다. 알 수 없는 이름을 지정하면 코드 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) 아무것도 전송하지 않습니다.