Skip to content Skip to sidebar
Home » WPML Documentation » Related Projects » Advanced Custom Fields (ACF) Multilingual – Translate All Fields with WPML » Setting Translation Preferences for ACF fields in PHP and JSON Files

Setting Translation Preferences for ACF fields in PHP and JSON Files

Kathy
Updated
March 3, 2026

Learn how to set translation preferences for ACF fields registered in PHP, and automatically include them in JSON files generated by ACF.

Setting Translation Preferences for ACF Fields Registered with PHP

To set translation preferences for ACF fields registered with PHP, you need to use the acf_add_local_field_group function and add wpml_cf_preferences to each field’s definition.

There are four numerical values you can use for wpml_cf_preferences:

  • 0 — Don’t translate. WPML ignores the field entirely.
  • 1 — Copy. The field value is copied to all languages and stays in sync.
  • 2 — Translate. The field value is made available for translation.
  • 3 — Copy once. The field value is copied to all languages once, after which it can be edited in each language independently.

Not sure which translation option to use? See the recommended option for each ACF field.

Below you can see an example of adding the wpml_cf_preferences key to a programmatically registered field group.

acf_add_local_field_group( [
    'key'                   => 'group_1',
    'title'                 => 'My Group',
    'fields'                => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'prefix'              => '',
            'instructions'        => '',
            'required'            => 0,
            'conditional_logic'   => 0,
            'wrapper'             => [
                'width' => '',
                'class' => '',
                'id'    => '',
            ],
            'default_value'       => '',
            'placeholder'         => '',
            'prepend'             => '',
            'append'              => '',
            'maxlength'           => '',
            'readonly'            => 0,
            'disabled'            => 0,
            'wpml_cf_preferences' => 2, // This field ("Sub Title") will be translated.
        ],
    ],
    'location'              => [
        [
            [
                'param'    => 'post_type',
                'operator' => '==',
                'value'    => 'post',
            ],
        ],
    ],
    'menu_order'            => 0,
    'position'              => 'normal',
    'style'                 => 'default',
    'label_placement'       => 'top',
    'instruction_placement' => 'label',
    'hide_on_screen'        => '',
] );

Syncing Your Fields With WPML

After defining your fields using PHP, you need to tell WPML about them.

  1. Go to ACF → Tools page.
  2. Scroll down to Translate ACF Local JSON and PHP-Registered Fields.
Syncing local ACF fields with WPML
  1. In the Sync Translation Preferences for Local Fields section, select when the syncing should happen. In most cases, you will want to use the Sync once now option and then click the Apply button.

WPML will sync the fields and then reset to the non-syncing option. This way, syncing hits your database only once and at the time you choose.

Setting Translation Preferences for ACF Fields in JSON Files

If you’re using ACF’s Local JSON feature, ACF Multilingual (ACFML) automatically adds translation preferences for every field in your JSON file. This means when you export and import JSON files between sites, the translation preferences apply automatically on the destination site. 

All you need to do is activate ACFML on both the origin and destination site. Once done, every time ACF generates a JSON file, it will also include your translation preferences.

If your JSON files were originally generated without ACFML active, activate ACFML, import the JSON files into the ACF user interface, set the translation preferences, and re-save the field groups. This regenerates the JSON files with the preferences included.