Skip to main content
A minimal guide to enabling translation during ingestion. Cognee includes a built-in translation pipeline that detects languages and translates content before graph extraction, so non-English documents are indexed as English knowledge. Before you start:
  • 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 langdetect library
  • Skips chunks already in the target language
  • Translates using one of three providers: llm (default), google, or azure
  • Stores original text alongside the translation in the knowledge graph

Configuration

Set these environment variables in your .env file:
The llm provider uses your existing LLM configuration — no additional keys needed.

Using Translation in a Pipeline

Insert translate_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

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.
For one-off translation without a pipeline, use translate_text:
All three providers translate non-English chunks to your TARGET_LANGUAGE. Pick based on cost, setup, and quality trade-offs:Supported languages: detection uses 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.

LLM Provider (default)

Uses your existing LLM — no extra configuration needed. Works with any provider configured via LLM_PROVIDER and LLM_API_KEY.
Requires the google-cloud-translate package and a Google Cloud project.
Requires an Azure Cognitive Services resource.

Custom Pipelines

Learn to build custom task pipelines

LLM Providers

Configure your LLM provider

Core Concepts

Understand knowledge graph fundamentals