ACF Options Page WPML: How to Translate Without Duplication

Implementing an acf options page wpml setup incorrectly often leads to duplicate field groups, missing values, or settings reverting to default languages. This guide details the exact architecture required to run localized global fields without bloated database rows or broken templates.

Quick answer

• Register your ACF options page using acf_add_options_page() in PHP.
• Navigate to WPML > Settings > Custom Fields Translation and set your options page fields to Translate instead of Copy.
• Fetch values in templates using get_field('field_name', 'option') while WPML handles the active language context.
• Avoid creating separate options pages per language to prevent administrative overhead and sync issues.

Registering the Options Page in Code

Always register your global options pages via PHP rather than the WordPress admin interface. This ensures consistency across staging and production environments, and prevents WPML from losing track of the option page context during language switches.

if ( function_exists('acf_add_options_page') ) {
    acf_add_options_page(array(
        'page_title'    => 'Site Global Settings',
        'menu_title'    => 'Global Settings',
        'menu_slug'     => 'site-global-settings',
        'capability'    => 'manage_options',
        'redirect'      => false,
        'autoload'      => true,
    ));
}

Keep the options page slug consistent and avoid appending language codes to the slug. WPML manages the underlying database entries by appending language suffixes or storing them based on the active language context, so your code slug must remain uniform.

Configuring WPML Custom Field Translation

By default, WPML treats custom fields according to global rules or guesses their behavior. For an options page, you must explicitly configure how field groups behave across languages to prevent overwriting translations every time an administrator saves the default language.

Go to WPML > Settings > Custom Fields Translation in your WordPress dashboard. Locate your options page field group or individual fields. Set the translation preference explicitly:

• Translate: Allows different values for each language. Use this for text, headings, and localized links.
• Copy: Keeps the exact same value across all languages. Use this for numerical IDs, email addresses, or boolean toggles.
• Don't translate: Ignores the field entirely in secondary languages.

Never set translatable text fields to Copy if your clients need localized content. This is the single most common cause of translated text being overwritten by default language updates.

Fetching Localized ACF Option Values

When writing custom theme templates or building headless endpoints, retrieving the options data requires passing the correct second argument. The get_field() function natively respects the current WPML language context when called correctly.

// Fetching a translated option field in a standard theme template
$hero_title = get_field('global_hero_title', 'option');
echo esc_html( $hero_title );

If you need to fetch an option value for a specific language outside the current request context, you must temporarily switch the WPML language or use WPML's internal API to filter the options query. However, for 95 percent of use cases, relying on the active frontend language context is sufficient.

Handling REST API and Headless Endpoints

If you are using a headless architecture with Next.js, getting translated options requires exposing the fields through the WordPress REST API with proper language parameters. WPML adds language query parameters to REST requests.

// Ensure ACF fields are shown in REST and respect language parameters
add_filter('acf/settings/rest_api_format', function ( $format ) {
    return 'light';
});

Make sure your headless frontend passes the lang query parameter (e.g., ?lang=es) when fetching your custom options endpoint. This forces WPML to return the correct localized row from the wp_options table without requiring separate endpoints for every language.

Debugging Missing Field Values in Secondary Languages

If fields appear blank on secondary language options pages, check the database structure. WPML stores options with language-specific keys, typically prefixed with the language code (e.g., options_field_name_es).

1. Confirm the field group assignment rules point to your options page slug.
2. Verify that the field translation preference is set to Translate.
3. Check if the secondary language options page has been saved at least once in the admin panel.

If a secondary language options row has never been saved in the WordPress admin, ACF may fall back to the default language or return empty values depending on your caching layer.

Checklist

• Register options page via PHP using acf_add_options_page
• Set field translation preference to Translate in WPML settings
• Avoid duplicate field groups for different languages
• Use get_field('name', 'option') to respect active language context
• Test REST API endpoints with language query parameters for headless builds

Frequently asked questions