Skip to main content

Django i18n: Leiðarvísir um alþjóðavæðingu og þýðingar

Frá settings.py til rekstrarumhverfis: stilltu þýðingarkerfi Django, skrifaðu PO-skrár, meðhöndlaðu fleirtölumyndir og gerðu þýðingar sjálfvirkar með gervigreind.

1

Settu upp og sæktu strengi

i18n-rammi Django er innbyggður -- þú þarft aðeins að virkja hann. Settu upp django-locale-chain fyrir snjallar varaleiðir staðfærslna og notaðu síðan makemessages til að sækja þýðanlega strengi úr Python-kóðanum þínum og sniðmátum í PO-skrár.

Django notar GNU gettext undir niðri. Skipunin makemessages leitar í kóðanum þínum að gettext-köllum og sniðmátsmörkum og býr síðan til .po-skrár. Að þýðingu lokinni umbreytir compilemessages þeim í tvíundarskrár á .mo-sniði svo hægt sé að fletta þýðingum hratt upp við keyrslu.
Terminal
pip install django-locale-chain
Terminal
# 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.mo
2

Stilltu stillingar og millibúnað

Virkjaðu alþjóðavæðingu í settings.py með því að stilla USE_I18N = True, skilgreina listann LANGUAGES yfir studd tungumál og bæta LocaleMiddleware við MIDDLEWARE-staflann. LocaleMiddleware greinir tungumál notandans út frá forskeyti vefslóðarinnar, setu, vafrakökum eða Accept-Language-hausnum.

settings.py
# 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',
]
LocaleMiddleware verður að koma á eftir SessionMiddleware (það les setuna) og á undan CommonMiddleware. Ef því er komið fyrir í rangri röð mistekst tungumálagreining án viðvörunar og allir notendur sjá sjálfgefna LANGUAGE_CODE.

Alþjóðavæðing vefslóða

Notaðu i18n_patterns() til að bæta virka tungumálskóðanum sjálfkrafa sem forskeyti við vefslóðirnar þínar. Þannig fær hvert tungumál eigið nafnrými vefslóða (/en/about/, /de/about/), sem bætir leitarvélabestun og gerir notendum kleift að deila tungumálssértækum tenglum.

urls.py
# 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
)
3

Merktu strengi til þýðingar

Django býður upp á tvö meginþýðingarföll: gettext() (með samheitinu _()) fyrir strengi sem eru metnir þegar beiðni er afgreidd og gettext_lazy() fyrir strengi sem eru metnir við innflutning. Notaðu mörkin {% trans %} og {% blocktrans %} í sniðmátum.

Í sýnum (Python-kóða)

views.py
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}")

Í sniðmátum

templates/myapp/index.html
{# 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>

Í líkönum og eyðublöðum

models.py
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 tags
Ef gettext() er notað í stað gettext_lazy() í líkanareitum, heitum eyðublaðsreita eða eigindum á klasastigi eru strengirnir aðeins þýddir einu sinni við innflutning (þegar þjónninn ræsist) í stað þess að vera þýddir fyrir hverja beiðni. Þýðingin festist á því tungumáli sem var virkt við innflutning -- yfirleitt sjálfgefnu LANGUAGE_CODE.

Snið PO-skráa

Eftir að makemessages hefur verið keyrt býr Django til .po-skrár (Portable Object) fyrir hvert tungumál. Þær innihalda msgid/msgstr-pör. Þýddu msgstr-gildin og keyrðu síðan compilemessages til að búa til tvíundarskrárnar á .mo-sniði sem Django les við keyrslu.

locale/de/LC_MESSAGES/django.po
# 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"
4

Meðhöndlaðu fleirtölumyndir og breytur

Django notar ngettext() fyrir fleirtölubeygingu samkvæmt fleirtölureglum GNU gettext. Hvert tungumál skilgreinir fjölda fleirtölumynda og formúluna sem velur rétta mynd. PO-skrár lýsa þessu með Plural-Forms-haus.

Plural forms by language
# 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}
Notaðu aldrei f-strengi úr Python eða .format() inni í gettext-köllum. Þýðingarútdrátturinn getur ekki þáttað þá. Notaðu eldri %()-sniðun: _('Hello, %(name)s!') % {'name': name}. Þannig er einnig tryggt að þýðendur sjái breytustaðgenglana í PO-ritlunum sínum.

Gerðu gæði þýðinga sjálfvirk

Finndu lykla sem vantar og skemmd staðgengi áður en þau fara í útgáfu með i18n-validate. Prófaðu notandaviðmótið með gerviþýðingum með i18n-pseudo áður en raunverulegar þýðingar berast.

Algengar gryfjur

Ruglingur á gettext() og gettext_lazy()

Notaðu gettext_lazy() (flutt inn sem _) fyrir líkanareiti, heiti eyðublaðsreita og allar eigindir á klasastigi sem eru metnar við innflutning. Notaðu gettext() fyrir sýnaföll og kóða sem keyrir við afgreiðslu beiðna. Ef þessu er ruglað saman festast þýðingar á því tungumáli sem var virkt þegar þjónninn ræstist.

Gleymdist að keyra compilemessages

Django les samsettar .mo-skrár, ekki .po-skrár. Ef þú breytir .po-skrá og keyrir ekki 'python manage.py compilemessages' birtast breytingarnar ekki. Bættu compilemessages við útsetningarforskriftina þína.

LOCALE_PATHS ekki stillt

Ef LOCALE_PATHS er tómt eða vísar á ranga möppu býr makemessages til .po-skrár á röngum stað og Django finnur þær ekki við keyrslu. Stilltu alltaf LOCALE_PATHS = [BASE_DIR / 'locale'] og sannreyndu að mappan sé til.

i18n_patterns vantar í vefslóðir

Án i18n_patterns() hafa vefslóðir ekkert tungumálaforskeyti og Django reiðir sig eingöngu á vafrakökur/hausa við tungumálagreiningu. Þetta skaðar leitarvélabestun (engar tungumálssértækar vefslóðir) og kemur í veg fyrir tungumálaskipti um vefslóð. Settu mynstur notendamiðaðra vefslóða innan i18n_patterns().

Snjallar varaleiðir staðfærslna með django-locale-chain

Þýðingarkerfi Django fellur beint aftur á LANGUAGE_CODE þegar svæðisbundið afbrigði vantar. Notandi með pt-BR sér ensku jafnvel þótt þú sért með pt-PT-þýðingar. django-locale-chain lagar þetta með því að setja upp gettext-varakeðjur: pt-BR prófar pt-PT og síðan pt áður en fallið er aftur á sjálfgefna tungumálið þitt.

settings.py
# 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"]})

Ráðlögð verkefnaskipan

Project Structure
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.txt

Þýddu einnig:

Prófaðu i18n Agent núna

Slepptu þýðingarskránni þinni hér

JSON, YAML, PO, XML, CSV, Markdown, Properties

eða smelltu til að fletta

Markmál

Engin skráning nauðsynlegKostnaðaráætlun samstundis

Varaleið staðfærslu með django-locale-chain

Þegar þýðingarlykil vantar í svæðisbundna staðfærslu eins og pt-BR stekkur Django beint í tungumál sniðmátsins í stað þess að kanna fyrst yfirstaðfærsluna pt.

Terminal
pip install django-locale-chain
Configuration
# settings.py
LOCALE_CHAINS = {
    'pt-BR': ['pt', 'es', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
}

MIDDLEWARE = [
    ...
    'django_locale_chain.middleware.LocaleChainMiddleware',
    ...
]

Sjá leiðarvísi okkar um varaleiðir staðfærslna til að fá allan listann yfir studda ramma og 75 innbyggðar keðjur. Learn more →

Algengar spurningar