npm package: @i18n-agent/n8n-node
Description: n8n node for i18n Agent - AI-powered translation service with cultural adaptation
Author: i18n Agent
Latest version: 1.0.1

# @i18n-agent/n8n-node

This is an n8n community node for [i18n Agent](https://i18nagent.ai), an AI-powered translation service with cultural adaptation capabilities.

## Features

- **Text Translation**: Translate text content with AI-powered cultural adaptation
- **File Translation**: Translate structured files (JSON, YAML, XML, CSV, etc.) while preserving format
- **Document Translation**: Support for PDF and Word documents
- **Language Detection**: Automatic source language detection
- **Cultural Context**: Industry-specific terminology and regional variations
- **Batch Processing**: Process multiple items in your workflow

## Installation

### Community Node (Recommended)

In n8n, go to **Settings** > **Community Nodes** and search for `@i18n-agent/n8n-node`.

### Manual Installation

1. Navigate to your n8n custom nodes folder:
   ```bash
   cd ~/.n8n/nodes
   ```

2. Install from npm:
   ```bash
   npm install @i18n-agent/n8n-node
   ```

   Or clone this repository:
   ```bash
   git clone https://github.com/i18n-agent/n8n-node.git
   cd n8n-node
   npm install
   ```

4. Build the node:
   ```bash
   npm run build
   ```

5. Restart n8n

### Docker Installation

If you're using n8n with Docker, mount the node as a volume:

```bash
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v ~/n8n-node:/home/node/.n8n/nodes/n8n-node \
  n8nio/n8n
```

## Configuration

### Getting an API Key

1. Sign up at [i18nagent.ai](https://i18nagent.ai)
2. Navigate to your dashboard
3. Go to Settings > API Keys
4. Create a new API key (it will start with `i18n_`)

### Setting up Credentials in n8n

1. In n8n, go to **Credentials** > **New**
2. Search for "i18n Agent"
3. Enter your API key
4. Select your environment (Production/Development/Custom)
5. Save the credentials

## Usage

### Text Translation

1. Add the i18n Agent node to your workflow
2. Select **Text** as the resource
3. Choose **Translate** operation
4. Enter the text to translate
5. Select target language
6. Configure optional settings (audience, industry, region)

### File Translation

1. Add the i18n Agent node to your workflow
2. Select **File** as the resource
3. Choose **Translate File** operation
4. Connect a node that provides binary data (e.g., Read Binary File)
5. Select target language
6. Configure file type and output format

### Workflow Examples

#### Example 1: Translate Customer Support Emails

```json
{
  "nodes": [
    {
      "name": "Gmail Trigger",
      "type": "n8n-nodes-base.gmailTrigger",
      "position": [250, 300]
    },
    {
      "name": "i18n Agent",
      "type": "n8n-nodes-base.i18nAgent",
      "position": [450, 300],
      "parameters": {
        "resource": "text",
        "operation": "translate",
        "text": "={{$node['Gmail Trigger'].json['text']}}",
        "targetLanguage": "es",
        "additionalOptions": {
          "targetAudience": "formal",
          "industry": "customer_support"
        }
      }
    },
    {
      "name": "Send Reply",
      "type": "n8n-nodes-base.gmail",
      "position": [650, 300]
    }
  ]
}
```

#### Example 2: Batch Translate Product Descriptions

```json
{
  "nodes": [
    {
      "name": "Spreadsheet File",
      "type": "n8n-nodes-base.spreadsheetFile",
      "position": [250, 300]
    },
    {
      "name": "i18n Agent",
      "type": "n8n-nodes-base.i18nAgent",
      "position": [450, 300],
      "parameters": {
        "resource": "text",
        "operation": "translate",
        "text": "={{$json['description']}}",
        "targetLanguage": "fr",
        "additionalOptions": {
          "targetAudience": "general",
          "industry": "ecommerce",
          "region": "France"
        }
      }
    }
  ]
}
```

## Node Reference

### Resources

#### Text
- **Translate**: Translate text content with cultural adaptation

#### File
- **Translate File**: Translate files while preserving structure

#### Language
- **List**: Get all supported languages with quality ratings

### Common Parameters

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| Target Language | Select | Language to translate to | Yes |
| Target Audience | Select | general, technical, casual, formal | No |
| Industry | Select | Industry context for specialized terms | No |
| Source Language | String | Auto-detected if not specified | No |
| Region | String | Specific regional variant | No |
| Notes | String | Additional translation instructions | No |

### File-Specific Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| File Type | Select | Format of the input file | auto |
| Preserve Keys | Boolean | Keep structure in JSON/YAML | true |
| Output Format | Select | Desired output format | same |

## Supported Languages

The node supports 100+ languages including:
- Major languages: Spanish, French, German, Japanese, Chinese, etc.
- Regional variants: pt-BR, zh-Hans, zh-Hant
- RTL languages: Arabic, Hebrew, Persian

Use the **List Languages** operation to get the current list with quality ratings.

## Supported File Formats

- **Structured**: JSON, YAML, XML, CSV
- **Documents**: PDF, DOCX, DOC
- **Markup**: HTML, Markdown
- **Configuration**: Properties files
- **Plain text**: TXT

## Error Handling

The node includes comprehensive error handling:

- **401**: Invalid API key
- **402**: Insufficient credits
- **400**: Validation errors
- **500**: Server errors

Enable "Continue On Fail" in node settings to handle errors gracefully in your workflow.

## Advanced Features

### Streaming (Coming Soon)

The API supports Server-Sent Events (SSE) for real-time translation progress. This feature will be added in a future version.

### Batch Processing

The node automatically handles n8n's item-based processing, allowing you to translate multiple items efficiently.

### Cultural Adaptation

The AI model considers:
- Industry-specific terminology
- Regional language variations
- Formal/informal tone
- Cultural context and idioms

## Support

- **Documentation**: [docs.i18nagent.ai](https://docs.i18nagent.ai)
- **API Reference**: [docs.i18nagent.ai/api](https://docs.i18nagent.ai/api)
- **Support**: support@i18nagent.ai
- **Issues**: [GitHub Issues](https://github.com/i18n-agent/n8n-node/issues)

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Changelog

### Version 1.0.0
- Initial release
- Text translation support
- File translation support
- Language listing
- Full API integration