למתרגמים¶

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

שום דבר כאן אינו דורש מכם לקרוא Python. הכול כאן עוסק בדבר אחד: החלקים של ההודעה שנמצאים בסוגריים מסולסלים.

מהו מציין מקום¶

הודעה בקטלוג עשויה להכיל שמות בתוך סוגריים מסולסלים:

msgid "Hello {name}"
msgstr ""

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

התרגום שלכם נכנס ל-msgstr, והוא חייב לשמור על המשבצת הזו:

msgid "Hello {name}"
msgstr "こんにちは {name}"

מה מותר לכם לשנות ומה אסור¶

מותר לכם:

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

אסור לכם:

לתרגם את השם שבתוך הסוגריים. ‏{name} נשאר {name}, גם בשפה שאינה כותבת שום דבר אחר באותיות לטיניות.
להסיר את הסוגריים, או לכתוב את השם בלעדיהם.
להחליף את סוגריי ה-ASCII‏ { } בסוגריים ברוחב מלא ｛ ｝. שיטות קלט רבות מייצרות את הצורות ברוחב מלא; הן נראות כמעט זהות ואינן עובדות.
להוסיף פורמט, כגון {name!r} או {amount:.2f}. האופן שבו ערך מוצג נקבע בתוכנית, לא בקטלוג.
להמציא מציין מקום שאינו נמצא ב-msgid.

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

צורות ריבוי¶

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

שני כללים שמפילים אנשים:

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

כללי מצייני המקום שלמעלה חלים על כל צורה בנפרד.

רשומות fuzzy¶

רשומה המסומנת fuzzy היא ניחוש של מכונה: המפתח שינה את הודעת המקור, והכלים צימדו את הטקסט החדש עם התרגום הישן שלכם כדי שתהיה לכם נקודת פתיחה.

#, fuzzy
msgid "Welcome back, {name}"
msgstr "こんにちは {name}"

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

קריאת הודעת כשל¶

הכלים בודקים את מצייני המקום בעת הידור הקטלוג, וההודעה נכתבת עבורכם ולא עבור מתכנת. דיווח שאומר רק ש-{name} חסר הוא מבוי סתום כשאתם רואים את התווים האלה מול עיניכם, ולכן במקום שבו מציין מקום נראה קיים אך אינו כזה, ההודעה מסבירה מדוע. מול המקור Hello {name}, כל אחד מהמקרים הבאים מדווח תחת translation does not match the source placeholders:

מה שכתוב בתרגום שלכם	הסיבה שההודעה נותנת
`こんにちは｛name｝`	`{name}` is missing (the braces around it are not the ASCII `{` and `}`)
`こんにちは {{name}}`	`{name}` is missing (it is written `{{name}}`, which is how a literal brace is escaped)
`こんにちは name`	`{name}` is missing (the name appears, but not inside braces)
`こんにちは {名前}`	`{name}` is missing; `{名前}` is not in the source message

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

placeholder {<U+00A0>name} has a space inside the braces; write {name}

שם שאותיותיו מערבבות מערכות כתב — מקרה ההומוגליף, שבו а קירילית אינה ניתנת להבחנה מ-a לטינית — מוצג פעמיים, פעם אחת בצורה קריאה ופעם אחת בצורה מקודדת (escaped), שהיא הצורה היחידה שמבדילה בין השתיים:

translation does not match the source placeholders: {name} is missing;
{nаme} (n\u0430me) is not in the source message

אותה הבחנה חלה גם כאשר שם יווני או קירילי הכתוב כולו במערכת כתב אחת מתנגש עם שם מקור ב-ASCII, כולל מקרה האות הבודדת — a לטינית מול а קירילית.

אם נתקלתם באחד מאלה והתיקון אינו מובן מאליו, המהלך הבטוח הוא למחוק את מציין המקום שהקלדתם ולהעתיק את זה שנמצא ב-msgid.

מה שהבדיקות אינן יכולות לעשות¶

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

שני דברים עוזרים יותר מכל בדיקה:

קראו את הערת המתרגם. שורה שמתחילה ב-#. מעל ההודעה היא המפתח שמספר לכם היכן היא מופיעה ומה משמעותה.
שאלו על msgctxt. כשאותה מילה מופיעה פעמיים עם הקשרים שונים, זה מפני ששתיהן צריכות להיות מתורגמות אחרת — "Open" ככפתור ו-"Open" כמצב, למשל.