ComfyUI-TranslateLink

ComfyUI-TranslateLink

English | 简体中文

A dependency-friendly translation node pack for ComfyUI, connecting Google, Baidu, Ollama, OpenAI-compatible models, and custom HTTP APIs through one unified interface.

TranslateLink translates workflow text (prompts, captions, any string) inside ComfyUI. It is not a UI localization plugin. A single TranslateLink · Translate Text node covers all five providers: pick the provider and languages from dropdowns, fill in the fields that provider needs, done.

Screenshot placeholder: drop a workflow screenshot here.

Highlights

• Zero extra runtime dependencies. Only the Python standard library (urllib, json, ssl, …) — no requests, no vendor SDKs, nothing installed into your ComfyUI environment. (This means the plugin adds no packages of its own; it is not a guarantee that unrelated plugins can never conflict.)
• Five providers, one node. Google Cloud Translation v2, Baidu Fanyi, Ollama, any OpenAI-compatible Chat Completions endpoint, and custom HTTP JSON APIs.
• One language list. Pick zh, ja, fr, … once; the node translates the code for each provider automatically (Google gets zh-CN, Baidu gets cht for Traditional Chinese, LLMs get "Simplified Chinese").
• Flexible credentials. Type keys directly on the node, or leave the fields empty and keep keys in environment variables / a git-ignored config.json. Keys never appear in logs or error messages.
• Sane networking, zero knobs. Fixed 60 s timeout and one automatic retry with backoff for network errors, HTTP 429 and 5xx; 2 MiB response cap; TLS verification always on.
• Built-in result cache. Inputs are hashed and identical requests replay the previous result instead of hitting the provider again (in-process LRU, max 100 entries; errors are never cached).

Installation

Copy or clone this repository into ComfyUI/custom_nodes/ and restart ComfyUI. No pip install required.

cd ComfyUI/custom_nodes
git clone https://github.com/your-name/ComfyUI-TranslateLink.git

Works on Windows, macOS, and Linux with Python 3.9+.

The node

TranslateLink · Translate Text

Core inputs:

| Input | Type | Default | Notes | |---|---|---|---| | provider | dropdown | google | google / baidu / openai / ollama / custom_http | | text | STRING (multiline) | "" | Empty text returns empty without any network call; input is never trimmed | | source_language | dropdown | auto | Unified code list; auto = detect | | target_language | dropdown | en | Unified code list |

Available languages: en, zh (Simplified Chinese), zh-TW (Traditional Chinese), ja, ko, fr, de, es, it, pt, ru, ar, th, vi, nl, pl, el, cs, sv, hu, da, fi, ro, bg, et, sl — the intersection of what Google and Baidu both support, so every choice works with every provider. Each adapter maps the code automatically; you never enter provider-specific codes.

Credential fields (leave empty to use environment variables / config.json):

| Input | google | baidu | openai | ollama | custom_http | |---|---|---|---|---|---| | api_key | API key | App ID | API key | — | — | | api_secret | — | Secret | — | — | — |

For Baidu, fill both api_key (App ID) and api_secret (Secret) or neither — setting only one is an error.

Provider-specific fields (ignored by other providers):

| Input | Default | Used by | Notes | |---|---|---|---| | endpoint | "" | all | Empty = provider default; required for custom_http | | model | "" | openai, ollama | Required for those providers | | temperature | 0.1 | openai, ollama | 0–2 | | system_prompt | built-in | openai, ollama | {source_language} / {target_language} placeholders are filled in with language names | | extra_body_json | {} | openai | JSON object merged into the request body; must not contain messages | | keep_alive | 5m | ollama | |

Output: translated_text (STRING).

Networking is fixed: 60-second timeout, one retry (network errors, HTTP 429, and 5xx only) with exponential backoff. Results are cached in-process: the node hashes every input that shapes the answer and replays the previous result for an identical request (LRU, max 100 entries; shared across queue runs and workflows for the life of the ComfyUI process; cleared on restart; errors are never cached). Every hit/store logs a [TranslateLink] cache … line to the console.

Default endpoints: Google https://translation.googleapis.com/language/translate/v2, Baidu https://fanyi-api.baidu.com/api/trans/vip/translate, OpenAI https://api.openai.com/v1/chat/completions, Ollama http://127.0.0.1:11434/api/chat.

Credentials

Precedence: node field > environment variable > config.json.

⚠️ Keys typed into the node are saved in the workflow JSON. For workflows you intend to share, leave the key fields empty and use one of the options below.

Environment variables:

| Variable | Used by | |---|---| | TRANSLATELINK_GOOGLE_API_KEY | google | | TRANSLATELINK_BAIDU_APP_ID | baidu | | TRANSLATELINK_BAIDU_SECRET | baidu | | TRANSLATELINK_OPENAI_API_KEY | openai |

Or copy config.example.json to config.json in the plugin directory and fill in the blanks:

{
  "profiles": {
    "default": {
      "google": { "api_key": "" },
      "baidu": { "app_id": "", "secret": "" },
      "openai": { "api_key": "" },
      "custom": {}
    }
  }
}

Ollama needs no credentials; OpenAI-compatible services without auth work with an empty key.

config.json is listed in .gitignore. The file is only read when a provider actually needs a credential; a missing file is fine until then.

Provider notes

• google — official Google Cloud Translation Basic (v2) REST API. HTML entities in responses are decoded automatically. No unofficial web-scraping endpoints.

• baidu — Baidu Fanyi open platform. Requests are signed with MD5(appid + q + salt + secret) using a cryptographically random salt; multi-segment results are joined with newlines in order.

• openai — any Chat Completions-compatible endpoint. An empty API key simply omits the Authorization header, so unauthenticated compatible servers (e.g. a local vLLM) work out of the box. The default system prompt asks for translation only — no explanations, no fences.

• ollama — requests always send stream: false, keep_alive, and options.temperature.

• custom_http — for your own translation endpoint. Fixed, simple contract:

  POST {endpoint}
  Content-Type: application/json
  
  {"text": "...", "source": "auto", "target": "ja"}
  
  → any 2xx status with: {"translation": "..."}
  

  source / target receive the unified codes as-is. Non-2xx responses are failures; TLS verification stays on. (Richer templating — custom headers, body templates, and response paths — exists in the engine layer translatelink/providers/custom_http.py for programmatic use.)

Minimal recipes

Add one TranslateLink · Translate Text node, pick the provider, choose target_language:

• google: paste your key into api_key (or set TRANSLATELINK_GOOGLE_API_KEY).
• baidu: App ID into api_key, Secret into api_secret.
• openai: key into api_key, model = gpt-4o-mini.
• openai-compatible (local): endpoint = http://127.0.0.1:8000/v1/chat/completions, key empty, set model.
• ollama: ollama pull qwen2.5:7b, then model = qwen2.5:7b.
• custom_http: fill endpoint; make your endpoint speak the fixed contract above.

Security notes

• With empty key fields, workflow JSON is safe to share: it contains endpoints and model names, never credentials. Keys typed into the node fields are stored in the workflow JSON — clear them before sharing.
• Do not share config.json or your environment variable values.
• Error messages include the provider name, HTTP status, and a short redacted response snippet — keys, secrets, signatures, and Authorization headers are never included.

Troubleshooting

| Symptom | Likely cause | |---|---| | Google API key is not configured | Fill api_key, set TRANSLATELINK_GOOGLE_API_KEY, or fill config.json | | Baidu needs both the App ID and the Secret | Fill both api_key and api_secret, or neither | | credential profile 'x' not found | config.json exists but has no such profile; the error lists available names | | config file ... is not valid JSON | Fix the reported file, or recreate it from config.example.json | | TranslateLink(baidu): Baidu API error 54001 | Wrong App ID/Secret (invalid sign) | | TranslateLink(ollama): network error (connection) | Ollama not running / wrong endpoint | | Ollama error: model '...' not found | ollama pull <model> first | | model is required | Set model for openai/ollama | | HTTP 429 persists | Provider rate limit; slow down | | response_path 'translation' not found | Your custom endpoint must return {"translation": "..."} | | response body exceeded the 2 MiB limit | The endpoint returned something that is not a translation response |

Development

python -m unittest discover -s tests -v
python -m compileall .

Tests use a fake HTTP transport — no network access and no real keys required.

Internals: the node (nodes.py) only converts inputs and calls TranslationEngine.translate(request, provider_config); each provider is an adapter in translatelink/providers/ behind that single interface; the unified language mapping lives in translatelink/languages.py, and the urllib-based transport is injectable for testing.

License

MIT