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 Translate Gateway API credential
2. Set Base URL: http://localhost:8080 (without /api/v1)
3. Set authentication method if 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 (YAML/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 YAML or JSON format. Also supports n8n expressions that return objects.

YAML 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

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 (YAML/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. Supports both YAML and JSON formats, as well as n8n expressions.

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