Set Up StringLane From Your Coding Agent

Paste this at your coding agent:

Read https://stringlane.app/docs/cli/agent-setup.md and set up StringLane for this project.

Everything below is the instruction set it will follow. It is worth reading first — it is short, and it is the thing that will be typing commands in your repository.

Instructions for the agent#

You are setting up StringLane in this repository: a localization engine that reads and writes ARB, iOS .strings/.stringsdict/.xcstrings, Android XML and i18next JSON through one parser and one validator.

Propose; never auto-apply. Every step below that changes anything is a separate yes. State the exact command, say what it will do, and wait. If the user declines a step, carry on with the next one — most of these are independent.

Do not edit locale files directly at any point, including before StringLane is installed. Four of the five formats escape, prefix or nest their values, so the bytes on disk are not the string.

Step 1 — Is there anything to localize here?#

Look for locale files: *.arb, *.xcstrings, *.strings, res/values*/strings.xml, or a locales/ directory of JSON. If you find none, say so and stop. StringLane has nothing to do in a repository with no localization, and installing it there is noise.

Step 2 — Is the CLI already installed?#

stringlane --version

Four outcomes, and the second is the one that gets misread:

• A version number. Go to step 3.
• Nothing at all, and exit 0. StringLane is not installed. On a host where the plugin is active, its resolver is on PATH and deliberately succeeds in silence when it finds nothing — a resolver that failed loudly would look to the hook protocol like a guard refusing an edit. Do not read exit 0 as installed.
• An npm error, a 404 or no network. Say which, and stop. Retrying changes neither.
• command not found. Nothing is installed and no resolver is on PATH. Propose the install below.

To install, propose this and wait for a yes:

npm install -g @stringlane/cli

It needs Node 22 or newer, and it is one JavaScript file with no runtime dependencies.

Step 3 — Which host are you running in?#

Work it out from what you can see: your own name, the directory your configuration lives in, the tool names you were given. Then take your row, and only yours.

If you cannot tell which host you are, ask. Guessing wrong writes a config file the real host never reads, which looks identical to working.

On the three plugin hosts, the plugin brings the MCP server and the write guard together and steps 4 and 5 are already done.

On every other host, setup mcp prints the entry and the exact file it belongs in. It does not write it, and --apply will not either: StringLane only merges into a config file for a host somebody has recorded, which today is Claude Code. Show the user the printed block and the path, and let them paste it. Then tell them the host has to be restarted before it will load a new MCP server.

Step 4 — The write guard#

This is the part an MCP server cannot do for itself. The server sees only its own tool calls; it has no idea you just wrote de.arb with a file tool. A hook does.

stringlane setup hooks --host <your host>

It prints the hook document and the file to paste it into. Report both, and say which of these your host gets, because they are different promises:

• Claude Code, Codex CLI — the write is held and the user is asked. Installed with the plugin; nothing more to do.
• Gemini CLI, Cursor — their hook protocol has no "ask", so the write is refused. The refusal names the tool to use instead and the command to remove the guard.
• Zed, OpenCode — no hook StringLane speaks. Run stringlane setup guard --host zed or --host opencode instead; it prints a block for that host's own permission table.
• VS Code Copilot — the hook installs and guards nothing yet, because its edit-tool names are not available as hook values. Say so plainly rather than implying protection.
• Windsurf — there is none. Its pre-write hook cannot send a message back to you, and a silent block teaches nothing. Say so and move on.

Whatever you install, stringlane setup hooks --host <host> --remove takes it back out, on every host.

Step 5 — The rules file#

This one writes into the user's own repository, so it works on every host:

stringlane setup rules --apply

It adds three rules about locale files to AGENTS.md, between two HTML-comment markers. Everything outside the markers is untouched, running it twice still leaves one block, and --remove takes exactly that block back out. Propose it; it is the only setup command here that writes without a paste.

Step 6 — The project itself#

stringlane init

Detects the format, the base locale and the paths, and writes stringlane.yaml. It asks first. Show the user what it detected before confirming — a wrong guess here is wrong for every later command.

Then get the state of things:

stringlane check

Report what comes back: which locales are behind, and which findings are structural. Do not start fixing them in this conversation unless asked.

Step 7 — Give it context, once#

If prepare_translation_plan reports keysWithoutDescription above zero, or stringlane check shows many locales at once, the highest-value thing you can do next is not translating. It is writing down what the product is and what each key means.

You have just read this codebase. That context is worth more here than anywhere else, and nobody recovers it later:

• set_project_context (or stringlane context --from) records what the product is, how it should sound, per-locale notes, and terms that must never be translated.
• describe_keys (or stringlane describe) records what individual keys are for. Translating a bare "Close" is a guess about part of speech, gender and register, and it is the single largest source of wrong translations.

Propose both. Neither is required, and both improve every locale and every later session.

Then stop#

Setup is done. Tell the user what is installed, what the guard on their host does and does not cover, and what stringlane check found. Do not begin translating unless they ask.

When they do, it is three calls in order — prepare_translation_plan, validate_translations, apply_translations — and the agent workflow is the page for it.

For the human reading this#

Three things worth knowing about what you just handed your agent.

Nothing here installs silently. The CLI's setup commands print by default; --apply writes only on Claude Code, and only into files whose format has been recorded from a real session. Everywhere else the change is bytes on your screen that you paste yourself, which means you read it first.

The write guard is not one feature. It is built out of whatever each host lets StringLane intercept, and the eight hosts offer four different amounts — including one where the answer is "none". Agent hosts has the table.

--remove always works, on every host, whether or not --apply did. Refusing to install is cautious; refusing to uninstall is a trap.