Wtyczka WPML Advanced Custom Fields (ACF) Multilingual - 2.2.4

Advanced Custom Fields Multilingual (ACFML) to dodatek-spinacz od OnTheGoSystems, który łączy WPML z wtyczką Advanced Custom Fields i otwiera pola niestandardowe WordPress na tłumaczenie. Działa wyłącznie w parze z WPML i ACF, z myślą o deweloperach i agencjach budujących wielojęzyczne strony oparte na polach ACF.

Jak działa Advanced Custom Fields Multilingual

Advanced Custom Fields Multilingual to warstwa pośrednicząca między WPML a wtyczką Advanced Custom Fields – podpowiada WPML, jak traktować dane zapisane w polach ACF. Bez ACFML WPML nie radzi sobie z polami niestandardowymi: albo nie pojawiają się one do tłumaczenia, albo dublują się między wersjami językowymi. Spinacz wymaga jednoczesnej obecności WPML core, WPML String Translation oraz ACF lub ACF Pro.

Dlaczego ACFML nie jest samodzielną wtyczką

ACFML pełni rolę glue plugin. Sam z siebie nie tłumaczy żadnej treści – WPML zarządza wersjami językowymi wpisów i stron, ACF tworzy pola niestandardowe, a ACFML dokłada brakującą wiedzę o tym, jak obie wtyczki mają współpracować przy danych z pól.

Bez tego pośrednika WPML nie wie, czy konkretne pole tłumaczyć, kopiować, czy ignorować, ani jak obsłużyć pola zagnieżdżone. Typowy objaw braku ACFML? Zdublowane opisy w wersji przetłumaczonej oraz pola, które w ogóle nie wpadają do Translation Dashboard.

Co musi być zainstalowane, żeby ACFML zadziałał

Spinacz potrzebuje całego stacku wtyczek działających razem. Wystarczy, że zabraknie jednej pozycji, a pola ACF nie staną się tłumaczalne.

• ACF lub ACF Pro – wtyczka bazowa dostarczająca pola niestandardowe.
• WPML core – środowisko zarządzające wersjami językowymi witryny.
• WPML String Translation – komponent obsługujący tłumaczenie ciągów tekstowych.
• ACFML – sam spinacz łączący WPML z ACF.

Gdzie konfiguruje się tłumaczenie — panel Multilingual Setup

Sterowanie tłumaczeniem siedzi bezpośrednio na ekranie edycji grupy pól (ACF → Field Groups). Na górze strony pojawia się panel Multilingual Setup, w którym deweloper wybiera tryb tłumaczenia bez skakania do osobnych ustawień WPML.

Częsta pułapka konfiguracyjna to próba zarządzania polami z poziomu WPML → Settings – a właściwe miejsce to ekran grupy pól ACF. Od ACFML 2.0 dodatek prowadzi przez wybór opcji jednokrokowym kreatorem konfiguracji.

Funkcje i możliwości Advanced Custom Fields Multilingual

Advanced Custom Fields Multilingual tłumaczy każdy typ pola dostępny w ACF i ACF Pro – wartości pól, etykiety, opcje wyboru (radio, select, checkbox), Options Pages oraz bloki ACF. Sterowanie odbywa się z ekranu edycji grupy pól, a wartości można tłumaczyć ręcznie albo przez automatyczne tłumaczenie WPML z silnikami DeepL, Google i Microsoft.

Tłumaczenie wszystkich typów pól ACF i ACF Pro

ACF udostępnia ponad 30 typów pól. ACFML obejmuje je wszystkie – od prostych pól po złożone struktury danych charakterystyczne dla ACF Pro.

• Pola tekstowe i podstawowe – tekst, obszary tekstowe i pola liczbowe tłumaczone domyślnie jako wartości przekazywane do edytora.
• Repeater i Flexible Content – układy powtarzalne i elastyczne, w których tłumaczeniu podlegają pod-pola wewnątrz każdego wiersza lub layoutu.
• Group i Clone – pola grupujące i klonujące inne pola, obsługiwane razem z ich zawartością.
• Pola relacyjne – Link, Post Object, Page Link, Relationship, Taxonomy i User, domyślnie kopiowane między językami.

Etykiety i opcje wyboru pól

Etykiety pól (Field Labels) identyfikują pola w edytorze, a często lądują też na froncie – choćby w formularzach. ACFML tłumaczy je przez WPML → Translation Dashboard w sekcji ACF Field Group, a od wersji 2.0 odbywa się to podejściem no-code, bez ingerencji w kod.

Osobno tłumaczą się opcje wyboru pól (Field Choices) – wartości pól radio, select i checkbox. Dzięki temu zlokalizowane etykiety opcji pojawiają się w formularzach i polach wyboru w każdym języku witryny.

Options Pages i bloki ACF

Globalne strony ustawień ACF (Options Pages) przechowują dane kontaktowe, logo czy teksty stopki – tłumaczy się je przez Translation Dashboard w sekcji ACF Options. Od ACFML 2.2.0 Options Pages wysyła się do tłumaczenia bezpośrednio z poziomu Translation Dashboard.

Bloki ACF zbudowane w Gutenbergu tłumaczą się tymi samymi metodami co pozostałe pola – w trybie wspólnych lub odmiennych pól per język.

Pola definiowane kodem (Local Fields)

Pola rejestrowane przez PHP lub JSON, a nie przez interfejs graficzny, też są tłumaczalne. Preferencję tłumaczenia ustawia się programowo parametrem wpml_cf_preferences w definicji pola.

Od ACFML 2.2.0 synchronizacja treści lokalnych jest prostsza – wystarczy jednorazowe wywołanie ACF → Tools → „Sync once now”, a pola lokalne zyskują status pełnoprawnych pól ACF.

Tryby tłumaczenia pól w ACFML

Advanced Custom Fields Multilingual udostępnia trzy tryby tłumaczenia grupy pól: „Same fields across languages” (te same pola, przetłumaczone wartości), „Different fields across languages” (odmienna treść per język) oraz Expert Mode, który pozwala ustawić preferencję osobno dla każdego pola. Do wyboru są cztery preferencje: Translate, Copy, Copy Once i Do Nothing.

Same fields across languages

To typowe ustawienie większości stron opartych na ACF. Tryb zachowuje strukturę pól między językami i tłumaczy ich wartości – treść wprowadza się raz w języku domyślnym, a potem wysyła do tłumaczenia.

Przykład? Strona zespołu. Ci sami ludzie, te same pola, tylko przetłumaczone wartości tekstowe. Pola layoutowe i relacyjne są w tym trybie domyślnie kopiowane, a tłumaczeniu podlega ich zawartość.

Different fields across languages

Tryb pokazuje inne wartości lub inny układ pól w każdym języku. Sprawdza się tam, gdzie poszczególne wersje językowe mają prezentować zlokalizowaną, odmienną treść – na przykład gdy firma organizuje różne wydarzenia dla różnych odbiorców językowych.

Tłumaczenie biegnie przez natywny edytor WordPress, gdzie wersję językową dodaje się ikoną „plus”.

Expert Mode — kontrola per pole

Expert Mode daje ręczną kontrolę nad preferencją tłumaczenia każdego pojedynczego pola. Pozwala mieszać podejścia w jednej grupie: tytuł i opis na Translate, a cena, data i adres na Copy.

Cztery preferencje określają zachowanie pola. Translate wysyła pole do tłumaczenia, Copy kopiuje wartość przy każdej zmianie, Copy Once kopiuje ją jednorazowo i pozwala dalej edytować niezależnie, a Do Nothing pomija pole.

Przykładowe zastosowania Advanced Custom Fields Multilingual

Advanced Custom Fields Multilingual sprawdza się tam, gdzie ważna treść siedzi w polach ACF – na stronach zespołu, w sekcjach landing page budowanych Repeaterem, na kartach produktów z mieszanymi danymi czy w globalnych Options Pages. Expert Mode rozdziela dane wspólne dla języków, takie jak cena, SKU czy data, od treści wymagającej tłumaczenia, jak tytuł i opis.

Strony korporacyjne i sekcje na ACF Pro

Strony korporacyjne często trzymają dane członków zespołu – imię, stanowisko, biografię i zdjęcie – w polach ACF Pro. Gdy firma wchodzi na drugi język, tryb „Same fields across languages” zachowuje strukturę, a wartości tekstowe trafiają do tłumaczenia raz wprowadzone w języku domyślnym.

Zdjęcia można współdzielić między językami albo podmieniać per język przez komponent WPML Media Translation.

Odmienna treść per rynek językowy

Część projektów wymaga, by każda wersja językowa prezentowała inną treść, a nie tłumaczenie tej samej. Strona wydarzeń obsługująca odbiorców anglo- i hiszpańskojęzycznych może pokazywać zupełnie inne wpisy i wartości pól w każdym języku.

Tryb „Different fields across languages” realizuje ten scenariusz przez natywny edytor WordPress, gdzie każda wersja językowa to niezależny zestaw danych.

Karty produktów i globalne ustawienia witryny

Na kartach produktów część danych jest wspólna dla języków – cena, data, adres, parametry – a część wymaga tłumaczenia, jak tytuł i opis. Expert Mode ustawia preferencję per pole i eliminuje powielanie pracy nad danymi technicznymi.

Globalne ustawienia witryny – dane kontaktowe, logo, teksty stopki – zarządza się w Options Pages i wysyła do tłumaczenia z sekcji ACF Options w Translation Dashboard.

Dla kogo jest Advanced Custom Fields Multilingual

Advanced Custom Fields Multilingual jest przeznaczony dla deweloperów i agencji budujących wielojęzyczne strony oparte na ACF i WPML, gdzie spora część treści siedzi w polach niestandardowych. Produkt nie ma zastosowania na stronach bez WPML lub ACF ani na witrynach jednojęzycznych – w tych przypadkach spinacz nie ma czego obsługiwać.

Dla jakich projektów ACFML sprawdza się najlepiej

Dla kogo Advanced Custom Fields Multilingual sprawdza się najlepiej:

• Deweloperzy i agencje budujący wielojęzyczne strony na ACF i WPML, gdzie ważna treść siedzi w polach niestandardowych.
• Strony korporacyjne i landing page na ACF Pro z sekcjami budowanymi Repeaterem i Flexible Content, wchodzące na rynki zagraniczne.
• Sklepy i katalogi z danymi w polach ACF, gdzie część informacji jest wspólna dla języków, a część wymaga tłumaczenia.
• Strony z Options Pages w ACF Pro, których globalne ustawienia muszą różnić się per język.
• Deweloperzy używający Local Fields definiowanych w PHP lub JSON.

Dla kogo ACFML nie jest właściwym wyborem

Dla kogo Advanced Custom Fields Multilingual nie jest właściwym wyborem:

• Strony tłumaczone przez Polylang, TranslatePress czy Weglot – te narzędzia nie używają WPML i mają własne integracje z ACF.
• Strony bez pól ACF – do tłumaczenia samych wpisów i stron wystarcza WPML core.
• Witryny jednojęzyczne – produkt nie ma zastosowania bez co najmniej dwóch języków.

Integracje Advanced Custom Fields Multilingual

Advanced Custom Fields Multilingual integruje się z ACF i ACF Pro, z automatycznym tłumaczeniem WPML (DeepL, Google, Microsoft), z WPML Media Translation do podmiany obrazów per język oraz z blokami ACF w Gutenbergu. Pola ACF na produktach WooCommerce obsługuje wspólnie z komponentem WooCommerce Multilingual, a w setupach z builderami działa przez dynamic content.

ACF, ACF Pro i automatyczne tłumaczenie WPML

Integracja z ACF i ACF Pro jest rdzeniowa – to jedyny powód istnienia spinacza. ACFML jawnie obsługuje obie edycje wtyczki bazowej, więc działa zarówno z darmowym ACF, jak i z ACF Pro.

Wartości pól można tłumaczyć ręcznie albo przez automatyczne tłumaczenie WPML oparte o silniki DeepL, Google i Microsoft. Obrazy przypisane do pól obsługuje WPML Media Translation, co pozwala podmieniać grafikę per język nawet w trybie „Same fields”.

WooCommerce, bloki ACF i page buildery

Pola ACF używane na produktach WooCommerce stają się tłumaczalne, przy czym pełna ścieżka sklepu wielojęzycznego wymaga komponentu WooCommerce Multilingual po stronie WPML. Bloki ACF w Gutenbergu i Full Site Editing tłumaczą się tymi samymi trybami co pozostałe pola.

W setupach z page builderami pola ACF wyświetlane przez dynamic content działają z ACFML. Udokumentowany jest przewodnik dla Avada i Fusion Builder, a społeczność opisuje także konfiguracje z Divi i Elementorem.

Ograniczenia Advanced Custom Fields Multilingual

Advanced Custom Fields Multilingual nie działa bez WPML core, WPML String Translation i ACF – sam nie tłumaczy niczego. Do znanych ograniczeń należą rozsynchronizowanie tłumaczeń Repeatera przy zmianie kolejności wierszy, brak tłumaczenia linków zewnętrznych w trybie „Same fields” oraz problemy z Conditional Logic dla pól Taxonomy i Post Object w językach drugorzędnych.

Repeater i Flexible Content przy zmianie kolejności

Zmiana kolejności wierszy Repeatera lub usunięcie wiersza w języku domyślnym potrafi rozsynchronizować istniejące tłumaczenia. Pozycja figuruje na liście znanych problemów WPML.

Obejście: po zmianie kolejności wystarczy drobna zmiana w treści, na przykład spacja, żeby WPML utworzył nowe zadanie tłumaczenia w poprawnej kolejności.

Zasady nazewnictwa pól i pozostałe ograniczenia

Żeby pola pojawiły się do tłumaczenia, nazwa pola nie może powtarzać się wielokrotnie ani zaczynać od podkreślenia, jak _custom_field. Złamanie tej zasady sprawia, że pole nie trafi do Translation Dashboard.

Linki zewnętrzne nie są tłumaczalne w trybie „Same fields across languages”, a Conditional Logic dla pól Taxonomy i Post Object nie działa poprawnie w językach innych niż domyślny.

Wymagania techniczne i kompatybilność

Advanced Custom Fields Multilingual wymaga jednoczesnej obecności ACF lub ACF Pro, WPML core oraz WPML String Translation, a jako spinacz dziedziczy wymagania serwerowe WPML i ACF. Środowisko potrzebuje minimum 128 MB pamięci WordPress (rekomendowane 256 MB), włączonej funkcji PHP eval(), rozszerzenia libxml oraz struktury permalinków /%postname%/.

Wymagany stack wtyczek

ACFML nie ma osobnej, publicznej tabeli wymagań – jako glue plugin dziedziczy je z WPML i ACF. Wszystkie cztery wtyczki muszą współistnieć: ACF lub ACF Pro, WPML core, WPML String Translation oraz sam ACFML.

ACF i ACF Pro są zgodne aż do PHP 8.3, a WPML deklaruje kompatybilność z aktualnie wspieranymi wersjami WordPress i PHP. Producent nie podaje pojedynczego twardego minimum numerycznego, odsyłając do dynamicznej strony wymagań i narzędzia Site Health.

Wymagania serwerowe i pamięć PHP

Najczęstsze źródło problemów stacku WPML i ACF? Zbyt niski limit pamięci. Uwaga: minimum to 128 MB pamięci WordPress, a rekomendowane 256 MB – przy niższych wartościach pola ACF potrafią nie pojawiać się do tłumaczenia.

WPML wymaga włączonej funkcji PHP eval(), bo korzysta z frameworka TWIG, oraz rozszerzenia libxml. Zalecana struktura permalinków to /%postname%/, bo WPML dokleja informację o języku do adresu URL.

Najczęściej zadawane pytania