לדלג לתוכן

תרגמו הודעות שלמות
עם מחרוזות-t של Python

‏gettext-tstrings מחברת מחרוזות-t של Python 3.14+ לקטלוגי gettext סטנדרטיים ולכלי Babel. הערכים והפורמט נשארים בקוד היישום; המתרגמים עובדים עם הודעות שלמות ועם מצייני מקום פשוטים בצורת {name}:

import gettext

from gettext_tstrings import Translator

_ = Translator(gettext.translation("messages", localedir="locales"))
name = "Ada"
print(_(t"Hello {name}"))  # with a Japanese catalog: こんにちは Ada

הקטלוג מכיל את Hello {name}. תרגום רשאי להזיז את {name} או לחזור עליו. אם הוא משמיט את מציין המקום, משנה את שמו או מוסיף לו פורמט, אימות הקטלוגים מדווח על השגיאה. אם רשומה שגויה בכל זאת מגיעה לייצור, הספרייה רושמת אזהרה ומרנדרת את הודעת המקור במקום לקרוס.

התחילו את מדריך המבוא בן חמש הדקות השוו את החלופות

אלפא · Python 3.14+ · קטלוגי PO/MO סטנדרטיים · ללא תלויות צד-שלישי בזמן ריצה

האתר הזה מיישם את מה שהוא מתעד: כל מהדורת שפה — הניווט, התוויות ודוח הבנייה המודע לצורות ריבוי — מרונדרת מקטלוגי PO על ידי gettext-tstrings עצמה.

האם זה מתאים לכם?

מתאים כבר היום כאשר היישום שלכם רץ על Python 3.14 ומעלה; אתם כבר משתמשים ב-gettext וב-Babel, או רוצים לאמץ את תהליך ה-PO/MO שלהם; ואתם רוצים תחביר של מחרוזות-t עם מצייני מקום בעלי שם שנבדקים לפני הרינדור.

עדיין לא מתאים כאשר אתם זקוקים ל-Python 3.13 ומטה; אתם דורשים API יציב של Python — זו גרסת אלפא, והמפרט הוא החלק שכבר התייצב; או שכמעט כל הטקסט הניתן לתרגום אצלכם נמצא בשפת תבניות ולא בקוד Python.

כבר יש לכם קטלוגים? הם ימשיכו לעבוד. ‏_("Hello {name}").format(name=name) ו-tr(t"Hello {name}") מפיקים את אותו msgid, ולכן תרגומים קיימים שורדים את המעבר — מעבר מקיים מלווה את כל המהלך.

מה הקטלוג רשאי לומר

תרגום אינו יכול לשנות את מבנה ההודעה שהוא מתרגם. זו כל ההבטחה, וכל שאר האתר הזה נובע ממנה. תרגום רשאי לשנות את סדר {name} או לחזור עליו, ורשאי לשכתב כל מילה אחרת סביבו. אסור לו להשמיט את מציין המקום, להמציא חדש, להושיט דרכו יד אל האובייקטים שלכם או לצרף פורמט משלו.

הספרייה בודקת זאת בכניסה — כשהקטלוגים מהודרים — ושוב בזמן הרינדור, וזה ההבדל בין טעות שנמצאת בסקירה לבין טעות שנמצאת בידי משתמש.

חדשים ב-gettext? כל תהליך העבודה בארבעה משפטים

gettext הוא הדרך הסטנדרטית שבה תוכנה מתורגמת, ב-Python והרחק מעבר לה. הקוד שלכם מסמן הודעות הניתנות לתרגום; מחלץ אוסף אותן לקובץ תבנית (.pot); מתרגם — בדרך כלל לא מתכנת — ממלא קובץ קטלוג אחד (.po) לכל שפה, שמהודר לקובץ .mo בינארי שהיישום שלכם טוען בזמן ריצה. השם המקובל לפונקציית התרגום הוא _, כך ש-_(t"Hello {name}") נקרא כ"תרגם את ההודעה הזו". מדריך המבוא עובר את המסלול כולו — סימון, חילוץ, תרגום, הידור, הרצה — בכחמש דקות.

הבעיה שהיא פותרת

מחרוזת-f כבר עברה אינטרפולציה לפני שכל ספרייה רואה אותה — f"Hello {name}" כבר הפכה ל-"Hello Ada", ותרגום המקטעים שסביב ערך שובר את הדקדוק של רוב השפות. מחרוזת-t (PEP 750) שומרת את הטקסט הסטטי, הערכים המחושבים, ביטויי המקור, ההמרות ומפרטי הפורמט בנפרד — וזו בדיוק ההפרדה שקטלוג הודעות זקוק לה. מה זה משנה, בהשוואה ל-%(name)s, ל-.format() ולמחרוזות-$.

שום דבר ב-gettext או ב-Babel לא קובע כיצד מחרוזת-t הופכת להודעה. הספרייה הזו עושה את הבחירה, מתעדת אותה כמפרט מנוהל-גרסאות, ומספקת את חבילת התאימות לבדיקתה.

כללי העיצוב

  • לתרגם הודעות שלמות, לעולם לא מקטעי משפטים.
  • לקבל רק שמות משתנים פשוטים כמו {name}.
  • להשאיר את !r ואת :.2f בשליטת היישום, מחוץ לקטלוג.
  • לאפשר לתרגומים לסדר מחדש ולחזור על מצייני מקום מוכרים, ובה בעת למנוע מהם להושיט יד אל תכונות או להוסיף פורמט.
  • לעשות שימוש חוזר בקובצי POT,‏ PO ו-MO רגילים, ובכלים שכבר קוראים אותם.

והרשימה המשלימה של מה שהיא משאירה בכוונה לאחרים: היא אינה מתאימה לשפה מספרים, מטבעות או תאריכים — עצבו אותם תחילה בעזרת Babel; היא אינה מבריחה תווים בפלט המרונדר עבור HTML, מעטפת או מסוף; והיא אינה יכולה לשפוט אם תרגום נכון, אלא רק אם מצייני המקום שלו שלמים.

התקנה

python -m pip install gettext-tstrings

Python 3.14 ומעלה. לרינדור אין תלויות — הוא משתמש ב-gettext מהספרייה הסטנדרטית ותו לא.

החילוץ ואימות הקטלוגים רצים דרך Babel, לכן התקינו את התוספת הזו בכל מקום שבו pybabel רץ — בדרך כלל סביבת פיתוח או CI ולא תמונת ייצור:

python -m pip install "gettext-tstrings[babel]"

לאן להמשיך

מתחילים כאן — בלי להניח שום ניסיון ב-gettext:

  • מדריך המבוא — מתיקייה ריקה לתרגום יפני פועל בחמישה שלבים, כל פקודה מוצגת עם הפלט שלה.
  • למה מחרוזות-t — אותה הודעה כתובה בארבע דרכים, ומה %(name)s,‏ .format() ומחרוזות-$ מוסרות כל אחת לקטלוג.

שימוש בפועל — חומרי העזר המעשיים:

  • מדריך — ה-API של זמן הריצה: באיזו נקודת כניסה להשתמש, צורות ריבוי, שפה לכל בקשה, מחרוזות דחויות, ומה קורה כשקטלוג שגוי.
  • חילוץ — חומר העזר של pybabel: תצורה, שמות פונקציות מותאמים, וכיצד כלים קיימים מאמתים את הקטלוגים האלה בחינם.
  • בסביבת ייצור — הלולאה כפי שצוות מריץ אותה: מחזור העדכון, רשומות fuzzy, שערי CI, פלטפורמות תרגום והמשלוח עצמו.
  • מעבר מקיים — אימוץ הספרייה בפרויקט שכבר יש בו קטלוגים, אתר קריאה אחד בכל פעם.
  • למתרגמים — עמוד אחד שאפשר למסור למי שעורך את קובצי ה-.po.

העמקה — מההיסטוריה ועד המימוש:

  • רקע — למה הספרייה הזו קיימת: שלושים שנות gettext, שני מסמכי PEP, והדיון בספרייה הסטנדרטית שנסגר בלי תשובה.
  • מלכודות נפוצות — מה באמת נשבר כשתרגמנו את האתר הזה לשלושים וחמש שפות, ואיזה חצי מזה כלי מסוגל לתפוס.
  • איך זה עובד — מאובייקט התבנית של PEP 750 ועד המחרוזת המרונדרת, והמטמונים שהופכים את הבדיקה לזולה.

עיון מהיר — החוזים:

  • API — כל מה שהחבילה מייצאת, בעמוד אחד.
  • מפרט — מוסכמת t-string ↔ msgid כחוזה יציב ומנוהל-גרסאות, עם חבילת תאימות קריאה למכונה.

סטטוס
גרסת החבילה 0.1.0a8
יציבות ה-API אלפא — ה-API של Python עדיין עשוי להשתנות
מפרט ‏v1, עם חבילת בדיקות תאימות
Python ‏3.14 ומעלה; נבדק על 3.14,‏ 3.14t (free-threaded) ו-3.15
Babel ‏2.18 ומעלה, ורק היכן ש-pybabel רץ
תלויות זמן ריצה אין — ‏gettext של הספרייה הסטנדרטית
פורמט קטלוגים קובצי POT,‏ PO ו-MO רגילים
שינויים CHANGELOG

גרסת אלפא. החוזה קטן בכוונה, והמפרט הוא החלק היציב שבו; ה-API של Python עדיין עשוי לזוז. לפני שחרור יציב נדרשים מקרי בוחן רחבים יותר של שפות, מעקב ביצועים מתמשך, סקירת API מאנשים שמשתמשים ב-gettext וב-Babel ברצינות, ובדיקות תאימות מול כל גרסאות Python ו-Babel הנתמכות.

דיווחי תקלות ובקשות משיכה יתקבלו בברכה — אלפא היא בדיוק השלב שבו עוד שווה להתווכח על הממשק.

הצטרפו לקהילה