כיצד לתרגם שדות מותאמים אישית של ACF ב־WordPress – קבוצות שדות, שדות Repeater, עמודי אפשרויות

לפני שתתחיל

התקן והפעל את התוספים הבאים:

• Advanced Custom Fields או ACF Pro.
• WPML ו־WPML תרגום מחרוזות.
• ACFML (התוסף הנלווה שמכוסה בעמוד זה).

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

בחר אפשרות תרגום עבור כל קבוצת שדות

קבוצות שדות של ACF אינן מתנהגות כולן באותה צורה בעת תרגום. ACFML מציע שלוש אפשרויות תרגום עבור כל קבוצת שדות. כדי לבחור אחת:

1. עבור אל ACF ← Field Groups וערוך את קבוצת השדות.
2. במקטע Multilingual Setup, תחת Select a translation option for this field group, לחץ על Choose באפשרות הרצויה.
3. שמור את קבוצת השדות.

ACFML מסמן את האפשרות שהוא מציע לאתר שלך בתור recommended for this site. כדי לבחור אפשרות אחרת מאוחר יותר, לחץ על Change option. גרסאות ישנות יותר של ACFML קוראות לשתי האפשרויות הראשונות Same fields across languages ו־Different fields across languages.

אותו תוכן בכל שפה, מתורגם

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

לכל שפה יש תוכן משלה

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

Expert

השתמש באפשרות זו כאשר אתה זקוק לשילוב: שדות מסוימים מתורגמים, חלקם נשארים זהים, וחלקם מועתקים פעם אחת ולאחר מכן משתנים בכל שפה. בחר ב־Expert והגדר את העדפת התרגום של כל שדה באופן ידני. בדוגמה של אירועים, הכותרת והתיאור משתמשים ב־Translate, והמחיר, התאריך והכתובת משתמשים ב־Copy. ACFML אינו ממליץ על אפשרות זו עבור קבוצות שדות חדשות. קבוצת שדות המוגדרת ב־PHP או ב־Local JSON יכולה להיות ללא אפשרות תרגום. במקרה כזה, היא משתמשת ב־Expert רק כאשר קבוצת השדות הייתה קיימת לפני שהאתר שלך עודכן ל־WPML 5.2.

העדפות תרגום עבור כל סוג שדה של ACF

לכל שדה שמאחסן ערך יש אחת מארבע העדפות תרגום:

• Translate. המבקרים רואים את הערך בשפה שלהם. WPML ממלא אותו בתרגום. אתה עורך אותו בעורך התרגום.
• Copy. מבקרים בכל שפה רואים בדיוק את מה שהמקור מציג. השדה נעול בשפות האחרות.
• Copy once. הערך מתחיל כעותק של המקור. לאחר מכן, אתה עורך אותו בכל שפה באופן ידני. אם תרוקן את השדה בתרגום, הוא יישאר ריק. WPML לא יעתיק אליו שוב את הערך המקורי.
• Don’t translate. התרגומים מתחילים ללא ערך זה. תוכל למלא אותו בכל שפה באופן ידני.

כאשר אתה בוחר באפשרות Same content in every language, translated או Each language has its own content, ACFML מעניק לכל שדה את ההעדפה המומלצת עבור סוג השדה שלו. הטבלאות להלן מציגות את ההעדפות המומלצות הללו. כדי להגדיר העדפה שונה עבור שדה אחד, השתמש ב־Expert. כדי לשנות את ההעדפה המומלצת של סוג שדה באתר כולו, השתמש בפילטר acfml_field_group_mode_field_translation_preference (ראה Developer Hooks for Edge Cases להלן).

שדות מסוג Tab, Accordion, Message ו־Separator אינם מאחסנים ערך, ולכן אין להם העדפת תרגום. סוג שדה שאינו מופיע בטבלאות, לדוגמה סוג שדה מתוסף אחר, מקבל Copy בשתי אפשרויות התרגום.

שדות מסוג Repeater, Flexible Content, Group ו־Clone

שדות אלו מכילים שדות אחרים. ההעדפה המומלצת של שדה המעטפת היא Copy או Copy once. ACFML אינו מציע Translate עבור שדה המעטפת עצמו. לכל תת־שדה יש העדפת תרגום משלו.

באפשרות Same content in every language, translated, השורות של שדות Repeater ו־Flexible Content נשארות באותו סדר כמו בשפת ברירת המחדל. באפשרות Expert, או כאשר פוסט משתמש בקבוצות שדות עם אפשרויות שונות, עורך הפוסטים מציג תיבת ACFML Synchronise translations. היא מופיעה בפוסט המקורי כאשר לפוסט יש תרגומים ושדה Repeater או Flexible Content. בחר באפשרות Keep repeater and flexible sub-fields in the same order as the default language כדי לשמור על יישור השורות בכל השפות.

שדות בסיסיים

שדות תוכן

שדות בחירה

שדות jQuery

שדות פריסה

שדות מקושרים

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

שדות URL וקישור

החל מ־ACFML 5.0, שדות URL וקישור משתמשים בהעדפה תרגום כברירת מחדל.

קשרים דו־כיווניים

החל מ־ACF 6.2, שדות קשר, אובייקט פוסט, טקסונומיה ומשתמש יכולים להיות דו־כיווניים. כאשר אתה בוחר יעד בשדה, ACF מוסיף את הפוסט שלך לשדה המותאם של היעד. לדוגמה, הספר Dune מגדיר את שדה ה־Author שלו כ־Frank Herbert. לאחר מכן, ACF מוסיף את Dune לשדה ה־Books של Frank Herbert.

ACFML שומר על הצמד בכל שפה:

• כאשר WPML מעתיק את השדה לתרגום, ACFML מפנה את השדה אל היעד באותה שפה. לאחר מכן, ACFML מוסיף את התרגום לשדה המצומד של אותו יעד. Dune בספרדית מציג את Frank Herbert בספרדית, ו־Frank Herbert בספרדית מציג את Dune בספרדית.
• כאשר השדה משתמש בהגדרה העתקה ואתה משנה את היעד בפוסט המקורי, WPML מעדכן את התרגום. ACFML מוסיף את התרגום ליעד החדש באותה שפה ומסיר אותו מהיעד הישן.
• ACFML משנה רק את היעדים בשפת התרגום. הפוסטים בשפה המקורית שומרים על הצמד שלהם.
• כאשר ליעד עדיין אין תרגום, התרגום מפנה ליעד המקורי, ו־ACFML אינו משנה את היעד המקורי. כאשר תתרגם את היעד מאוחר יותר, ACFML יפנה את השדה לתרגום החדש ויוסיף את הפוסט לשדה המצומד שלו. השדה מציג את היעד פעם אחת.
• למשתמשים אין תרגומים, לכן ACFML אינו מוסיף תרגומים לשדה המצומד של משתמש. שדה זה שומר את הפוסט המקורי. בשפה אחרת, ACFML מציג את התרגום של פוסט זה, אלא אם השדה משתמש בהגדרה העתקה.

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

תרגום בלוקים של ACF

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

• הבלוק משתמש באפשרות התרגום ובהעדפות השדה של קבוצת השדות שכלל המיקום שלה הוא בלוק זה.
• ACFML שולח רק את השדות שמשתמשים בהגדרה תרגום. שדות שמשתמשים בהגדרות העתקה, העתק פעם אחת או אל תתרגם שומרים את הערך מהבלוק המקורי.
• שדות מסוג Repeater ו־Flexible Content בתוך בלוק מתורגמים גם הם, גם כאשר הם מקוננים. כל תת-שדה משתמש בהעדפת התרגום שלו.
• בלוק עם "usePostMeta": true בסעיף acf של block.json שלו שומר את הערכים שלו בתור שדות מותאמים אישית של הפוסט, ולא בבלוק. ערכים אלו מתורגמים כמו כל שדה מותאם אישית אחר של הפוסט, עם אפשרות התרגום והעדפות השדה של קבוצת השדות.
• כאשר אתה משנה העדפת תרגום בקבוצת שדות שבה אתה משתמש עבור בלוקים, WPML שואל אם ברצונך לעדכן את התרגומים הקיימים. אם תאשר, WPML יסמן את התרגומים של פוסטים אלו ככאלה שדורשים עדכון. שלח אותם לתרגום שוב כדי להחיל את השינוי. שינוי להגדרה אל תתרגם אינו מסמן אותם.

שדות שהוצהרו ב־block.json

החל מ־ACF 6.8.1, בלוק יכול להצהיר על השדות שלו בקובץ block.json שלו, תחת acf.fields. ACF יוצר קבוצת שדות עבור שדות אלו, ולא ניתן לערוך את קבוצת השדות הזו באזור הניהול. ACFML מעניק לה את האפשרות אותו תוכן בכל שפה, מתורגם ואת ההעדפה המומלצת לכל סוג שדה, כמו קבוצת שדות שנרשמה ב־PHP.

כדי להשתמש באפשרות אחרת עבור הקבוצה כולה, הוסף את acfml_field_group_mode לסעיף acf של block.json, או ל־acf_register_block_type(). הערכים המקובלים הם translation (אותו תוכן בכל שפה, מתורגם), localization (לכל שפה יש תוכן משלה) ו־advanced (מומחה). ACFML מתעלם מכל ערך אחר.

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

כדי להגדיר את ההעדפה של שדה אחד, הוסף את wpml_cf_preferences לשדה זה. ACFML שומר על העדפה זו בכל אפשרות. עם מומחה, רק השדות שמצהירים על wpml_cf_preferences מקבלים העדפה.

כאשר block.json אינו מציין אפשרות, ACFML מאחסן את האפשרות שהוא מעניק לקבוצה בפעם הראשונה שהוא רואה את הקבוצה, ושומר אותה לאחר מכן. באתרים שהשתמשו בבלוקים אלו עם גרסת ACFML ישנה יותר, האפשרות המאוחסנת היא מומחה.

הגדרת העדפות עבור שדות שנרשמו ב־PHP או ב־JSON

קבוצות שדות של ACF שנרשמו ב־PHP (עם acf_add_local_field_group()) או דרך תכונת Local JSON של ACF אינן מקבלות את העדפות התרגום ממסכי אזור הניהול, מכיוון שאזור הניהול אינו מנהל אותן. הגדר את ההעדפות באותו מקום שבו אתה רושם את השדות.

כדי להגדיר את אפשרות התרגום של קבוצת השדות, הוסף את המפתח acfml_field_group_mode להגדרה, עם translation, localization או advanced (Expert). כאשר ההגדרה אינה קובעת אפשרות תרגום, ACFML מעניק לקבוצת השדות את האפשרות Same content in every language, translated בפעם הראשונה שהוא מזהה את הקבוצה. ACFML שומר אפשרות זו ומשאיר אותה לאחר מכן. קבוצות שדות שקיימות לפני שהאתר שלך מתעדכן ל־WPML 5.2 שומרות על Expert.

עבור כל שדה בהגדרת קבוצת השדות, הוסף מפתח wpml_cf_preferences. הערך הוא מספר שלם שממופה לארבע העדפות התרגום: 0 עבור אל תתרגם (WPML מתעלם מהשדה), 1 עבור העתקה (הערך נשאר מסונכרן בכל השפות), 2 עבור תרגום (הערך עובר תרגום), ו־3 עבור העתק פעם אחת (הערך מועתק לתרגומים חדשים, ולאחר מכן ניתן לערוך כל שפה באופן עצמאי).

דוגמה מינימלית:

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

לאחר שתגדיר את השדות בקוד, סנכרן את ההעדפות לתוך WPML כדי שאזור הניהול יזהה אותן:

1. עבור אל ACF ← כלים.
2. גלול אל Translate ACF Local JSON and PHP-Registered Fields.
3. תחת Sync Translation Preferences for Local Fields, בחר Sync once now ולחץ על החל.

WPML קורא את ההעדפות מהגדרות השדות שלך ושומר אותן. Sync once now פועל פעם אחת. אם אתה משנה את ההגדרות לעיתים קרובות, בחר במקום זאת באפשרות Sync on every request (may affect performance). אפשרות זו מפעילה את הסנכרון בכל בקשה של אזור הניהול.

אם אתה משתמש בתכונת Local JSON של ACF כדי לשתף קבוצות שדות בין אתרים, ACFML כותב את העדפות התרגום לתוך קובצי ה־JSON באופן אוטומטי. ייצא קובץ JSON מאתר אחד, ייבא אותו לאתר אחר, ואתר היעד יקלוט את ההעדפות ברגע ש־ACFML יהיה פעיל בשני הקצוות.

קבוצות שדות ש־ACF יוצר באמצעות פקודת ה־WP-CLI wp acf json import, או דרך ה־Abilities API שלו עבור כלי AI, נשמרות במסד הנתונים. ACFML מעניק להן את האפשרות Same content in every language, translated ואת ההעדפה המומלצת עבור כל סוג שדה. כאשר ל־JSON המיובא יש כבר מפתח acfml_field_group_mode, ACFML משתמש באפשרות זו במקום זאת.

קבוצות שדות בקובצי Local JSON

ACF טוען את קבוצות השדות של התיקייה acf-json מוקדם מאוד בכל בקשה. החל מ־WPML 5.2, ACFML קורא את קבוצות השדות הללו באותו הזמן. לכן, כאשר אתה מסנכרן את העדפות התרגום, הסנכרון מכסה גם קבוצות שדות מ־JSON. לאחר מכן, WPML משתמש בהעדפות שבקובצי ה־JSON.

בקובץ ה־JSON, הוסף wpml_cf_preferences לכל שדה, עם אותם ערכים כמו ב־PHP. מפתח זה מגדיר את ההעדפה של כל שדה, ללא קשר לאפשרות התרגום של קבוצת השדות. הדוגמה משתמשת ב־Expert:

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

כדי לשלוח את ההעדפות ואת התוויות של קבוצות שדות מ־JSON אל WPML:

1. עבור אל ACF ← כלים.
2. גלול אל Translate ACF Local JSON and PHP-Registered Fields.
3. תחת Sync Translation Preferences for Local Fields, בחר Sync once now או Sync on every request (may affect performance).
4. תחת Register Labels for Translation, בחר Register labels now.
5. לחץ על החל.

כדי לבדוק את התוצאה, עבור אל WPML ← הגדרות ומצא את השדות תחת תרגום שדות מותאמים אישית. כל שדה מציג את ההעדפה מקובץ ה־JSON. ACFML גם רושם את התוויות של קבוצות השדות, סוגי התוכן המותאמים אישית, הטקסונומיות ועמודי האפשרויות שקיימים רק בקוד: בתיקייה acf-json או כאלה שנרשמו ב־PHP. תרגם אותם כמו את התוויות של כל קבוצת שדות אחרת (ראה תרגום תוויות של שדות ACF להלן).

תרגום תוויות של שדות ACF

תוויות השדות של ACF הן השמות שמזהים כל שדה מותאם אישית בעורך WordPress ובצד הלקוח (לדוגמה, Phone number, Address). הן מתורגמות בנפרד מערכי השדות, והן נמצאות ב־WPML תרגום מחרוזות, ולא במשימת התרגום של הפוסט.

כדי לשלוח תוויות שדות לתרגום:

1. פתח את WPML ← תרגומים ← לוח בקרה.
2. הרחב את המקטע ACF Field Group.
3. בחר את הפריט Field Group Labels עבור קבוצת השדות שברצונך לתרגם.
4. בחר שיטת תרגום (PTC, המתרגם שלך, או אתרגם בעצמי) ושלח.

התוויות המתורגמות מופיעות בצד הלקוח באופן אוטומטי ברגע שהתרגום מושלם.

עצירת תרגום של תוויות שדות

כברירת מחדל, משימת התרגום של פוסט אינה כוללת את תוויות השדות. אתה מתרגם אותן רק כאשר אתה שולח את הפריט Field Group Labels מלוח הבקרה. אם אינך שולח אותו, ACF מציג את התוויות המקוריות. כדי להציג את התוויות המקוריות גם כאשר קיימים תרגומים, השתמש בפילטר acfml_should_translate_acf_entity והחזר false עבור השדות או קבוצות השדות שברצונך לדלג עליהם. תוכל למצוא דוגמה במדריך ההוקים והקבועים של ACFML.

תרגום אפשרויות שדה של ACF

שדות בחירה (Select, Checkbox, Radio Button, Button Group) נושאים תוויות אפשרויות משלהם (לדוגמה, Small / Medium / Large). גם אלו נמצאים לצד תוויות השדות ולא בתוך תרגום הפוסט. שלח אותם באותה דרך:

1. פתח את WPML → תרגומים → לוח בקרה.
2. הרחב את המקטע ACF Field Group.
3. בחר את קבוצת השדות שאת ערכי הבחירה שלה ברצונך לתרגם.
4. בחר שיטת תרגום ושלח.

תרגום דפי אפשרויות של ACF

דפי אפשרויות של ACF (מסכי הגדרות גלובליים כמו Contact details, Header settings, Footer links) מתורגמים כסוג אובייקט משלהם, בנפרד מפוסטים:

1. פתח את WPML → תרגומים → לוח בקרה.
2. הרחב את המקטע ACF Options.
3. בחר את דף האפשרויות שברצונך לתרגם.
4. בחר שיטת תרגום ושלח.

הערכים של דף האפשרויות בכל שפה מופיעים אוטומטית כאשר ACF קורא את האפשרות בהקשר של אותה שפה.

אפשרות התרגום של קבוצת השדות בדף האפשרויות קובעת מה קורה לכל שדה:

• שדות שמשתמשים בתרגום נכנסים לפריט ACF Options שאתה שולח מלוח בקרת תרגום. כאשר התרגום מושלם, ACFML כותב את הערכים לדף האפשרויות של אותה שפה. שדות מסוג Repeater ו־Flexible Content מקבלים את אותן שורות כמו המקור.
• שדות שמשתמשים בהעתקה מקבלים את הערך של המקור בכל שפה. כאשר אתה שומר את המקור, ACFML מעדכן את השפות האחרות.
• שדות שמשתמשים בהעתק פעם אחת מתחילים כעותק של המקור. לאחר מכן, אתה עורך אותם בדף האפשרויות של כל שפה.

השתמש ב־Each language has its own content כאשר האפשרויות שונות בהתאם לשפה. לדוגמה, דף אפשרויות המציג שלושה סוכני מכירות באנגלית ושניים בספרדית. כדי לבחור באפשרות זו, ערוך את קבוצת השדות, כמו בכל קבוצת שדות אחרת.

כדי לשנות תרגום שהסתיים, עבור אל WPML → תרגומים → עבודות תרגום ולחץ על עריכה במשימת ACF Options. תוכל גם לערוך את הערכים המתורגמים בWPML → תרגום מחרוזות. כאשר תשמור שם תרגום, ACFML יכתוב אותו לדף האפשרויות של אותה שפה.

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

בקוד, get_field( 'my_field', 'option' ) מחזיר את הערך של השפה הנוכחית. לאחר do_action( 'wpml_switch_language', 'fr' ), הוא מחזיר את הערך בצרפתית. זה עובד גם עבור דפי אפשרויות עם post_id מותאם אישית.

בעיות נפוצות

• תוויות השדות נראות לא מתורגמות. הן נמצאות בתרגום מחרוזות, ולא בתרגום הפוסט. שלח את הפריט Field Group Labels של קבוצת השדות מלוח הבקרה (ראה Translate ACF field labels לעיל).
• ערכי הבחירה נראים לא מתורגמים. אותו עיקרון. שלח את קבוצת השדות מהמקטע ACF Field Group של לוח הבקרה כדי שערכי האפשרויות ייכללו.
• שורות Repeater יוצאות מסנכרון. קבוצת השדות כנראה משתמשת ב־Expert. ערוך את הפוסט המקורי, בחר ב־Keep repeater and flexible sub-fields in the same order as the default language בתיבת ACFML Synchronise translations, ועדכן את הפוסט. או שנה את קבוצת השדות ל־Same content in every language, translated.
• לוגיקה מותנית מתנהגת באופן בלתי צפוי. כאשר השדה המבקר מוגדר להעתקה (Copy) או לאל תתרגם (Don’t translate), ההתנהגות המותנית עוקבת אחר הערך של שפת המקור בכל התרגומים. הגדר את השדה המבקר לתרגום (Translate) אם הערך שלו אמור להיות שונה בכל שפה.
• שדות מקומיים (הרשומים דרך PHP) מתעלמים מהעדפות התרגום שהוגדרו באזור הניהול. הגדר את המפתח wpml_cf_preferences בהגדרת קבוצת השדות עצמה וסנכרן מתוך ACF → כלים. התהליך מוסבר בסעיף Setting Preferences for Fields Registered in PHP or JSON לעיל.

הוקים למפתחים עבור מקרי קצה

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