מפרט¶

אפשר להשתמש בספרייה הזו בלי לקרוא את העמוד הזה — מדריך המבוא והמדריך מכסים את השימוש היומיומי. העמוד הזה מיועד למחברי כלים: המוסכמה שהספרייה מממשת כתובה כאן כחוזה קטן ויציב, כך שמימוש אחר — מחלץ, IDE, בודק טיפוסים או pygettext עתידי — יוכל לכוון אליו ולפעול איתו בתאימות מלאה. לאותם כללים, מוסברים עם נימוקיהם ועם האופן שבו מימוש הייחוס מבצע אותם, קראו קודם את איך זה עובד.

קראו את מפרט v1

הכללים במסך אחד¶

msgid הוא השרשור, בסדר המקור, של המקטעים הליטרליים ושל אסימון {name} אחד לכל אינטרפולציה. סוגריים מסולסלים ליטרליים עוברים escape (התו { הופך ל-{{). שם חייב להיות שם מציין מקום פשוט — str.isidentifier() מחזירה עליו true והוא אינו מילת מפתח של Python. המרות ומפרטי פורמט אינם חלק מה-msgid; הם נשארים בשליטת האפליקציה.

t-string	msgid
`t"Hello {name}"`	`Hello {name}`
`t"Total: {amount:,.2f}"`	`Total: {amount}`
`t"Config {{raw}} is {value}"`	`Config {{raw}} is {value}`
`t"Hello {user.name}"`	נדחית — לא שם פשוט

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

בצורות ריבוי, המותר הוא איחוד השמות של הענפים והנדרש הוא החיתוך שלהם — כך ש-t"One file" מול t"{n} files" משאיר את n זמין למתרגם של כל אחת מהצורות אך נדרש באף אחת מהן, וכללי הריבוי של שפת היעד יכולים להיות שונים מאלה של שפת המקור.

msgid ריק לעולם אינו נשלח לחיפוש, כי gettext שומר אותו לכותרת המטא-נתונים של הקטלוג.

תאימות¶

conformance/v1.json הוא אותו מסמך בצורה קריאת-מכונה: מקרים הממפים את המבנה הסטטי של מחרוזת-t אל msgid, ואת הצירוף של msgid עם תבנית קטלוג אל מחרוזת מרונדרת או אל דחייה.

מימוש תואם את spec v1 כאשר הוא משחזר כל מקרה ומקרה. המקרים נוקבים רק במה שהמפרט מגדיר — msgid-ים נגזרים, תבניות מתקבלות ותבניות נדחות, פלט מרונדר — ולעולם לא בהודעת שגיאה או בטיפוס של חריגה, ולכן מימוש בשפה אחרת יכול להריץ אותם ללא שינוי.

אינטרפולציות מתוארות באופן מבני, לעולם לא כקוד מקור של Python:

{
  "spec": "2.2",
  "name": "format spec stays out of the msgid",
  "source": [
    "Total: ",
    {"expression": "amount", "value": 1234.5, "format_spec": ",.2f"}
  ],
  "msgid": "Total: {amount}"
}

השדה "spec" אינו גרסת מפרט — כל מקרה ב-v1.json שייך ל-spec v1. הוא מציין את הסעיף של SPEC.md שהמקרה בודק, כך ש-"2.2" נקרא כ-§2.2, הכלל לגזירת אסימון של מציין מקום.

מימוש הייחוס מריץ את חבילת התאימות כחלק ממערך הבדיקות של עצמו, כך שהפרוזה והקוד אינם יכולים להתרחק זה מזה בשקט.

ניהול גרסאות¶

זהו spec v1. שינוי שאינו תואם לאחור בגזירת msgid או באימות תרגומים מעלה את מספר הגרסה ומצרף קובץ conformance/vN.json חדש לצד הקיים. הבהרות תוספתיות שאינן משנות לא msgid-ים נגזרים ולא תבניות מתקבלות — אינן מעלות אותו.