Skip to main content

Python i18n: Ítarlegur leiðarvísir um staðfærslu

Settu upp python-i18n með JSON- eða YAML-þýðingarskrám, meðhöndlaðu staðgengla og fleirtölumyndir og sjálfvirknivæddu síðan þýðingar með gervigreind.

1

Settu upp python-i18n

python-i18n er létt alþjóðavæðingarsafn fyrir Python. Það styður JSON- og YAML-þýðingarskrár, falda lykla, innskot breytugilda með staðgenglum og fleirtölubeygingu án viðbótaruppsetningar.

Terminal
pip install python-i18n
python-i18n styður JSON sjálfgefið. Fyrir YAML-þýðingarskrár skaltu setja upp valfrjálsa YAML-stoðpakkann með pip install python-i18n[YAML], sem bætir PyYAML við.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Grunnstilltu þýðingar

Stilltu skráarsniðið, bættu við slóðum að þýðingarskrám og grunnstilltu sjálfgefnu staðfærsluna og varastaðfærsluna. Flyttu þessa grunnstillingu inn á inngangsstað forritsins áður en kallað er á þýðingar.

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 verður að vísa í möppuna sem inniheldur þýðingarskrárnar, ekki í tiltekna skrá. Ef þýðingarnar skila óunnum lyklum skaltu ganga úr skugga um að load_path sé rétt og að skráaheitin samsvari staðfærslukóðunum þínum (t.d. en.json, de.json).
3

Búðu til þýðingarskrár

Búðu til eina skrá fyrir hvert tungumál á JSON- eða YAML-sniði. Notaðu falda lykla til að flokka strengi eftir eiginleika eða síðu. Láttu frummálið (yfirleitt ensku) vera eina uppruna sannleikans.

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"
  }
}
Nefndu lykla eftir því sem þeir lýsa, ekki hvar þeir birtast: 'cart.item_count' er betra en 'homepage_cart_label'. Lyklarnir ættu að halda gildi sínu þótt notandaviðmótið sé endurhannað.
4

Notaðu þýðingar í kóðanum

Kallaðu á i18n.t() með lykilslóð sem er aðskilin með punktum til að fletta upp þýddum strengjum. Þú getur yfirritað staðfærsluna í hverju kalli án þess að breyta víðvægu stillingunni.

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"
Faldir lyklar nota punktaritun: i18n.t('nav.home'). Ef JSON-lyklarnir þínir innihalda bókstaflega punkta túlkar python-i18n þá sem aðgreini falinna stiga. Forðastu punkta í lyklaheitum.
5

Staðgenglar og fleirtölubeyging

python-i18n styður innskot breytugilda með staðgenglum sem nota málskipanina %{name} og einfalda fleirtölubeygingu með undirlyklunum 'zero', 'one' og 'many'. Gefðu i18n.t() nafngreind viðföng fyrir hvort tveggja.

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"
Fleirtölubeyging python-i18n notar þrjá flokka: zero, one og many. Það nægir fyrir ensku og mörg önnur tungumál en styður ekki allar fleirtölureglur CLDR (few, two, other). Fyrir tungumál á borð við arabísku, rússnesku eða pólsku, sem hafa flóknar fleirtölumyndir, gætirðu þurft að meðhöndla jaðartilvik handvirkt eða nota þróaðra safn.
6

Skiptu um staðfærslu við keyrslu

Skiptu um virku staðfærsluna víðvært með i18n.set('locale', code) eða yfirritaðu hana í hverju kalli með nafngreinda viðfanginu locale. Í vefverkramma skaltu greina valið tungumál notandans úr beiðninni og stilla staðfærsluna fyrir myndgerð.

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', ...) breytir staðfærslunni víðvært. Í fjölþráða vefþjónum (gunicorn með workers, Django) getur það valdið kapphlaupi þar sem ein beiðni breytir staðfærslunni meðan önnur er í miðri myndgerð. Notaðu yfirritun staðfærslu í hverju kalli eða þráðbundna geymslu til að forðast þetta.
7

Snjöll varaleit staðfærslna með python-i18n-locale-chain

Sjálfgefið styður python-i18n aðeins eina varastaðfærslu. Þegar engar pt-BR-þýðingar eru til fyrir notanda með pt-BR fer safnið beint í ensku varastaðfærsluna og hunsar fullgildar pt-PT-þýðingar. python-i18n-locale-chain lagar þetta með stillanlegum varakeðjum fyrir 75 staðfærsluafbrigði.

python-i18n-locale-chain er ókeypis pakki með opnum hugbúnaði. Eitt fallskall virkjar 75 innbyggðar varaleitarkeðjur fyrir svæðisbundin afbrigði kínversku, portúgölsku, spænsku, frönsku, þýsku, ítölsku, hollensku, ensku, arabísku, norsku og malaísku.
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()
Áhrifamestu keðjurnar til prófunar eru: pt-BR -> pt-PT -> pt -> en (portúgalska), es-MX -> es-419 -> es -> en (spænska), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (hefðbundin kínverska). Þær ná yfir algengustu svæðisbundnu varaleitartilvikin.
8

Sjálfvirknivæddu þýðingar

Þegar i18n-uppsetningunni er lokið skaltu þýða staðfærsluskrárnar með gervigreind. Biddu gervigreindaraðstoðarmanninn í þróunarumhverfinu að þýða frumskrána eða notaðu skipanalínuverkfæri i18n Agent í CI/CD-vinnslurásinni.

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
Þýddu í áföngum. Þegar þú bætir nýjum lyklum við frumskrána skaltu aðeins þýða breytingarnar í stað þess að endurgera allar skrár. Þannig varðveitast þýðingar sem fólk hefur yfirfarið.

Sjálfvirknivæddu gæðaprófun þýðinga

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

Algengar gildrur

Þýðingar skila óunnum lyklum

Orsakir: load_path er ekki stillt eða vísar í ranga möppu, file_format samsvarar ekki skráarendingunum eða skráaheitin samsvara ekki staðfærslukóðunum. Gakktu úr skugga um að i18n.load_path innihaldi réttu möppuna og að skrárnar heiti rétt (t.d. en.json, de.json).

YAML-skrár hlaðast ekki inn

python-i18n krefst PyYAML til að styðja YAML en það er ekki sett upp sjálfgefið. Settu það upp með pip install python-i18n[YAML]. Án þess eru YAML-skrár hunsaðar án viðvörunar og þýðingar skila staðgenglum fyrir lykla sem vantar.

Uppfletting falinna lykla mistekst

python-i18n notar punktaritun fyrir falda lykla: i18n.t('nav.home'). Ef JSON-skráin notar flata lykla með punktum í heitinu (t.d. 'nav.home' sem einn lykil) túlkar safnið þá sem falda uppflettingu og mistekst. Notaðu raunverulega falda JSON-hluti í staðinn.

Staðfærslur blandast milli beiðna

i18n.set('locale', ...) er víðvær aðgerð. Í fjölþráða þjónum getur ein beiðni breytt staðfærslunni meðan önnur er í myndgerð. Notaðu nafngreinda viðfangið locale= í einstökum i18n.t()-köllum eða vistaðu staðfærsluna í þráðbundinni geymslu með millibúnaði.

Ráðlögð skráaskipan

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
└── ...

Þý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

Varaleit staðfærslna með python-i18n-locale-chain

Þegar þýðingarlykil vantar í svæðisbundna staðfærslu á borð við es-419 fer python-i18n beint í sjálfgefnu staðfærsluna í stað þess að athuga fyrst yfirstaðfærsluna 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

Í leiðarvísi okkar um varaleit staðfærslna er að finna allan listann yfir studda verkramma og 75 innbyggðar keðjur. Learn more →

Algengar spurningar