So übersetzen Sie benutzerdefinierte ACF-Felder in WordPress – Feldgruppen, Repeater, Optionsseiten

Bevor Sie beginnen

Installieren und aktivieren Sie diese Plugins:

• Advanced Custom Fields oder ACF Pro.
• WPML und WPML String-Übersetzung.
• ACFML (das Add-on, das auf dieser Seite behandelt wird).

Ihre Feldgruppen sollten bereits in ACF konfiguriert sein. Sie können die Übersetzungseinstellungen für jedes Feld auch nachträglich ändern, die Reihenfolge der Schritte spielt also keine Rolle. Richten Sie die Feldgruppen ein und kehren Sie dann zu ACFML zurück.

Wählen Sie einen Übersetzungsmodus für jede Feldgruppe

ACF-Feldgruppen verhalten sich bei der Übersetzung nicht alle gleich. ACFML bietet drei Modi pro Feldgruppe, die unter ACF → Feldgruppen im Abschnitt Multilingual Setup festgelegt werden:

Gleiche Felder in allen Sprachen

Die typische Einstellung für die meisten ACF-Websites. Übersetzen Sie die Feldwerte in jede Sprache, während die Struktur gleich bleibt. Die Seite Unser Team ist das klassische Beispiel. Ihr Team ist in jeder Sprache dasselbe, daher werden Name und Biografie jedes Teammitglieds pro Sprache übersetzt, während die Feldstruktur intakt bleibt. Sie geben das Team in der Ausgangssprache ein und senden den Beitrag dann über WPML → Übersetzungen → Dashboard zur Übersetzung; die übersetzten Werte kommen an dieselben Felder angehängt zurück.

Unterschiedliche Felder in verschiedenen Sprachen

Verwenden Sie dies, wenn jede Sprache grundlegend andere Inhalte in derselben Feldgruppe anzeigt. Der klassische Fall ist ein Unternehmen, das lokalisierte Veranstaltungen durchführt. Die englische Seite Events zeigt Veranstaltungen für das englische Publikum, die französische Seite zeigt Veranstaltungen für das französische Publikum. Setzen Sie die Feldgruppe auf Unterschiedliche Felder in verschiedenen Sprachen, öffnen Sie dann den Beitrag, den Sie lokalisieren möchten → klicken Sie rechts in der Box Sprachen auf das Plus-Symbol für die Zielsprache → es öffnet sich ein leerer Entwurf mit leeren benutzerdefinierten Feldern → füllen Sie die sprachspezifischen Werte aus und veröffentlichen Sie ihn.

Expertenmodus

Verwenden Sie dies, wenn Sie eine Mischung benötigen: Einige Felder werden pro Sprache übersetzt, andere bleiben gleich, wieder andere werden einmal kopiert und weichen dann ab. Wählen Sie beim Einrichten der Feldgruppe Expertenmodus und legen Sie die Einstellung pro Feld fest. Das Events-Beispiel mit gemischtem Verhalten: Titel und Beschreibung sind auf Übersetzen gesetzt; Preis, Datum und Adresse auf Kopieren.

Übersetzungseinstellungen für jeden ACF-Feldtyp

Jedes Feld in einer Feldgruppe hat eine von vier Übersetzungseinstellungen:

• Übersetzen. Der Wert des Feldes wird pro Sprache übersetzt.
• Kopieren. Der Wert des Feldes bleibt über alle Sprachen hinweg synchron; Sie bearbeiten ihn einmal und er wird übernommen.
• Einmal kopieren. Der Wert des Feldes dient als Ausgangsbasis für die Übersetzung, danach kann jede Sprachversion unabhängig bearbeitet werden.
• Nicht übersetzen. Das Feld wird beim Übersetzungsvorgang ignoriert.

Wenn Sie Gleiche Felder in allen Sprachen oder Unterschiedliche Felder in verschiedenen Sprachen wählen, erhält jedes Feld basierend auf seinem Feldtyp eine sinnvolle Standardeinstellung. Die folgenden Tabellen zeigen diese Standards. Verwenden Sie den Expertenmodus, um sie pro Feld zu überschreiben, oder verwenden Sie den Filter acfml_field_group_mode_field_translation_preference, um den Standard für einen Feldtyp auf der gesamten Website zu überschreiben (siehe Entwickler-Hooks für Sonderfälle unten).

Repeater und Flexible Content – Kopieren oder Einmal kopieren

Für Repeater- und Flexible-Content-Felder wählen Sie zwischen zwei Verhaltensweisen auf Zeilenebene, bevor die Einstellungen für Unterfelder greifen:

• Kopieren. Gleiches Layout und gleiche Anzahl von Zeilen in jeder Sprache. Übersetzer sehen dieselben Zeilen; Unterfelder werden gemäß ihren eigenen Einstellungen übersetzt.
• Einmal kopieren. Jede Sprache kann nach der anfänglichen Befüllung ein anderes Layout und eine andere Anzahl von Zeilen haben.

Wählen Sie Kopieren, wenn die Struktur in allen Sprachen gleich ist (in den meisten Fällen). Wählen Sie Einmal kopieren, wenn die Sprachversionen strukturell abweichen (z. B. eine unterschiedliche Veranstaltungsliste pro Sprache).

Einfache Felder

Inhaltsfelder

Auswahlfelder

jQuery-Felder

Layout-Felder

Relationale Felder

Einstellungen für in PHP oder JSON registrierte Felder festlegen

ACF-Feldgruppen, die in PHP (über acf_add_local_field_group()) oder durch die Local JSON-Funktion von ACF registriert wurden, übernehmen keine Übersetzungseinstellungen aus der Admin-Benutzeroberfläche, da der Admin-Bereich sie nicht verwaltet. Legen Sie die Einstellungen an derselben Stelle fest, an der Sie die Felder registrieren.

Fügen Sie für jedes Feld in der Feldgruppendefinition einen Schlüssel wpml_cf_preferences hinzu. Der Wert ist eine Ganzzahl, die den vier Übersetzungseinstellungen zugeordnet ist: 0 für Nicht übersetzen (WPML ignoriert das Feld), 1 für Kopieren (der Wert bleibt über alle Sprachen hinweg synchron), 2 für Übersetzen (der Wert durchläuft die Übersetzung) und 3 für Einmal kopieren (der Wert wird in neue Übersetzungen kopiert, danach kann jede Sprache unabhängig bearbeitet werden).

Ein minimales Beispiel:

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
] );

Nachdem Sie die Felder im Code definiert haben, synchronisieren Sie die Einstellungen in WPML, damit der Admin-Bereich sie erkennt:

1. Gehen Sie zu ACF → Werkzeuge.
2. Scrollen Sie zu Translate ACF Local JSON and PHP-Registered Fields.
3. Wählen Sie unter Sync Translation Preferences for Local Fields die Option Sync once now und klicken Sie auf Apply.

WPML liest die Einstellungen aus Ihren PHP-Definitionen und speichert sie. Die Synchronisierung wird einmal ausgeführt, wenn Sie sie auslösen, nicht bei jedem Seitenaufruf.

Wenn Sie die Local JSON-Funktion von ACF verwenden, um Feldgruppen zwischen Websites zu teilen, schreibt ACFML die Übersetzungseinstellungen automatisch in die JSON-Dateien. Exportieren Sie eine JSON-Datei von einer Website, importieren Sie sie auf einer anderen, und die Ziel-Website übernimmt die Einstellungen, sobald ACFML auf beiden Seiten aktiv ist.

ACF-Feldbezeichnungen übersetzen

ACF-Feldbezeichnungen sind die Namen, die jedes benutzerdefinierte Feld im WordPress-Editor und im Frontend identifizieren (z. B. Telefonnummer, Adresse). Sie werden separat von den Feldwerten übersetzt und befinden sich in der WPML String-Übersetzung, nicht im Übersetzungsauftrag des Beitrags.

So senden Sie Feldbezeichnungen zur Übersetzung:

1. Öffnen Sie WPML → Übersetzungen → Dashboard.
2. Erweitern Sie den Abschnitt ACF Field Group.
3. Wählen Sie das Element Field Group Labels für die Feldgruppe aus, die Sie übersetzen möchten.
4. Wählen Sie eine Übersetzungsmethode (PTC, Ihren Übersetzer oder Selbst übersetzen) und senden Sie sie ab.

Die übersetzten Bezeichnungen erscheinen automatisch im Frontend, sobald die Übersetzung abgeschlossen ist.

ACF-Feldauswahlmöglichkeiten übersetzen

Auswahlfelder (Auswahl, Kontrollkästchen, Optionsfeld, Schaltflächengruppe) haben ihre eigenen Optionsbezeichnungen (z. B. Klein / Mittel / Groß). Diese befinden sich ebenfalls neben den Feldbezeichnungen und nicht innerhalb der Beitragsübersetzung. Senden Sie sie auf die gleiche Weise:

1. Öffnen Sie WPML → Übersetzungen → Dashboard.
2. Erweitern Sie den Abschnitt ACF Field Group.
3. Wählen Sie die Feldgruppe aus, deren Auswahlwerte Sie übersetzen möchten.
4. Wählen Sie eine Übersetzungsmethode und senden Sie sie ab.

ACF-Optionsseiten übersetzen

ACF-Optionsseiten (globale Einstellungsseiten wie Kontaktdaten, Header-Einstellungen, Footer-Links) werden als eigener Objekttyp separat von Beiträgen übersetzt:

1. Öffnen Sie WPML → Übersetzungen → Dashboard.
2. Erweitern Sie den Abschnitt ACF Options.
3. Wählen Sie die Optionsseite aus, die Sie übersetzen möchten.
4. Wählen Sie eine Übersetzungsmethode und senden Sie sie ab.

Die Werte der Optionsseite für jede Sprache erscheinen automatisch, wenn ACF die Option im Kontext dieser Sprache liest.

Häufige Fallstricke

• Feldbezeichnungen erscheinen unübersetzt. Sie befinden sich in der String-Übersetzung, nicht in der Beitragsübersetzung. Senden Sie das Element Field Group Labels der Feldgruppe über das Dashboard (siehe ACF-Feldbezeichnungen übersetzen oben).
• Auswahlwerte erscheinen unübersetzt. Gleiches Prinzip. Senden Sie die Feldgruppe aus dem Abschnitt ACF Field Group des Dashboards, damit die Optionswerte einbezogen werden.
• Repeater-Zeilen sind nicht mehr synchron. Das Feld ist wahrscheinlich auf Einmal kopieren gesetzt, während Kopieren die Zeilen synchron halten würde. Öffnen Sie die Feldgruppe → ändern Sie das Verhalten des Repeater-Feldes auf Kopieren.
• Bedingte Logik verhält sich unerwartet. Wenn das steuernde Feld auf Kopieren oder Nicht übersetzen gesetzt ist, folgt das bedingte Verhalten dem Wert der Ausgangssprache in allen Übersetzungen. Setzen Sie das steuernde Feld auf Übersetzen, wenn sich sein Wert je nach Sprache unterscheiden soll.
• Lokale Felder (in PHP registriert) ignorieren die im Admin-Bereich festgelegten Übersetzungseinstellungen. Setzen Sie den Schlüssel wpml_cf_preferences in der Feldgruppendefinition selbst und synchronisieren Sie über ACF → Werkzeuge. Das Verfahren ist oben unter Einstellungen für in PHP oder JSON registrierte Felder festlegen beschrieben. Mit ACFML 2.2.0 (Feb. 2026) kam die vollständige Unterstützung für lokale Felder hinzu; ältere Versionen hatten hier Einschränkungen.

Entwickler-Hooks für Sonderfälle

Für die programmatische Steuerung (bestimmte Felder von der Übersetzung ausschließen, die Standardeinstellung für einen Feldtyp auf der gesamten Website überschreiben, Anmerkungen vor Übersetzern ausblenden oder Feldgruppen-Strings von Übersetzungsaufträgen für Beiträge ausschließen) stellt ACFML zwei Filter und vier Konstanten zur Verfügung. Die vollständige Referenz mit Codebeispielen finden Sie unter ACFML-Referenz für Hooks und Konstanten.