n8n-nodes-bozonx-translate-gateway-microservice

An n8n community node for text translation via the Translate Gateway microservice.

Features

• Multiple Providers: Google Translate, DeepL, DeepSeek LLM, OpenRouter LLM, Yandex Translate, AnyLang, LibreTranslate
• Auto Language Detection: Automatically detect source language
• HTML Support: Preserves HTML tags during translation
• Text Chunking: Automatically splits large texts with configurable strategies
• Error Handling: Built-in retry logic and continue-on-fail support

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in n8n
2. Click Install
3. Enter n8n-nodes-bozonx-translate-gateway-microservice
4. Install and restart n8n

Manual Installation

npm install n8n-nodes-bozonx-translate-gateway-microservice

For Docker:

RUN npm install -g n8n-nodes-bozonx-translate-gateway-microservice

Quick Start

1. Start the Microservice

docker run -d \
  --name translate-gateway \
  -p 8080:8080 \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/gcp-service-account.json \
  -v /path/to/gcp-credentials.json:/secrets/gcp-service-account.json \
  bozonx/translate-gateway-microservice:latest

Test the service:

curl http://localhost:8080/api/v1/health
# Expected: {"status":"ok"}

2. Configure n8n Credentials

1. Create a new Bozonx Microservices API credential
2. Set Gateway URL: http://localhost:8080
3. Set API Token (optional, if authentication is required)

3. Use the Node

Add the Translate Gateway node to your workflow and configure:

• Text: Hello, world!
• Target Language: ru

Result:

{
  "translatedText": "Привет, мир!",
  "provider": "google"
}

Configuration

Required Parameters

• Text: Source text to translate (plain text or HTML)
• Target Language: BCP-47 language code (e.g., en, ru, ru-RU, es, fr, de, pt-BR)

Optional Parameters

| Parameter | Description | Default | |-----------|-------------|---------| | Source Language | BCP-47 source language code | Auto-detect | | Provider | Translation provider | Service default | | Model | Model name (for LLM/AnyLang providers) | Provider default |

Additional Options

| Option | Description | Default | |--------|-------------|---------| | Timeout (Seconds) | Request timeout per provider attempt (0-600) | Service default (60s) | | Retry Max Attempts | Maximum retry attempts including initial (0-30) | Service default (3) | | Retry Initial Delay (ms) | Initial retry delay with exponential backoff (0-600000) | Service default (1000ms) | | Retry Max Delay (ms) | Maximum retry delay cap (0-600000) | Service default (5000ms) | | Max Chunk Length | Maximum characters per chunk (0-1000000, min 100 if set) | Provider default | | Splitter | Text splitting strategy | Service default (paragraph) | | Provider Parameters (JSON) | Provider-specific overrides (see below) | None |

Providers

| Provider | Type | Environment Variable | |----------|------|---------------------| | Google | Translation API | GOOGLE_APPLICATION_CREDENTIALS | | DeepL | Translation API | DEEPL_AUTH_KEY | | DeepSeek | LLM | DEEPSEEK_API_KEY | | OpenRouter | LLM | OPENROUTER_API_KEY | | Yandex | Translation API | YANDEX_API_KEY, YANDEX_FOLDER_ID | | AnyLang | Open Source | None (uses translate-tools/core) | | LibreTranslate | Open Source | LIBRETRANSLATE_URL |

Configure providers via microservice environment variables. See microservice documentation for details.

Text Splitting Strategies

| Strategy | Description | Use Case | |----------|-------------|----------| | paragraph | Split by paragraphs (double newlines) | Long-form plain text (default) | | markdown | Split by markdown structure (headers, lists) | Markdown documents | | sentence | Split by sentences | When paragraphs are too large | | off | No splitting (error if exceeds limit) | Enforce strict limits |

Note: HTML content is automatically detected and never chunked. If HTML exceeds provider limits, an error is returned.

Provider Parameters

Override microservice environment variables per request using JSON format:

{
  "apiKey": "your-api-key",
  "baseUrl": "https://custom-api.example.com",
  "systemPrompt": "Custom LLM prompt",
  "folderId": "yandex-folder-id",
  "autoModels": ["google", "microsoft"],
  "userAgent": "Custom-Agent/1.0",
  "freeDelayMs": 2000
}

Field mappings by provider:

| Field | Providers | Description | |-------|-----------|-------------| | apiKey | Google, DeepL, DeepSeek, OpenRouter, LibreTranslate, Yandex | API key or credentials (for Google: JSON string) | | baseUrl | DeepSeek, OpenRouter, LibreTranslate | Custom API endpoint URL | | systemPrompt | DeepSeek, OpenRouter | System prompt for LLM providers | | folderId | Yandex | Yandex Cloud folder ID | | autoModels | AnyLang | Array of models for auto mode | | userAgent | AnyLang | Custom User-Agent header | | freeDelayMs | AnyLang | Delay between free tier requests |

Usage Examples

Basic Translation

Text: "Привет, мир!"
Target Language: en

Output:

{
  "translatedText": "Hello, world!",
  "provider": "google"
}

HTML Translation

Text: "<p>Bonjour, <b>monde</b>!</p>"
Target Language: en
Provider: deepl

Output:

{
  "translatedText": "<p>Hello, <b>world</b>!</p>",
  "provider": "deepl"
}

LLM Translation

Text: "Hello, world!"
Target Language: ru
Provider: deepseek
Model: deepseek-chat

Output:

{
  "translatedText": "Привет, мир!",
  "provider": "deepseek",
  "model": "deepseek-chat"
}

Large Text with Chunking

Text: "Very long text... (5000+ characters)"
Target Language: es
Max Chunk Length: 1000
Splitter: paragraph

The text is automatically split into chunks, translated separately, and reassembled.

With Retry Configuration

Text: "Hello, world!"
Target Language: ru
Additional Options:
  - Retry Max Attempts: 5
  - Retry Initial Delay (ms): 500
  - Retry Max Delay (ms): 10000

Retries are automatically triggered for transient errors (timeouts, 5xx, 429).

With Provider Parameters

Text: "Hello, world!"
Target Language: ru
Provider: deepseek
Additional Options:
  - Provider Parameters (JSON):
    {
      "apiKey": "sk-custom-key",
      "baseUrl": "https://custom-deepseek.example.com",
      "systemPrompt": "Translate naturally and preserve tone"
    }

Overrides microservice environment variables for this request only.

Error Handling

Enable Continue On Fail to handle errors gracefully. Errors are returned as:

{
  "error": "Error message"
}

Common Error Codes

| Code | Description | |------|-------------| | 400 | Invalid request (missing required fields) | | 404 | Unknown provider | | 413 | Text exceeds maximum length | | 422 | Provider error (quota exceeded, unsupported language) | | 503 | Provider unavailable or timeout |

Troubleshooting

Node Not Found

• Restart n8n after installation
• Check Settings → Community Nodes for installation status

Connection Error

• Verify microservice is running: curl http://localhost:8080/api/v1/health
• Ensure Gateway URL does NOT include /api/v1
• Check port 8080 is accessible

Translation Error (422)

• Provider API key not configured in microservice
• Unsupported language code
• Provider quota exceeded

Timeout Error (503)

• Provider is slow or unavailable
• Increase REQUEST_TIMEOUT_SEC in microservice environment variables

Development

Build

pnpm build

Watch Mode

pnpm build:watch

Lint

pnpm lint
pnpm lint:fix

Publish

pnpm publish:npm

Resources

• Translate Gateway Microservice
• API Documentation
• n8n Community Nodes
• n8n Community Forum

License

MIT