Skip to content

Translation Context

TranslateBot Django can use project-specific context to improve translation quality. By providing information about your project's domain, terminology, and style preferences, you help the AI produce more accurate and consistent translations.

The TRANSLATING.md File

Create a TRANSLATING.md file in your project root (same directory as manage.py) to provide translation context:

TRANSLATING.md
# Translation Context for MyProject

## About This Project
This is an e-commerce platform for outdoor sports equipment.

## Terminology
- "cart" should be translated as "Warenkorb" (German), not "Karren"
- "checkout" should be "Zur Kasse" (German)
- Keep brand names like "Nike", "Adidas", "Patagonia" untranslated

## Tone & Style
- Use informal "du" form in German, not formal "Sie"
- Use informal "tu" form in French, not formal "vous"
- Keep the tone friendly and approachable

## Domain-Specific Terms
- "crampon" - climbing equipment, not a muscle cramp
- "belay" - climbing technique for rope safety
- "bouldering" - keep as English loanword in most languages

DeepL Provider

The TRANSLATING.md context file is only supported with LLM providers (OpenAI, Claude, Gemini, etc.). The DeepL provider does not support custom context β€” if a TRANSLATING.md is found, TranslateBot will show a warning and skip it. For terminology control with DeepL, consider using DeepL glossaries directly.

PO File Comments

Added in v0.9.0

TranslateBot automatically reads extracted comments from your .po files (the #. lines generated by Django's # Translators: markers) and passes them to the LLM as per-string context. This helps disambiguate translations for words with multiple meanings.

# Translators: This is a river bank, not a financial bank
_("bank")

The comment is sent alongside the string so the LLM knows which meaning to use. No configuration needed β€” if comments are present, they're used automatically.

Note

PO file comments are only supported with LLM providers. The DeepL provider does not support per-string context and silently ignores comments.

How It Works

When TranslateBot runs, it:

  1. Searches for a project-level TRANSLATING.md in:
    • Your project's BASE_DIR (from Django settings)
    • The current working directory
  2. Searches for per-app TRANSLATING.md files in each app's directory
  3. Combines project-level and app-level context when both are present
  4. Reads extracted comments from .po file entries and attaches them as per-string context
  5. Groups .po files by their effective context, so apps sharing the same context are batched together efficiently
  6. Includes the combined context in every translation request to the AI model

Output with Context

πŸ“‹ Found TRANSLATING.md - using project context
πŸ“‹ Found TRANSLATING.md for medical_records
πŸ“‹ Found TRANSLATING.md for legal_docs
ℹ️  Found 42 untranslated entries
πŸ”„ Translating with gpt-4o-mini...

What to Include

Project Description

Help the AI understand what your application does:

## About This Project
A healthcare management platform for clinics and hospitals.
Patients use this to book appointments and view medical records.

Terminology Guidelines

Define how specific terms should be translated:

## Terminology
| English | German | French | Notes |
|---------|--------|--------|-------|
| dashboard | Dashboard | tableau de bord | Keep as loanword in German |
| patient | Patient | patient | Medical context |
| appointment | Termin | rendez-vous | Healthcare booking |

Tone & Formality

Specify the level of formality for each language:

## Tone
- German: Use formal "Sie" form (business/healthcare context)
- French: Use formal "vous" form
- Spanish: Use "usted" form
- Keep all messaging professional but warm

Brand & Product Names

List terms that should remain untranslated:

## Do Not Translate
- Company name: "HealthFirst"
- Product names: "CarePlus", "MediTrack"
- Technical terms: "API", "OAuth", "SSO"

Domain Context

Provide context for ambiguous terms:

## Domain Context
This is a legal services platform:
- "brief" means a legal document, not underwear
- "court" means a legal court, not a sports court
- "case" means a legal case, not a container

Per-App Context

Added in v0.6.0

Individual Django apps can have their own TRANSLATING.md files with domain-specific translation context. This is useful when different parts of your project have distinct terminology or style requirements.

Place a TRANSLATING.md file in the app's root directory (next to models.py):

myproject/
β”œβ”€β”€ manage.py
β”œβ”€β”€ TRANSLATING.md              # Project-level context
β”œβ”€β”€ medical_records/
β”‚   β”œβ”€β”€ models.py
β”‚   β”œβ”€β”€ locale/
β”‚   β”‚   └── de/LC_MESSAGES/django.po
β”‚   └── TRANSLATING.md          # App-specific context
β”œβ”€β”€ legal_docs/
β”‚   β”œβ”€β”€ models.py
β”‚   β”œβ”€β”€ locale/
β”‚   β”‚   └── de/LC_MESSAGES/django.po
β”‚   └── TRANSLATING.md          # App-specific context
└── common/
    β”œβ”€β”€ models.py
    └── locale/
        └── de/LC_MESSAGES/django.po  # Uses project-level context only
medical_records/TRANSLATING.md
## Medical Records App

This app handles patient medical records, diagnoses, and treatment plans.

## Terminology
- "record" means a medical record, not a database record
- "chart" means a patient chart, not a graph
- "prescription" - use formal medical terminology in all languages
- "vitals" - short for vital signs (blood pressure, heart rate, etc.)
legal_docs/TRANSLATING.md
## Legal Documents App

This app manages contracts, agreements, and legal compliance documents.

## Terminology
- "party" means a legal party (person/entity in a contract), not a celebration
- "brief" means a legal document, not something short
- "motion" means a legal motion/request, not physical movement
- Use formal register in all languages

When both project-level and app-level context exist, they are combined: the project context appears first, followed by the app-specific context under an "App-Specific Context" heading. Apps without their own TRANSLATING.md use only the project-level context. Apps sharing the same effective context are batched together for efficiency.

Best Practices

Be Specific

The more specific your context, the better the translations. Instead of "use formal tone", specify "use formal 'Sie' in German and 'vous' in French".

Include Examples

When terms are ambiguous, provide example sentences showing the intended meaning.

Update Regularly

As your project evolves, update TRANSLATING.md with new terminology and context.

Version Control

Commit TRANSLATING.md to your repository so the entire team shares the same translation context.

Example: E-commerce Project

TRANSLATING.md
# Translation Context

## Project Overview
Online store selling handmade jewelry. Target audience is women aged 25-45
who appreciate artisanal, sustainable products.

## Brand Voice
- Warm and personal, like talking to a friend
- Emphasize craftsmanship and sustainability
- Avoid corporate/formal language

## Terminology
- "artisan" - craftsperson who makes items by hand
- "sustainable" - environmentally responsible
- "collection" - a themed group of products (not gathering things)

## Language-Specific Guidelines

### German
- Use informal "du" form
- "Warenkorb" for cart, "Zur Kasse" for checkout
- Keep "Sale" as English loanword

### French
- Use informal "tu" form
- "Panier" for cart, "Commander" for checkout
- Translate "handmade" as "fait main"

### Dutch
- Use informal "je" form
- "Winkelwagen" for cart, "Afrekenen" for checkout

## Do Not Translate
- Brand name: "Luna & Sol"
- Collection names: "Ocean Dreams", "Forest Whispers"
- Material names when they're marketing terms: "EcoSilk"

Example: SaaS Application

TRANSLATING.md
# Translation Context

## Project Overview
B2B project management software for enterprise teams.
Users are typically project managers and team leads.

## Brand Voice
- Professional and clear
- Action-oriented
- Avoid jargon, be accessible

## Terminology
- "sprint" - agile development cycle (not running)
- "backlog" - list of pending work items
- "milestone" - project checkpoint
- "stakeholder" - person with interest in project outcome

## Language-Specific Guidelines

### German
- Use formal "Sie" form (business context)
- "Projekt" not "Project" (use German spelling)
- "Aufgabe" for task, "Frist" for deadline

### Japanese
- Use polite/formal register (です/ます form)
- Use katakana for technical terms: γ‚Ήγƒ—γƒͺγƒ³γƒˆ, バックログ

## Technical Terms (Keep in English)
- API, REST, webhook
- OAuth, SSO, SAML
- Dashboard (commonly used as loanword)

Next Steps