Locize for AI agents

Conventions and setup for using Locize from AI coding agents (Claude Code, Cursor, VS Code, and any MCP-compatible client) — so an agent translates, reviews, and lints terminology to your project's standards, right in your editor.

There are two halves, and they live in different repos:

	Where	What it covers
Setting i18n up	i18next-localization skill	Hardcoded strings → localized app
Translating well	this repo	Glossary, tone, translation memory

To install the setup skill:

npx skills add i18next/i18next-cli

It ships with i18next-cli so it stays version-matched to the commands it drives. The rest of this repo is what governs the translations afterwards.

Install as a plugin

Everything in this repo, plus the i18next-localization skill and the Locize MCP server, ships as one plugin. The MCP server authenticates via OAuth on first use (or a Personal Access Token if you prefer to configure it by hand).

# Claude Code
/plugin marketplace add locize/locize-agents
/plugin install locize@locize

# GitHub Copilot CLI (reads the same plugin layout)
copilot plugin marketplace add locize/locize-agents

# Gemini CLI
gemini extensions install https://github.com/locize/locize-agents

# Cursor: Settings > Plugins > add from GitHub, or the Cursor Marketplace listing

What you get:

Skill / server	What it does
i18next-localization	Hardcoded strings to a localized app (vendored from i18next-cli; refresh with scripts/sync-skill.sh)
locize-translation-conventions	Translate, review and lint terminology against the project's glossary, style guide and translation memory
MCP server locize	https://mcp.locize.app: 26 tools for translations, context (glossary, style guide, TM, screenshots) and versions

Privacy policy: https://www.locize.com/privacy. Support: https://www.locize.com/support or support@locize.com.

Conventions

This repo is the canonical home of the agent-convention snippets. Drop the one that matches your tool into your project, or copy the shared rules into your existing CLAUDE.md / AGENTS.md / .cursorrules.

• CLAUDE.md — for Claude Code
• AGENTS.md — generic (Codex, and tools that read AGENTS.md)
• .cursorrules — for Cursor

They all carry the same rules; pick the file your tool reads.

Connect the Locize MCP server

The conventions assume your agent can reach the Locize MCP server:

# Claude Code
claude mcp add --transport http locize https://mcp.locize.app

For Claude Desktop, Cursor, VS Code, and other clients, add https://mcp.locize.app as a custom MCP connector and complete the OAuth flow, or use a Personal Access Token (read scope is enough for the context tools below). Full setup: https://www.locize.com/docs/integration/mcp.

The context tools these conventions use

All read-only, read scope:

Tool	What it gives the agent
get_glossary	Approved & forbidden terms per language (preferred / allowed / forbidden)
get_styleguide	Tone, formality, audience, usage rules per language
search_translation_memory	Exact + fuzzy matches from prior translations
get_screenshot_context	The screenshot + region where a key appears

What the conventions tell the agent

• Before translating or reviewing, fetch context: use each glossary term's preferred value (never a forbidden one), apply the style guide's tone/formality, and reuse high-score translation-memory matches. Pull screenshot context when a string is ambiguous.
• For pull-request terminology lint (no translation needed): call get_glossary(languages: "<source>") and flag any new/changed source string that contains a forbidden term, suggesting the language's preferred term instead.
• Matching against source text is the agent's job — terms are returned verbatim (case as stored).

See CLAUDE.md for the full rule text.

Localizing an app end-to-end

The conventions above assume an existing Locize project. To take an app from hardcoded strings to fully localized (detect → instrument → extract → connect to Locize → AI-translate → download), install the skill:

npx skills add i18next/i18next-cli --skill i18next-localization

Then just ask: "add i18n to this project". The skill drives i18next-cli, which does AST-based string wrapping rather than having the agent edit files by hand, and routes per-stack via references/stacks.md.

Without the skill, the same flow is one command:

npx i18next-cli localize                      # interactive
npx i18next-cli localize --print-agent-prompt  # paste into any agent

The printed prompt is version-matched to the installed CLI. Regenerate it from the command rather than keeping a copy, so it never drifts from what the CLI actually does. The skill follows the same rule: it tells the agent to run --print-agent-prompt instead of embedding a snapshot of the steps.

More: launch post · CLI docs.