코딩 에이전트로 설정하기
CLI에는 클로드 코드, 코덱스, 커서 같은 코딩 에이전트를 위한 가이드가 포함되어 있습니다. 아래 프롬프트 중 하나를 에이전트에 전달하세요. 에이전트가 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, 아이오에스, 안드로이드, 마크독, 이메일, 국제화 라이브러리 또는 문서 사이트입니다.
- 로그인을 요청합니다. 안내가 나오면 본인의 터미널에서
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를 다시 실행하세요. 에이전트가 감지되지 않으면--client <name>를 추가하세요. - 블록 작성을 건너뛰려면
lingo init --no-agents-md를 실행하세요.
AGENTS.md 또는 CLAUDE.md에 블록이 없는 프로젝트에서 에이전트가 Lingo.dev 명령을 실행하면, CLI는 lingo agent setup -y를 실행하라는 안내를 표준 오류로 한 줄 출력합니다. 사용자와 지속적 통합 환경에는 이 안내가 표시되지 않습니다.
lingo agent setup #
lingo agent setup이 컴퓨터의 코딩 에이전트인 클로드 코드, 코덱스, 커서와 현재 명령이 실행되는 에이전트에 Lingo.dev MCP server가 설정되어 있는지 확인합니다. 설정되지 않은 에이전트마다 변경해야 할 설정 파일을 알려 줍니다. 에이전트 설정을 직접 수정하지는 않으므로, MCP 설정의 절차에 따라 서버를 추가하세요. 프로젝트 안에서는 사용자의 확인을 받은 뒤 AGENTS.md 블록도 작성합니다.
| 플래그 | 동작 |
|---|---|
--client <name> | 감지 여부와 관계없이 지정한 에이전트만 확인합니다: claude-code, codex 또는 cursor. 여러 번 지정할 수 있습니다. |
--dry-run | 변경될 내용만 표시하고 실제로 기록하지는 않습니다. |
--status | 감지된 에이전트의 설정 상태를 표시합니다. --client는 무시합니다. |
-y, --yes | 확인을 요청하지 않고 블록을 작성합니다. |
--status가 지정되지 않은 상태에서 확인할 에이전트가 없으면 아무것도 기록하지 않고 실패합니다. 이 경우 --client로 에이전트를 지정하세요.
lingo agent-guide #
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에 있습니다.
사용자 개입 없는 세션 #
클라우드 또는 지속적 통합 세션에서는 에이전트가 로그인할 필요가 없도록 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) 아무것도 전송하지 않습니다.