Skip to main content

Python i18n: ο πλήρης οδηγός τοπικής προσαρμογής

Ρυθμίστε το python-i18n με αρχεία μετάφρασης JSON ή YAML, χειριστείτε placeholders και πληθυντικούς και αυτοματοποιήστε τις μεταφράσεις με AI.

1

Εγκαταστήστε το python-i18n

Το python-i18n είναι μια ελαφριά βιβλιοθήκη διεθνοποίησης για Python. Υποστηρίζει αρχεία μετάφρασης JSON και YAML, ένθετα κλειδιά, παρεμβολή placeholders και πληθυντικούς χωρίς πρόσθετη διαμόρφωση.

Terminal
pip install python-i18n
Το python-i18n υποστηρίζει JSON από προεπιλογή. Για αρχεία μετάφρασης YAML, εγκαταστήστε την προαιρετική εξάρτηση YAML με pip install python-i18n[YAML], η οποία προσθέτει το PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Διαμορφώστε τις μεταφράσεις

Ορίστε τη μορφή αρχείου, προσθέστε διαδρομές αρχείων μετάφρασης και διαμορφώστε την προεπιλεγμένη και την εναλλακτική γλώσσα. Εισαγάγετε αυτή τη διαμόρφωση στο σημείο εισόδου της εφαρμογής πριν από οποιαδήποτε κλήση μετάφρασης.

i18n_config.py
import i18n

# Set the file format (json or yaml)
i18n.set("file_format", "json")

# Add the directory containing your translation files
i18n.load_path.append("translations/")

# Set the default locale
i18n.set("locale", "en")

# Set the fallback locale (used when a key is missing)
i18n.set("fallback", "en")

# Enable/disable error on missing translations
i18n.set("error_on_missing_translation", False)
Το load_path πρέπει να δείχνει στον κατάλογο που περιέχει τα αρχεία μετάφρασης και όχι σε συγκεκριμένο αρχείο. Αν οι μεταφράσεις επιστρέφουν τα ανεπεξέργαστα κλειδιά, ελέγξτε ότι το load_path είναι σωστό και ότι τα ονόματα αρχείων αντιστοιχούν στους κωδικούς γλώσσας, για παράδειγμα en.json και de.json.
3

Δημιουργήστε αρχεία μετάφρασης

Δημιουργήστε ένα αρχείο ανά γλώσσα σε μορφή JSON ή YAML. Χρησιμοποιήστε ένθετα κλειδιά για να οργανώσετε τις συμβολοσειρές ανά λειτουργία ή σελίδα. Διατηρήστε την αρχική γλώσσα, συνήθως τα Αγγλικά, ως τη μοναδική αξιόπιστη πηγή.

translations/en.json
// translations/en.json
{
  "greeting": "Hello!",
  "welcome": "Welcome to our application",
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "cart": {
    "item_count": "%{count} item(s) in your cart"
  }
}

// translations/de.json
{
  "greeting": "Hallo!",
  "welcome": "Willkommen in unserer Anwendung",
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "cart": {
    "item_count": "%{count} Artikel in Ihrem Warenkorb"
  }
}
Ονομάστε τα κλειδιά βάσει αυτού που περιγράφουν και όχι του σημείου όπου εμφανίζονται: το 'cart.item_count' είναι καλύτερο από το 'homepage_cart_label'. Τα κλειδιά πρέπει να παραμένουν κατάλληλα ακόμη και μετά από ανασχεδιασμό του UI.
4

Χρησιμοποιήστε μεταφράσεις στον κώδικά σας

Καλέστε το i18n.t() με μια διαδρομή κλειδιού χωρισμένη με τελείες για να αναζητήσετε μεταφρασμένες συμβολοσειρές. Μπορείτε να παρακάμψετε τη γλώσσα ανά κλήση χωρίς να αλλάξετε την καθολική ρύθμιση.

app.py
import i18n

# Simple translation
print(i18n.t("greeting"))          # "Hello!"
print(i18n.t("nav.home"))          # "Home"
print(i18n.t("nav.about"))         # "About"

# Translation with a specific locale
print(i18n.t("greeting", locale="de"))   # "Hallo!"
print(i18n.t("nav.home", locale="ja"))   # "ホーム"

# Missing key returns a placeholder
print(i18n.t("missing.key"))       # "Missing.Key"
Τα ένθετα κλειδιά χρησιμοποιούν σημειογραφία τελείας: i18n.t('nav.home'). Αν τα κλειδιά JSON περιέχουν κυριολεκτικές τελείες, το python-i18n θα τις ερμηνεύσει ως διαχωριστικά ένθεσης. Αποφύγετε τις τελείες στα ονόματα κλειδιών.
5

Placeholders και πληθυντικοί

Το python-i18n υποστηρίζει παρεμβολή placeholders με τη σύνταξη %{name} και βασικούς πληθυντικούς με τα δευτερεύοντα κλειδιά 'zero', 'one' και 'many'. Περάστε ορίσματα λέξεων-κλειδιών στο i18n.t() και για τις δύο δυνατότητες.

Placeholders
# translations/en.json
# {
#   "welcome_user": "Welcome, %{name}!",
#   "order_status": "Order #%{order_id}: %{status}",
#   "file_size": "File size: %{size} %{unit}"
# }

import i18n

# Single placeholder
print(i18n.t("welcome_user", name="Alice"))
# "Welcome, Alice!"

# Multiple placeholders
print(i18n.t("order_status", order_id=12345, status="shipped"))
# "Order #12345: shipped"

# Reusable with different values
print(i18n.t("file_size", size=2.5, unit="MB"))
# "File size: 2.5 MB"

print(i18n.t("file_size", size=800, unit="KB"))
# "File size: 800 KB"
Pluralization
# translations/en.json
# {
#   "inbox": {
#     "zero": "No messages",
#     "one": "1 message",
#     "many": "%{count} messages"
#   }
# }

import i18n

print(i18n.t("inbox", count=0))    # "No messages"
print(i18n.t("inbox", count=1))    # "1 message"
print(i18n.t("inbox", count=42))   # "42 messages"
Οι πληθυντικοί του python-i18n χρησιμοποιούν τρεις κατηγορίες: zero, one και many. Αυτές καλύπτουν τα Αγγλικά και πολλές άλλες γλώσσες, αλλά όχι όλους τους κανόνες πληθυντικού CLDR (few, two, other). Για γλώσσες όπως τα Αραβικά, τα Ρωσικά ή τα Πολωνικά, οι οποίες έχουν σύνθετους πληθυντικούς, ίσως χρειαστεί να χειριστείτε τις οριακές περιπτώσεις χειροκίνητα ή να χρησιμοποιήσετε μια πιο προηγμένη βιβλιοθήκη.
6

Αλλάξτε γλώσσα κατά την εκτέλεση

Αλλάξτε καθολικά την ενεργή γλώσσα με i18n.set('locale', code) ή παρακάμψτε την ανά κλήση με το όρισμα λέξης-κλειδιού locale. Στα framework για Web, εντοπίστε την προτιμώμενη γλώσσα του χρήστη από το αίτημα και ορίστε την πριν από την απόδοση.

Locale switching
import i18n

# Set locale globally
i18n.set("locale", "de")
print(i18n.t("greeting"))           # "Hallo!"

# Switch to Japanese
i18n.set("locale", "ja")
print(i18n.t("greeting"))           # "こんにちは！"

# Override per-call without changing global locale
i18n.set("locale", "en")
print(i18n.t("greeting"))           # "Hello!"
print(i18n.t("greeting", locale="de"))  # "Hallo!"
app.py
from flask import Flask, request, g
import i18n

app = Flask(__name__)

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

SUPPORTED_LOCALES = ["en", "de", "ja", "es", "fr"]

@app.before_request
def set_locale():
    # Check URL parameter, cookie, then Accept-Language header
    locale = request.args.get("lang")
    if not locale:
        locale = request.cookies.get("locale")
    if not locale:
        locale = request.accept_languages.best_match(SUPPORTED_LOCALES)
    g.locale = locale or "en"
    i18n.set("locale", g.locale)

@app.route("/")
def index():
    return i18n.t("welcome")
Το i18n.set('locale', ...) αλλάζει καθολικά τη γλώσσα. Σε πολυνηματικούς διακομιστές Web, όπως gunicorn με workers ή Django, αυτό μπορεί να προκαλέσει συνθήκες ανταγωνισμού, όπου ένα αίτημα αλλάζει τη γλώσσα ενώ ένα άλλο βρίσκεται στη μέση της απόδοσης. Χρησιμοποιήστε παρακάμψεις γλώσσας ανά κλήση ή τοπική αποθήκευση ανά νήμα.
7

Έξυπνη εναλλακτική επιλογή γλώσσας με το python-i18n-locale-chain

Από προεπιλογή, το python-i18n υποστηρίζει μόνο μία εναλλακτική γλώσσα. Όταν ένας χρήστης με γλώσσα pt-BR δεν διαθέτει μεταφράσεις pt-BR, η βιβλιοθήκη μεταβαίνει απευθείας στην εναλλακτική αγγλική έκδοση, αγνοώντας πλήρεις μεταφράσεις pt-PT. Το python-i18n-locale-chain το διορθώνει με διαμορφώσιμες αλυσίδες εναλλακτικής επιλογής που καλύπτουν 75 παραλλαγές γλώσσας.

Το python-i18n-locale-chain είναι ένα δωρεάν πακέτο ανοικτού κώδικα. Μία κλήση συνάρτησης ενεργοποιεί 75 ενσωματωμένες αλυσίδες εναλλακτικής επιλογής για περιφερειακές παραλλαγές των Κινεζικών, Πορτογαλικών, Ισπανικών, Γαλλικών, Γερμανικών, Ιταλικών, Ολλανδικών, Αγγλικών, Αραβικών, Νορβηγικών και Μαλαϊκών.
Terminal
pip install python-i18n-locale-chain
i18n_config.py
from locale_chain import configure
import i18n

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

# Activate smart fallback chains (75 built-in chains)
configure()

# Now pt-BR falls back to pt-PT -> pt -> en (instead of just en)
result = i18n.t("greeting", locale="pt-BR")

# es-MX falls back to es-419 -> es -> en
result = i18n.t("greeting", locale="es-MX")

# zh-Hant-HK falls back to zh-Hant-TW -> zh-Hant -> en
result = i18n.t("greeting", locale="zh-Hant-HK")
Advanced configuration
from locale_chain import configure, reset

# Override specific chains
configure(overrides={
    "pt-BR": ["pt"],         # Skip pt-PT, go straight to pt
    "ja-JP": ["ja"],         # Add a new chain
})

# Full custom map (no defaults)
configure(
    fallbacks={"pt-BR": ["pt-PT"]},
    merge_defaults=False
)

# Use German as final fallback instead of English
configure(default_locale="de")

# Restore original i18n.t() behaviour
reset()
Οι σημαντικότερες αλυσίδες προς δοκιμή είναι: pt-BR -> pt-PT -> pt -> en (Πορτογαλικά), es-MX -> es-419 -> es -> en (Ισπανικά), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (Παραδοσιακά Κινεζικά). Καλύπτουν τα συνηθέστερα σενάρια περιφερειακής εναλλακτικής επιλογής.
8

Αυτοματοποιήστε τις μεταφράσεις

Αφού ολοκληρώσετε τη ρύθμιση i18n, μεταφράστε τα αρχεία γλωσσών με AI. Ζητήστε από τον βοηθό AI στο IDE να μεταφράσει το αρχικό αρχείο ή χρησιμοποιήστε το i18n Agent CLI στη διοχέτευση CI/CD.

Terminal
# In your IDE, ask your AI assistant:
> Translate translations/en.json to German, Japanese, and Spanish

translations/de.json created (1.2s)
translations/ja.json created (1.5s)
translations/es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate translations/en.json --lang de,ja,es
Μεταφράζετε σταδιακά. Όταν προσθέτετε νέα κλειδιά στο αρχικό αρχείο, μεταφράζετε μόνο τις διαφορές αντί να δημιουργείτε ξανά όλα τα αρχεία. Έτσι διατηρούνται οι μεταφράσεις που έχουν ελεγχθεί από άνθρωπο.

Αυτοματοποιήστε τον έλεγχο ποιότητας των μεταφράσεων

Εντοπίστε κλειδιά που λείπουν και λανθασμένα placeholders πριν φτάσουν στην παραγωγή με το i18n-validate. Δοκιμάστε το UI με ψευδομεταφράσεις χρησιμοποιώντας το i18n-pseudo πριν είναι διαθέσιμες οι πραγματικές μεταφράσεις.

Συνηθισμένες παγίδες

Οι μεταφράσεις επιστρέφουν ανεπεξέργαστα κλειδιά

Αιτίες: το load_path δεν έχει οριστεί ή δείχνει σε λανθασμένο κατάλογο, το file_format δεν αντιστοιχεί στις επεκτάσεις αρχείων ή τα ονόματα αρχείων δεν αντιστοιχούν στους κωδικούς γλώσσας. Βεβαιωθείτε ότι το i18n.load_path περιέχει τον σωστό κατάλογο και ότι τα αρχεία έχουν ονομαστεί σωστά, για παράδειγμα en.json και de.json.

Τα αρχεία YAML δεν φορτώνονται

Το python-i18n απαιτεί το PyYAML για υποστήριξη YAML, αλλά δεν εγκαθίσταται από προεπιλογή. Εγκαταστήστε το με pip install python-i18n[YAML]. Χωρίς αυτό, τα αρχεία YAML αγνοούνται χωρίς προειδοποίηση και οι μεταφράσεις επιστρέφουν placeholders για τα κλειδιά που λείπουν.

Οι αναζητήσεις ένθετων κλειδιών αποτυγχάνουν

Το python-i18n χρησιμοποιεί σημειογραφία τελείας για ένθετα κλειδιά: i18n.t('nav.home'). Αν το JSON χρησιμοποιεί επίπεδα κλειδιά με τελείες στο όνομα, για παράδειγμα το 'nav.home' ως ένα ενιαίο κλειδί, η βιβλιοθήκη το ερμηνεύει ως ένθετη αναζήτηση και αποτυγχάνει. Χρησιμοποιήστε πραγματικά ένθετα αντικείμενα JSON.

Οι αλλαγές γλώσσας διαρρέουν μεταξύ αιτημάτων

Το i18n.set('locale', ...) είναι καθολική λειτουργία. Σε πολυνηματικούς διακομιστές, ένα αίτημα μπορεί να αλλάξει τη γλώσσα ενώ αποδίδεται ένα άλλο. Χρησιμοποιήστε το όρισμα λέξης-κλειδιού locale= σε κάθε κλήση i18n.t() ή ορίστε τη γλώσσα σε αποθήκευση τοπική για κάθε νήμα μέσω middleware.

Προτεινόμενη δομή αρχείων

Project Structure
my-python-app/
├── translations/
│   ├── en.json           # Source language (JSON)
│   ├── de.json           # German
│   ├── ja.json           # Japanese
│   ├── es.json           # Spanish
│   └── pt-BR.json        # Brazilian Portuguese
├── app.py                # Application entry point
├── i18n_config.py        # i18n setup and configuration
├── requirements.txt      # pip dependencies
└── pyproject.toml        # Project metadata

# Or with YAML files:
my-python-app/
├── translations/
│   ├── en.yml
│   ├── de.yml
│   └── ja.yml
├── app.py
└── ...

Μεταφράστε επίσης:

Δοκιμάστε τώρα το i18n Agent

Αφήστε εδώ το αρχείο μετάφρασής σας

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

ή κάντε κλικ για να επιλέξετε αρχείο

Γλώσσες-στόχοι

Δεν απαιτείται εγγραφήΆμεση εκτίμηση

Εναλλακτική επιλογή γλώσσας με το python-i18n-locale-chain

Όταν λείπει ένα κλειδί μετάφρασης σε μια περιφερειακή γλώσσα όπως το es-419, το python-i18n μεταβαίνει απευθείας στην προεπιλεγμένη γλώσσα αντί να ελέγξει πρώτα τη γονική γλώσσα es.

Terminal
pip install python-i18n-locale-chain
Configuration
from i18n_locale_chain import configure_chain

configure_chain('{')
    'es': ['en', 'ru'],
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
'}')

# Usage: t('greeting', locale='es') — falls back through chain

Δείτε τον οδηγό μας για την εναλλακτική επιλογή γλώσσας, με την πλήρη λίστα των υποστηριζόμενων framework και 75 ενσωματωμένων αλυσίδων. Learn more →

Συχνές ερωτήσεις