better-i18n.com
Docs développeurCentre d'aideNotes de version

Coding Agents

Sur cette page

Connect coding agents like Cursor, Claude Code, Windsurf, Zed, Codex, and Antigravity to your translation workspace.

Get your API Key #

  1. Sign in to dash.better-i18n.com.
  2. Go to Settings > API Keys.
  3. Create a new key and copy it.

Configure Project Context #

The MCP server needs to know which project to manage. It reads the projectId field from your i18n.config.ts.

i18n.config.ts
import { createI18n } from "@better-i18n/next";

export const i18n = createI18n({
  projectId: "your-org/your-project", // MCP uses this ID // [!code highlight]
  defaultLocale: "en",
});

Configure your AI Assistant #

Pass your API key using the BETTER_I18N_API_KEY environment variable.

Cursor

Recommended — OAuth, no API key. Add the remote server in Settings → MCP → Add new MCP server, choose Remote, and paste:

Code
```
https://mcp.better-i18n.com/mcp
```

Cursor opens your browser to sign in on first use — no key to manage.

**Alternative — API key** (`~/.cursor/mcp.json`):

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}
```

Claude Code

Recommended — OAuth, no API key. Add the remote server and sign in through your browser:

Code
```bash title="Terminal"
claude mcp add --transport http --scope user better-i18n https://mcp.better-i18n.com/mcp
```

Then run `/mcp` inside Claude Code, pick **better-i18n → Authenticate**, and approve in your browser. No key to copy or rotate — the token refreshes automatically.

**Alternative — API key** (for offline / self-hosted setups):

```bash title="Terminal"
claude mcp add better-i18n -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest
```

Claude Code automatically manages the `.mcp.json` configuration. View and manage servers with `claude mcp list`.

Claude Desktop

Add this to your Claude Desktop config: json { "mcpServers": { "better-i18n": { "command": "npx", "args": ["-y", "@better-i18n/mcp@latest"], "env": { "BETTER_I18N_API_KEY": "your-api-key" } } } }

Windsurf

Add this to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json): json title="~/.codeium/windsurf/mcp_config.json" { "mcpServers": { "better-i18n": { "command": "npx", "args": ["-y", "@better-i18n/mcp@latest"], "env": { "BETTER_I18N_API_KEY": "your-api-key" } } } }

Zed

Add this to your Zed settings (~/.config/zed/settings.json): json title="~/.config/zed/settings.json" { "context_servers": { "better-i18n": { "command": { "path": "npx", "args": ["-y", "@better-i18n/mcp@latest"], "env": { "BETTER_I18N_API_KEY": "your-api-key" } }, "settings": {} } } }

Codex

Option 1: CLI command bash title="Terminal" codex mcp add better-i18n --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest

Code
**Option 2: Manual config** (`~/.codex/config.toml`)
```toml title="~/.codex/config.toml"
[mcp_servers.better-i18n]
command = "npx"
args = ["-y", "@better-i18n/mcp@latest"]

[mcp_servers.better-i18n.env]
BETTER_I18N_API_KEY = "your-api-key"
```

Antigravity

Add this to your GEMINI.md or .rules file: ```markdown title="GEMINI.md" MCP Servers: - better-i18n: @better-i18n/mcp@latest (stdio)

Code
Environment Variables:
BETTER_I18N_API_KEY: your-api-key
```

Verify Connectivity #

Ask your AI assistant a translation-related question to verify the setup:

"Show me the translation status for my current project."

If configured correctly, the AI will use the getProject tool to fetch your real-time stats.

Content Management MCP #

If you also use Better i18n's headless CMS features, add the content MCP server separately:

Cursor

~/.cursor/mcp.json
    {
      "mcpServers": {
        "better-i18n": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        },
        "better-i18n-content": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp-content@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        }
      }
    }
    ```

**Claude Code**

Run both commands in your terminal:
    ```bash title="Terminal"
    claude mcp add better-i18n -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest
    claude mcp add better-i18n-content -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp-content@latest
    ```

**Claude Desktop**

```json
{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    },
    "better-i18n-content": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp-content@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json
    {
      "mcpServers": {
        "better-i18n": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        },
        "better-i18n-content": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp-content@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        }
      }
    }
    ```

**Zed**

```json title="~/.config/zed/settings.json"
    {
      "context_servers": {
        "better-i18n": {
          "command": {
            "path": "npx",
            "args": ["-y", "@better-i18n/mcp@latest"],
            "env": {
              "BETTER_I18N_API_KEY": "your-api-key"
            }
          },
          "settings": {}
        },
        "better-i18n-content": {
          "command": {
            "path": "npx",
            "args": ["-y", "@better-i18n/mcp-content@latest"],
            "env": {
              "BETTER_I18N_API_KEY": "your-api-key"
            }
          },
          "settings": {}
        }
      }
    }
    ```

**Codex**

**Option 1: CLI commands**
    ```bash title="Terminal"
    codex mcp add better-i18n --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest
    codex mcp add better-i18n-content --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp-content@latest
    ```

    **Option 2: Manual config** (`~/.codex/config.toml`)
    ```toml title="~/.codex/config.toml"
    [mcp_servers.better-i18n]
    command = "npx"
    args = ["-y", "@better-i18n/mcp@latest"]

    [mcp_servers.better-i18n.env]
    BETTER_I18N_API_KEY = "your-api-key"

    [mcp_servers.better-i18n-content]
    command = "npx"
    args = ["-y", "@better-i18n/mcp-content@latest"]

    [mcp_servers.better-i18n-content.env]
    BETTER_I18N_API_KEY = "your-api-key"
    ```

**Antigravity**

```markdown title="GEMINI.md"
    MCP Servers:
    - better-i18n: @better-i18n/mcp@latest (stdio)
    - better-i18n-content: @better-i18n/mcp-content@latest (stdio)

    Environment Variables:
    BETTER_I18N_API_KEY: your-api-key
    ```

> [!NOTE]
> The translation and content MCP servers are separate packages to keep each focused. You can install one or both depending on your needs.

## Environment Variables

| Variable              | Required | Description                                    |
| --------------------- | -------- | ---------------------------------------------- |
| `BETTER_I18N_API_KEY` | Yes      | Your organization API key                      |
| `BETTER_I18N_API_URL` | No       | Custom API URL (default: dash.better-i18n.com) |
| `BETTER_I18N_DEBUG`   | No       | Enable detailed debug logging                  |