better-i18n.com
Geliştirici DokümanlarıYardım MerkeziSürüm Notları

Coding Agents

Bu sayfada

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                  |