- Complete Quickstart to understand basic operations
- Ensure you have LLM Providers configured
- Have non-English text or documents to process
What Translation Does
- Detects language automatically using the
langdetectlibrary - Skips chunks already in the target language
- Translates using one of three providers:
llm(default),google, orazure - Stores original text alongside the translation in the knowledge graph
Configuration
Set these environment variables in your.env file:
llm provider uses your existing LLM configuration — no additional keys needed.
Using Translation in a Pipeline
Inserttranslate_content as a pipeline task between chunk extraction and graph building:
translate_content mutates chunks in-place: chunk.text is replaced with the translation and the original is preserved in a TranslatedContent data point attached to the chunk.Additional Information
How Language Detection Works
How Language Detection Works
Cognee detects language per chunk with the
langdetect library. Each chunk produced by the chunker is analyzed independently, so a document that mixes languages has every chunk detected — and translated — on its own.A chunk is translated only when both conditions hold: the detected language differs from TARGET_LANGUAGE, and the detection confidence is at least CONFIDENCE_THRESHOLD (default 0.8). Otherwise the chunk is left untouched and only tagged with LanguageMetadata. Chunks shorter than 10 characters skip detection entirely.langdetect recognizes 55 languages:af, ar, bg, bn, ca, cs, cy, da, de, el, en, es, et, fa, fi, fr, gu, he, hi, hr, hu, id, it, ja, kn, ko, lt, lv, mk, ml, mr, ne, nl, no, pa, pl, pt, ro, ru, sk, sl, so, sq, sv, sw, ta, te, th, tl, tr, uk, ur, vi, zh-cn, zh-twLanguages outside this set — for example Azerbaijani (az) — cannot be detected. langdetect either misclassifies them as a related language (Azerbaijani is often read as Turkish, tr) or returns low confidence, so such chunks may be skipped or translated from the wrong source language. Detection drives translation off the detected code, not the document’s true language, so verify coverage before relying on it for an unsupported language.Translating Individual Strings
Translating Individual Strings
For one-off translation without a pipeline, use
translate_text:Choosing a Provider
Choosing a Provider
All three providers translate non-English chunks to your
Supported languages: detection uses
TARGET_LANGUAGE. Pick based on cost, setup, and quality trade-offs:| Provider | Setup | Cost | Best for |
|---|---|---|---|
llm (default) | None — reuses your LLM config | Per-token LLM usage; higher quality, slower | Mixed/long-form documents where context-aware translation matters |
google | Install google-cloud-translate, Google Cloud project | Per-character pricing; fast batch translation | High-volume ingestion across many languages |
azure | Azure Cognitive Services key + region | Per-character pricing; fast batch translation | Enterprise deployments already on Azure |
langdetect (~55 languages). The llm provider supports any language the underlying model handles. Google Translate and Azure Translator each support 130+ language codes, including locale-specific variants such as zh-CN and zh-TW — see the Google Cloud Translation language list and Azure Translator language list for the full set.Set TRANSLATION_PROVIDER in .env to switch — no code changes required.Provider-Specific Setup
Provider-Specific Setup
LLM Provider (default)
LLM Provider (default)
Uses your existing LLM — no extra configuration needed. Works with any provider configured via
LLM_PROVIDER and LLM_API_KEY.Google Cloud Translation
Google Cloud Translation
Requires the
google-cloud-translate package and a Google Cloud project.Azure Translator
Azure Translator
Requires an Azure Cognitive Services resource.
Advanced Options
Advanced Options
| Variable | Default | Description |
|---|---|---|
TRANSLATION_BATCH_SIZE | 10 | Chunks per translation batch |
TRANSLATION_MAX_RETRIES | 3 | Retry attempts on failure |
TRANSLATION_TIMEOUT_SECONDS | 30 | Request timeout |
Custom Pipelines
Learn to build custom task pipelines
LLM Providers
Configure your LLM provider
Core Concepts
Understand knowledge graph fundamentals