Set up with a coding agent

Max PrilutskiyCEO & Co-Founder5 min read

The CLI ships guides written for coding agents such as Claude Code, Codex and Cursor. Give your agent one of the prompts below. It runs lingo agent-guide, reads the guide for the task, and does the work in your repository with the CLI. Account work, such as the engine's glossary or the GitHub App connection, goes through the Lingo.dev MCP server.

The guides come with the CLI, so an agent always reads the guide for the version it runs. The agent shows you a plan and an estimate before it translates anything, and waits for your yes.

Prompts #

Paste a prompt into your agent from the project root.

Set up Lingo.dev from scratch #

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

The agent:

  1. Checks that it has the Lingo.dev MCP tools. If it doesn't, it adds the server and asks you to restart it and paste the prompt again. A cloud or CI agent skips this and the browser sign-in; see Sessions without a person.
  2. Works out the stack and finds every source file the app loads, and runs the guide for that stack (Rails, iOS, Android, Markdoc, emails, an i18n library or a docs site).
  3. Asks you to sign in. Run npx @lingo.dev/cli@latest login in your own terminal when it asks; never paste an API key into the conversation.
  4. Runs lingo init and lingo link. If the project already has translations, it checks them for broken placeholders, untranslated text and inconsistent terms, and fixes only what you accept.
  5. Shows the plan and a lingo push --estimate, and translates after your yes.
  6. Registers the new locales in the app and offers to connect the GitHub App.

Connect the GitHub App #

text
Connect the Lingo.dev GitHub App to this repository. Run npx @lingo.dev/cli@latest agent-guide github and follow it.

The agent sets the project up first if it isn't, checks that the GitHub App reaches the repository and gives you the links to fix it if not, lets you choose whether the App translates after merge or in pull requests, and opens the pull request with the config only after you agree.

The AGENTS.md block #

lingo init and lingo agent setup write a short block to AGENTS.md in the project root, so every later agent session knows to read the guides before localization work:

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 is created when it is missing. Text outside the markers is kept, and a later run replaces only the text between them.
  • An existing CLAUDE.md gets the block too, unless it imports an AGENTS.md that has it (@AGENTS.md). CLAUDE.md is never created.
  • A file is left unchanged, with a warning, when it can't be read, links outside the project, or has markers that don't pair up. Fix the file and run lingo agent setup again, adding --client <name> if it doesn't detect your agent.
  • To skip the block, run lingo init --no-agents-md.

When an agent runs a Lingo.dev command in a project whose AGENTS.md or CLAUDE.md has no block, the CLI prints one line on stderr telling it to run lingo agent setup -y. People and CI never see it.

lingo agent setup #

bash
lingo agent setup

Checks whether the coding agents on this machine (Claude Code, Codex and Cursor, plus the one it runs inside) have the Lingo.dev MCP server, and names the config file to change for each one that doesn't. It never edits agent configs; add the server with the steps in MCP setup. Inside a project it also writes the AGENTS.md block, after asking.

FlagEffect
--client <name>Check only this agent, even if it wasn't detected: claude-code, codex or cursor. Repeatable.
--dry-runShow what would change and write nothing.
--statusShow what is set up for the detected agents. Ignores --client.
-y, --yesWrite the block without asking.

Without --status, it fails without writing anything when there is no agent to check, so name one with --client.

lingo agent-guide #

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

Without a name, prints the guide every agent starts from (CLI or MCP, signing in, unfinished onboarding) and lists the guides. With a name, prints that guide. An unknown name exits 1 and lists the guides this version has. People using @lingo.dev/react have their own guides under lingo guide.

Sessions without a person #

In a cloud or CI session, set LINGO_API_KEY so the agent doesn't need to sign in. Such an agent does the CLI part of the task and doesn't set up the MCP server. Its last message lists what is left that needs the account, which you can finish in the web app or with an agent that has the MCP server.

When a translation is refused for billing, the CLI exits 9 if a person has to act (out of credits, at the engine limit, or a plan feature is missing) and 75 if the daily token allowance is used up. It prints the reason and the link to the billing page. The guides tell agents to stop on either code.

Reports from agents #

The guides ask agents to send Lingo.dev a short report with lingo agent report when a step fails and when a task ends, so we can improve the guides. A report holds the guide and step, a one- or two-sentence summary and what the agent proposed, the agent's name, and the linked organization and engine. The CLI removes credentials and secret values from the summary and the proposal and cuts each to 500 characters; the guides tell agents to keep code, file contents and secrets out of every field. A report never fails the task, and it sends nothing when nobody is signed in or telemetry is off (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or OTEL_SDK_DISABLED=true).