# i18n-agent [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/i18n-agent/mcp-client  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1049  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/i18n-agent

## Description
AI-powered translation for 48 languages with context-aware quality

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "i18n-agent": {
    "command": "npx",
    "args": ["-y","@i18n-agent/mcp-client"]
  }
}
```

## Documentation & README

# 🌍 i18n-agent MCP Client

Professional translation service client for Claude, Cursor, VS Code, Antigravity, and other AI IDEs using the Model Context Protocol (MCP).

[![npm version](https://badge.fury.io/js/%40i18n-agent%2Fmcp-client.svg)](https://www.npmjs.com/package/@i18n-agent/mcp-client)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- **🎯 Smart Translation**: Context-aware translations with cultural adaptation
- **📁 File Translation**: Support for JSON, YAML, CSV, XML, Markdown, and more
- **⚡ Large File Support**: Async processing for files >50KB with progress tracking
- **🔄 Timeout Improvements**: Extended timeouts (5-10 min) for large translations
- **📊 Progress Tracking**: Real-time job status and completion monitoring
- **💰 Credit Tracking**: Real-time credit balance and word count estimates
- **🌐 48 Languages**: Comprehensive language support with regional variants
- **🔧 Easy Setup**: One-command installation for major AI IDEs

## 🚀 Quick Installation

```bash
npx @i18n-agent/mcp-client install
```

The installer will detect all available AI IDEs and configure them automatically.

### Claude Code Marketplace Installation

For Claude Code users, you can install directly from the marketplace:

**Step 1: Get your API key**
- Visit [app.i18nagent.ai](https://app.i18nagent.ai)
- Sign up or log in
- Copy your API key (starts with "i18n_")

**Step 2: Set environment variable**
```bash
echo 'export I18N_AGENT_API_KEY=your-api-key-here' >> ~/.zshrc
source ~/.zshrc
```

Replace `your-api-key-here` with your actual API key.

**Step 3: Install from marketplace**
```bash
/plugin marketplace add i18n-agent/mcp-client
/plugin install i18n-agent@i18n-agent
```

**Step 4: Restart Claude Code**

That's it! The plugin will automatically use your API key from the environment variable.

## 🔑 Setup API Key

1. **Get your API key** from [app.i18nagent.ai](https://app.i18nagent.ai)

2. **Set environment variable**:
   ```bash
   export I18N_AGENT_API_KEY=your-api-key-here
   ```

3. **Make it permanent** (add to ~/.bashrc or ~/.zshrc):
   ```bash
   echo 'export I18N_AGENT_API_KEY=your-api-key-here' >> ~/.zshrc
   ```

4. **Restart your AI IDE** to load the new configuration

## 🎮 Usage Examples

### Text Translation
```
Translate "Hello, how are you?" to Spanish for a casual audience
```

### File Translation
```
Translate this JSON file to French, preserving the structure
```

### Credit Check
```
Check my translation credits
```

### Language Support
```
List supported languages with quality ratings
```

### Content Analysis
```
Analyze "Hello world! This is a test." for translation to Spanish
```

## 🛠 Supported AI IDEs

| IDE | Status | macOS | Windows | Linux |
|-----|--------|-------|---------|-------|
| **Claude Desktop** | ✅ Auto-configured | `~/Library/Application Support/Claude/` | `%APPDATA%\Claude\` | `~/.config/Claude/` |
| **Claude Code CLI** | ✅ Auto-configured | `~/.claude.json` | `~/.claude.json` | `~/.claude.json` |
| **Cursor** | ✅ Auto-configured | `~/.cursor/mcp_settings.json` | `~/.cursor/mcp_settings.json` | `~/.cursor/mcp_settings.json` |
| **VS Code** | ✅ Auto-configured | `~/.vscode/mcp_settings.json` | `~/.vscode/mcp_settings.json` | `~/.vscode/mcp_settings.json` |
| **Codex (OpenAI)** | ✅ Auto-configured | `~/.codex/mcp_settings.json` | `~/.codex/mcp_settings.json` | `~/.codex/mcp_settings.json` |
| **Antigravity (Google)** | ✅ Auto-configured | `~/.gemini/antigravity/mcp_config.json` | `%USERPROFILE%\.gemini\antigravity\mcp_config.json` | `~/.config/antigravity/mcp_config.json` |

**Note:** The installer automatically detects your platform and uses the correct config paths.

## 🌐 Language Support (48 Languages)
- **bg**: Bulgarian
- **ca**: Catalan
- **cs**: Czech
- **da**: Danish
- **de**: German
- **el**: Greek
- **en**: English
- **en-AU**: English (Australia)
- **en-CA**: English (Canada)
- **en-GB**: English (United Kingdom)
- **en-US**: English (United States)
- **es**: Spanish
- **es-MX**: Spanish (Mexico)
- **et**: Estonian
- **fi**: Finnish
- **fr**: French
- **fr-CA**: French (Canada)
- **hi**: Hindi
- **hr**: Croatian
- **hu**: Hungarian
- **id**: Indonesian
- **is**: Icelandic
- **it**: Italian
- **ja**: Japanese
- **ko**: Korean
- **lt**: Lithuanian
- **lv**: Latvian
- **ms**: Malay
- **nl**: Dutch
- **no**: Norwegian
- **pl**: Polish
- **pt**: Portuguese
- **pt-BR**: Portuguese (Brazil)
- **ro**: Romanian
- **ru**: Russian
- **sk**: Slovak
- **sl**: Slovenian
- **sr**: Serbian
- **sv**: Swedish
- **th**: Thai
- **tl**: Filipino
- **tr**: Turkish
- **uk**: Ukrainian
- **vi**: Vietnamese
- **zh-Hans**: Chinese (Simplified)
- **zh-Hant-HK**: Chinese (Traditional, Hong Kong)
- **zh-Hant-TW**: Chinese (Traditional, Taiwan)

## 📁 Supported File Formats

| Format | Extension | Features |
|--------|-----------|----------|
| JSON | `.json` | Preserves structure, nested objects |
| YAML | `.yaml`, `.yml` | Maintains formatting, comments |
| CSV | `.csv` | Handles quoted fields, commas |
| XML/HTML | `.xml`, `.html` | Extracts text content |
| Markdown | `.md` | Preserves formatting, skips code |
| Properties | `.properties` | Java properties key-value pairs |
| Plain Text | `.txt` | Direct translation |
| PDF | `.pdf` | Text extraction and translation |
| Word | `.docx`, `.doc` | Document translation |
| Gettext | `.po`, `.pot`, `.mo` | Localization file formats |

## 🔧 Manual Setup

If auto-installation fails, you can manually configure your IDE:

### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "i18n-agent": {
      "command": "node",
      "args": ["/path/to/i18n-agent.js"],
      "env": {
        "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
        "I18N_AGENT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor / VS Code
Create `.cursor/mcp_settings.json` or `.vscode/mcp_settings.json`:

```json
{
  "mcpServers": {
    "i18n-agent": {
      "command": "node", 
      "args": ["/path/to/i18n-agent.js"],
      "env": {
        "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
        "I18N_AGENT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## 💡 Usage Tips

### Translation Context
- **Target Audience**: Specify "technical", "casual", "formal", or "general"
- **Industry Context**: Use "technology", "healthcare", "finance", "education"
- **Regional Variations**: Add regions like "Spain", "Mexico", "Brazil"

### File Translation
- **Preserve Structure**: Keeps original file format and structure
- **Output Format**: Convert between formats (JSON ↔ YAML ↔ CSV)
- **Large Files**: Automatically chunks large files for processing
- **Async Processing**: Files >50KB processed asynchronously with job tracking
- **Progress Monitoring**: Real-time status updates for long-running translations
- **Timeout Resilience**: Up to 10 minutes for large translation jobs

### Large Translation Handling
- **Async Processing**: >100 texts or >50KB files processed asynchronously
- **Job Tracking**: Unique job IDs for monitoring long-running translations
- **Progress Updates**: Real-time completion percentages and status
- **Extended Timeouts**: 5-10 minute timeouts prevent interruptions
- **Automatic Polling**: Client automatically polls for job completion

### Credit Management
- **Cost**: 1 credit per word ($0.01/word)
- **Monitoring**: Check balance before large translations
- **Estimates**: Get word count estimates before translation

### Quality Warnings
- **Source Analysis**: By default, source content is analyzed for quality issues before translation
- **Skip Warnings**: Use `skipWarnings: true` to bypass warnings in automated workflows
- **Trade-off**: Skipping warnings may reduce translation quality as potential issues aren't addressed
- **Best Practice**: Keep warnings enabled (default) for production translations

## 🚨 Troubleshooting

### Installation Issues

**Permission denied:**
```bash
sudo npm install -g @i18n-agent/mcp-client
```

**IDE not detected:**
```bash
# Check if IDE directory exists
ls ~/Library/Application\ Support/Claude/
ls ~/.cursor/
ls ~/.vscode/
```

### MCP Connection Issues

**"Failed" status in Claude Code:**

This usually happens with Node Version Managers (nvm, fnm, n). The installer now automatically detects nvm and creates a wrapper script. If you still have issues:

1. **Check your Node installation:**
   ```bash
   which node
   # If output contains .nvm, you're using nvm
   ```

2. **Manual wrapper script (if auto-detection fails):**
   Create `~/.claude/run-mcp.sh`:
   ```bash
   #!/bin/bash
   export PATH="$(dirname $(which node)):$PATH"
   cd ~/.claude
   exec node node_modules/@i18n-agent/mcp-client/i18n-agent.js
   ```
   
   Make it executable:
   ```bash
   chmod +x ~/.claude/run-mcp.sh
   ```
   
3. **Update Claude configuration:**
   Edit `~/.claude.json`:
   ```json
   {
     "mcpServers": {
       "i18n-agent": {
         "command": "/Users/YOUR_USERNAME/.claude/run-mcp.sh",
         "env": {
           "MCP_SERVER_URL": "https://mcp.i18nagent.ai",
           "I18N_AGENT_API_KEY": "your-api-key"
         }
       }
     }
   }
   ```

4. **Restart Claude Code completely** (not just close window, quit the app)

### Runtime Issues

**API Key not found:**
```bash
echo $I18N_AGENT_API_KEY  # Should show your key
export I18N_AGENT_API_KEY=your-key-here
```

**Connection errors:**
- Check your internet connection
- Verify API key is valid
- Try again after a few seconds

**Translation quality:**
- Use Tier 1 languages for production
- Add context with industry/audience parameters
- Review Tier 2/3 translations manually

## 📊 Pricing

- **Pay-per-use**: 1 credit per word ($0.01/word)
- **No subscriptions**: Only pay for what you translate  
- **Bulk discounts**: Available for enterprise usage
- **Free tier**: New accounts get starter credits

## 🔐 Privacy & Security

- **No data storage**: Translations are processed in real-time
- **Encrypted transport**: All data sent over HTTPS
- **API key security**: Keys are stored locally, never transmitted in logs
- **GDPR compliant**: EU privacy standards

## 🏗️ Architecture

The MCP client installer uses a modular architecture for bulletproof installation:

```
lib/
├── config-manager.js      # Config file operations with atomic writes
├── installer-core.js      # Installation orchestration
├── transport-detector.js  # Auto-detect SSE vs stdio transport
└── validator.js          # Input validation and sanitization
```

### Key Features

- **Atomic Config Writes**: Use temp files + rename for crash safety
- **Automatic Backups**: Create timestamped backups before modifications
- **Transport Detection**: Auto-detect SSE vs stdio from config
- **Comprehensive Validation**: Validate all inputs at module boundaries
- **Zero External Dependencies**: Uses only Node.js built-ins

### Architecture Details

See detailed documentation:
- [Module Architecture](lib/README.md) - Module responsibilities and design
- [Full Architecture Guide](docs/mcp-installer-architecture.md) - Complete system design

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md).

### Development Setup

```bash
git clone https://github.com/i18n-agent/mcp-client.git
cd mcp-client
npm install
npm test
```

### Publishing

Use the publishing script with built-in test gate:
```bash
./scripts/publish-mcp-client.sh --dry-run  # Preview package
./scripts/publish-mcp-client.sh            # Run pre-publish checks
npm publish                                 # Publish to npm
```

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

Copyright (c) 2025 FatCouple OÜ

## 🔗 Links

- **Website**: [i18nagent.ai](https://i18nagent.ai)
- **Dashboard**: [app.i18nagent.ai](https://app.i18nagent.ai)
- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)
- **GitHub**: [github.com/i18n-agent/mcp-client](https://github.com/i18n-agent/mcp-client)
- **Issues**: [github.com/i18n-agent/mcp-client/issues](https://github.com/i18n-agent/mcp-client/issues)

## 🆘 Support

- **Email**: support@i18nagent.ai
- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)

## 🔧 Available MCP Tools

### translate_text
Translate text content with cultural adaptation and context awareness.

**Parameters:**
- `texts` (array): Array of strings to translate
- `targetLanguage` (string): Target language code
- `targetAudience` (string): Target audience context
- `industry` (string): Industry context
- `namespace` (string, optional): Optional namespace identifier for backend tracking and project organization
- `sourceLanguage` (string, optional): Source language (auto-detected if not provided)
- `region` (string, optional): Specific region for localization
- `skipWarnings` (boolean, optional): Skip source text quality warnings (default: false). ⚠️ WARNING: May hurt translation quality by bypassing source analysis. Only use when confident about content quality or in automated workflows.

### translate_file
Translate files while preserving structure and format.

**Parameters:**
- `filePath` or `fileContent` (string): File path or content to translate
- `fileType` (string): File format (json, yaml, xml, csv, txt, md, etc.)
- `targetLanguage` (string): Target language code
- `namespace` (string, **required**): Unique namespace identifier for backend tracking and project organization
- `preserveKeys` (boolean): Whether to preserve object keys/structure
- `outputFormat` (string): Output format (same, json, yaml, txt)
- `skipWarnings` (boolean, optional): Skip source text quality warnings (default: false). ⚠️ WARNING: May hurt translation quality by bypassing source analysis. Only use when confident about content quality or in automated workflows.

### analyze_content
Analyze content for translation readiness and get improvement suggestions before translation. This helps identify potential issues and optimize content before spending credits on translation.

**Parameters:**
- `content` (string/array/object): Content to analyze
- `targetLanguage` (string): Target language for translation
- `fileType` (string, optional): File type if content is from a file
- `sourceLanguage` (string, optional): Source language (auto-detected)
- `industry` (string): Industry context
- `targetAudience` (string): Target audience
- `region` (string, optional): Specific region for localization

**Returns:**
- Source language detection with confidence score
- Content type and tone analysis
- Translation readiness score (0-100)
- Specific improvement suggestions
- Quality metrics and issues
- Warnings for potential problems
- Estimated credits required

### list_supported_languages
Get list of all supported languages with quality ratings.

**Parameters:**
- `includeQuality` (boolean): Include quality ratings (default: true)

### get_credits
Check remaining translation credits and word count estimates.

**Parameters:**
- `apiKey` (string): Your API key

### check_translation_status
Check status of async translation jobs (for large files).

**Parameters:**
- `jobId` (string): Job ID from async translation

---

Made with ❤️ by [FatCouple OÜ](https://fireinbelly.com)