
Django i18n: Průvodce internacionalizací a překladem
Od settings.py až po produkci: nakonfigurujte překladový systém v Django, pište PO soubory, řešte plurály a automatizujte překlady pomocí AI.
Nainstalovat a extrahovat řetězce
Framework i18n je v Django vestavěný — stačí ho povolit. Nainstalujte django-locale-chain pro chytré fallbacky lokalizací a poté použijte makemessages k extrakci přeložitelných řetězců z Python kódu a šablon do PO souborů.
pip install django-locale-chain# Extract all translatable strings from Python and template files
python manage.py makemessages -l de -l ja -l es -l fr
# After translating .po files, compile to .mo (binary)
python manage.py compilemessages
# Project structure after running makemessages:
# locale/
# ├── de/
# │ └── LC_MESSAGES/
# │ ├── django.po <-- translate this
# │ └── django.mo <-- compiled (auto-generated)
# ├── ja/
# │ └── LC_MESSAGES/
# │ ├── django.po
# │ └── django.mo
# └── es/
# └── LC_MESSAGES/
# ├── django.po
# └── django.moNakonfigurovat settings a middleware
Povolte internacionalizaci v settings.py nastavením USE_I18N = True, definujte seznam podporovaných LANGUAGES a přidejte LocaleMiddleware do zásobníku MIDDLEWARE. LocaleMiddleware detekuje jazyk uživatele z URL prefixu, session, cookies nebo hlavičky Accept-Language.
# settings.py
from django.utils.translation import gettext_lazy as _
# Default language
LANGUAGE_CODE = 'en'
# Enable i18n
USE_I18N = True
USE_L10N = True
# Languages your site supports
LANGUAGES = [
('en', _('English')),
('de', _('German')),
('ja', _('Japanese')),
('es', _('Spanish')),
('fr', _('French')),
('pt-br', _('Brazilian Portuguese')),
]
# Where Django looks for .po files
LOCALE_PATHS = [
BASE_DIR / 'locale',
]
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.locale.LocaleMiddleware', # <-- enables i18n
'locale_chain.middleware.LocaleChainMiddleware', # <-- smart fallbacks
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware',
]Internacionalizace URL
Použijte i18n_patterns() k automatickému prefixování Vašich URL aktivním jazykovým kódem. Každý jazyk tak získá vlastní URL namespace (/en/about/, /de/about/), což je lepší pro SEO a umožní uživatelům sdílet odkazy specifické pro daný jazyk.
# urls.py
from django.conf.urls.i18n import i18n_patterns
from django.urls import path, include
urlpatterns = [
# Non-localized URLs (API, admin, etc.)
path('api/', include('api.urls')),
]
urlpatterns += i18n_patterns(
# These get prefixed with the language code: /en/about/, /de/about/
path('', include('myapp.urls')),
path('admin/', admin.site.urls),
prefix_default_language=False, # Skip prefix for default language
)Označit řetězce k překladu
Django poskytuje dvě hlavní překladové funkce: gettext() (alias _()) pro řetězce vyhodnocované při zpracování požadavku a gettext_lazy() pro řetězce vyhodnocované při importu. V šablonách použijte značky {% trans %} a {% blocktrans %}.
Ve views (Python kód)
from django.utils.translation import gettext as _
from django.utils.translation import ngettext
from django.http import HttpResponse
def greeting_view(request):
# Simple translation
welcome = _("Welcome to our site")
# Translation with variables (Python string formatting)
user_greeting = _("Hello, %(name)s!") % {"name": request.user.username}
# Plurals
count = request.user.order_set.count()
order_text = ngettext(
"You have %(count)d order.",
"You have %(count)d orders.",
count,
) % {"count": count}
return HttpResponse(f"{welcome}<br>{user_greeting}<br>{order_text}")V šablonách
{# Load the i18n template tags #}
{% load i18n %}
{# Simple translation #}
<h1>{% trans "Welcome to our site" %}</h1>
{# Translation with variables #}
{% blocktrans with name=user.username %}
Hello, {{ name }}!
{% endblocktrans %}
{# Plurals in templates #}
{% blocktrans count count=order_count %}
You have {{ count }} order.
{% plural %}
You have {{ count }} orders.
{% endblocktrans %}
{# Mark strings as translatable but don't output them (for attributes, etc.) #}
{% trans "Submit" as submit_label %}
<button type="submit">{{ submit_label }}</button>V modelech a formulářích
from django.db import models
from django.utils.translation import gettext_lazy as _
class Product(models.Model):
name = models.CharField(_("product name"), max_length=200)
description = models.TextField(_("description"), blank=True)
class Meta:
verbose_name = _("product")
verbose_name_plural = _("products")
def __str__(self):
return self.name
# IMPORTANT: Use gettext_lazy (_) for anything evaluated at import time:
# - Model field labels, verbose_name, help_text
# - Form field labels
# - Class-level attributes
# Use gettext for anything evaluated at request time:
# - View functions, template tagsFormát PO souborů
Po spuštění makemessages Django vygeneruje pro každý jazyk soubory .po (Portable Object). Ty obsahují dvojice msgid/msgstr. Přeložte hodnoty msgstr a poté spusťte compilemessages, aby se vygenerovaly binární soubory .mo, které Django načítá za běhu.
# locale/de/LC_MESSAGES/django.po
msgid "Welcome to our site"
msgstr "Willkommen auf unserer Seite"
msgid "Hello, %(name)s!"
msgstr "Hallo, %(name)s!"
#, python-format
msgid "You have %(count)d order."
msgid_plural "You have %(count)d orders."
msgstr[0] "Sie haben %(count)d Bestellung."
msgstr[1] "Sie haben %(count)d Bestellungen."
msgid "product name"
msgstr "Produktname"
msgid "description"
msgstr "Beschreibung"
msgid "product"
msgstr "Produkt"
msgid "products"
msgstr "Produkte"
msgid "Submit"
msgstr "Absenden"Zpracovat plurály a proměnné
Django používá pro pluralizaci ngettext(), které se řídí pravidly plurálů GNU gettext. Každý jazyk definuje, kolik má tvarů množného čísla, a vzorec pro výběr správného tvaru. PO soubory to deklarují v hlavičce Plural-Forms.
# English: 2 forms (singular, plural)
msgid "%(count)d item"
msgid_plural "%(count)d items"
msgstr[0] "%(count)d item"
msgstr[1] "%(count)d items"
# German: 2 forms (singular, plural)
msgstr[0] "%(count)d Artikel"
msgstr[1] "%(count)d Artikel"
# Russian: 3 forms (one, few, many)
msgstr[0] "%(count)d товар" # 1 item
msgstr[1] "%(count)d товара" # 2-4 items
msgstr[2] "%(count)d товаров" # 5+ items
# Arabic: 6 forms (zero, one, two, few, many, other)
msgstr[0] "لا عناصر" # 0
msgstr[1] "عنصر واحد" # 1
msgstr[2] "عنصران" # 2
msgstr[3] "%(count)d عناصر" # 3-10
msgstr[4] "%(count)d عنصرًا" # 11-99
msgstr[5] "%(count)d عنصر" # 100+
# Japanese: 1 form (no plural distinction)
msgstr[0] "%(count)d個のアイテム"
# In Python code, always use ngettext:
from django.utils.translation import ngettext
msg = ngettext(
"%(count)d item",
"%(count)d items",
count,
) % {"count": count}Automatizovat kvalitu překladu
Běžná úskalí
Záměna gettext() a gettext_lazy()
Zapomenuté spuštění compilemessages
LOCALE_PATHS není nakonfigurováno
Chybějící i18n_patterns v URLs
Chytré fallbacky lokalizací s django-locale-chain
Překladový systém v Django při chybějící regionální variantě fallbackuje přímo na LANGUAGE_CODE. Uživatel pt-BR tak uvidí angličtinu i tehdy, když máte překlady pt-PT. django-locale-chain to řeší instalací fallback řetězců gettext: pt-BR zkusí pt-PT, potom pt, a teprve pak fallbackuje na Váš výchozí jazyk.
# settings.py -- Smart fallback with django-locale-chain
# pip install django-locale-chain
MIDDLEWARE = [
# ...
'django.middleware.locale.LocaleMiddleware',
'locale_chain.middleware.LocaleChainMiddleware', # after LocaleMiddleware
# ...
]
# That's it! 75 built-in fallback chains are now active:
# pt-BR user → tries pt-PT → tries pt → falls back to LANGUAGE_CODE
# es-MX user → tries es-419 → tries es → falls back to LANGUAGE_CODE
# fr-CA user → tries fr → falls back to LANGUAGE_CODE
# Optional: customize specific chains
LOCALE_FALLBACK_CHAINS = {
"pt-BR": ["pt-PT", "pt"],
"es-MX": ["es-419", "es"],
"fr-CA": ["fr"],
}
# Or configure programmatically in AppConfig.ready():
from locale_chain import configure
class MyAppConfig(AppConfig):
name = "myapp"
def ready(self):
configure(overrides={"zh-Hant-HK": ["zh-Hant-TW", "zh-Hant"]})Doporučená struktura projektu
myproject/
├── myproject/
│ ├── settings.py # i18n config, MIDDLEWARE, LANGUAGES
│ ├── urls.py # i18n_patterns for URL prefixing
│ └── wsgi.py
├── myapp/
│ ├── models.py # gettext_lazy for field labels
│ ├── views.py # gettext for request-time strings
│ └── templates/
│ └── myapp/
│ └── index.html # {% load i18n %}, {% trans %}, {% blocktrans %}
├── locale/ # Created by makemessages
│ ├── de/
│ │ └── LC_MESSAGES/
│ │ ├── django.po # German translations
│ │ └── django.mo # Compiled binary
│ ├── ja/
│ │ └── LC_MESSAGES/
│ │ ├── django.po
│ │ └── django.mo
│ └── es/
│ └── LC_MESSAGES/
│ ├── django.po
│ └── django.mo
├── manage.py
└── requirements.txtVyzkoušejte i18n Agent nyní
Sem přetáhněte svůj překladový soubor
JSON, YAML, PO, XML, CSV, Markdown, Properties
nebo klikněte a vyberte soubor
Cílové jazyky
Fallback lokalizací s django-locale-chain
Když v regionální lokalizaci, jako je pt-BR, chybí překladový klíč, Django skočí rovnou na jazyk šablony místo toho, aby nejdřív zkontrolovalo nadřazené pt.
pip install django-locale-chain# settings.py
LOCALE_CHAINS = {
'pt-BR': ['pt', 'es', 'en'],
'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
}
MIDDLEWARE = [
...
'django_locale_chain.middleware.LocaleChainMiddleware',
...
]Podívejte se do našeho Průvodce fallbackem lokalizací, kde najdete kompletní seznam podporovaných frameworků a 75 vestavěných řetězců. Learn more →