Django Translation Context

Introduction

When localizing your Django applications, you'll often encounter scenarios where the same word in English might have different translations depending on the context. For example, the word "May" could refer to the month or the verb expressing possibility. In these cases, Django's translation context features help you disambiguate these situations to ensure accurate translations.

Translation contexts allow you to provide additional information to translators about where and how a string is used, enabling them to choose the most appropriate translation based on the specific usage.

Understanding Translation Context

In many languages, a single English word can translate differently based on context:

• "Post" might mean a blog post or to send something
• "Order" could refer to a purchase or arrangement
• "Book" could be a noun (reading material) or verb (to reserve)

Without additional context, translators might choose the wrong meaning, leading to confusing translations for users.

Using pgettext for Context-Aware Translations

Django provides the pgettext function (and its lazy counterpart pgettext_lazy) that lets you specify a context along with the string to be translated.

Basic Syntax

python

from django.utils.translation import pgettext, pgettext_lazy

# Immediate translation
translated_text = pgettext("context_marker", "text_to_translate")

# Lazy translation (evaluated when accessed)
translated_text = pgettext_lazy("context_marker", "text_to_translate")

Practical Example

Let's look at a real-world example involving the word "order" which could refer to a purchase order or a sorting order:

python

from django.utils.translation import pgettext

# For a purchase order
order_status = pgettext("purchase", "Order processed successfully")

# For sorting results
sort_message = pgettext("sorting", "Order changed to alphabetical")

In your translation files, these would appear as:

# In your .po file
msgctxt "purchase"
msgid "Order processed successfully"
msgstr "Pedido procesado con éxito"  # Spanish translation for purchase context

msgctxt "sorting"
msgid "Order changed to alphabetical"
msgstr "Ordenación cambiada a alfabética"  # Spanish translation for sorting context

Translation Context in Templates

You can also use translation contexts in your Django templates with the translate template tag:

django

{% translate "Order" context "purchase" %}

For template blocks, use:

django

{% blocktranslate context "sorting" %}
The order has been changed.
{% endblocktranslate %}

Context in Model Fields and Forms

When working with models and forms, you can provide context for field names and help texts:

python

from django.db import models
from django.utils.translation import gettext_lazy as _, pgettext_lazy

class Product(models.Model):
    # Using context for an ambiguous field name
    order = models.IntegerField(
        verbose_name=pgettext_lazy("product", "order"),
        help_text=pgettext_lazy("product", "Position in catalog")
    )
    
    name = models.CharField(
        max_length=100,
        verbose_name=_("name")  # Context not needed here as it's unambiguous
    )

When to Use Translation Context

Use translation context when:

1. A word has multiple meanings depending on usage
2. A phrase might be translated differently based on where it appears
3. You need to provide extra information to translators about intent

For strings that are unambiguous, you can continue using the standard gettext or _ functions.

Real-World Application Example

Let's imagine we're building a calendar application that needs to be translated. The word "date" in English could refer to a calendar date or a romantic engagement.

python

from django.utils.translation import pgettext, gettext as _

# In a calendar view
event_date = pgettext("calendar", "Date")

# In a social feature
date_invitation = pgettext("social", "Date")

# Time is unambiguous, so no context needed
time_label = _("Time")

# Using both in a view
def event_detail(request, event_id):
    event = get_object_or_404(Event, id=event_id)
    context = {
        'date_label': pgettext("calendar", "Date"),
        'event_date': event.date,
        'time_label': _("Time"),
        'event_time': event.time,
    }
    return render(request, 'events/detail.html', context)

The corresponding template might look like:

django

<div class="event-details">
  <div class="field">
    <span class="label">{{ date_label }}:</span>
    <span class="value">{{ event_date|date:"SHORT_DATE_FORMAT" }}</span>
  </div>
  <div class="field">
    <span class="label">{{ time_label }}:</span>
    <span class="value">{{ event_time|time:"H:i" }}</span>
  </div>
</div>

Translating With Context in Message Files

When extracting messages for translation using Django's makemessages command, context-aware strings will appear in the resulting .po files with a msgctxt field:

#: events/views.py:12
msgctxt "calendar"
msgid "Date"
msgstr ""  # Translators will fill this with the appropriate translation

#: events/views.py:13
msgctxt "social"
msgid "Date"
msgstr ""  # This can have a different translation

Translators can then provide the appropriate translation for each context.

Managing Translation Contexts

As your application grows, it's important to:

1. Be consistent with context markers
2. Document context markers for translators
3. Avoid overly specific contexts that might fragment your translations
4. Consider creating a glossary of terms with contexts for your project

Summary

Translation contexts in Django are a powerful feature that helps you provide accurate translations for ambiguous terms based on their usage. By using pgettext, pgettext_lazy, and the context parameter in template tags, you can ensure your translations are precise and natural-sounding across different languages.

Remember these key points:

• Use context when the same word has multiple potential translations
• Be consistent with your context markers
• Only use context when needed for disambiguation
• Document your contexts for translators

Additional Resources

• Django's Translation Documentation
• GNU gettext Manual on Contexts

Exercises

1. Identify five words in your application that might have different translations based on context.
2. Refactor an existing view to use pgettext where appropriate.
3. Create a small glossary for translators explaining the different contexts used in your project.
4. Implement context-aware translations in a template using the translate tag with context.