hirasso/acf-multilingual

An experimental plugin for building multilingual websites using WordPress and Advanced Custom Fields 🌀

v3.2.2 2025-11-17 09:36 UTC

Requires (Dev)

• laravel/pint: ^1.25
• pestphp/pest: ^1.23
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• roots/wordpress: ^6.8
• symfony/var-dumper: ^7.3
• wp-phpunit/wp-phpunit: ^6.8
• wpackagist-plugin/advanced-custom-fields: ^6.6
• wpackagist-plugin/classic-editor: ^1.6
• wpackagist-theme/twentytwentyfive: ^1.3
• yoast/wp-test-utils: ^1.2

GPL-2.0-or-later

• Rasso Hilber

README

An experimental plugin for building multilingual websites using WordPress and Advanced Custom Fields 🌀

Limitations

Does NOT integrate with plugins that add additional fields to the WordPress Admin, like e.g. Yoast SEO. Works best with fully customized pure WordPress/ACF setups.

Why did I make this public?

I made this public in the hopes to make it more sustainable and fail-proof. You will probably not want to use this plugin in big corporate projects, just yet (or ever). Use it for a personal website or the likes and report bugs and problems.

Usage

Installation

Via Composer (recommended):

1. Install the plugin:

composer require hirasso/acf-multilingual

1. Activate the plugin manually or using WP CLI:

wp plugin activate acf-multilingual

Manually:

1. Download and extract the plugin from the latest release
2. Copy the acf-multilingual folder into your wp-content/plugins folder
3. Activate the plugin via the plugins admin page – Done!
4. Handle updates via afragen/git-updater

Setup

Add as many languages as you like. The languages will be injected into the URL, like this:

https://yoursite.tld/your-post/ < default language
https://yoursite.tld/de/dein-eintrag/ < german translation
https://yoursite.tld/es/tu-entrada/ < spanish translation

Put a file acfml.config.json in your theme root, for example with these contents:

{
  "languages": {
    "en": {
      "locale": "en_US",
      "name": "English"
    },
    "de": {
      "locale": "de_DE",
      "name": "Deutsch"
    }
  },
  "post_types": {
    "page": true,
    "project": {
      "de": {
        "rewrite_slug": "projekt",
        "archive_slug": "projekte"
      }
    }
  },
  "taxonomies": {
    "filter": true
  }
}

This config will make:

• English the default language
• Deutsch the second language
• The post type "page" translatable
• The post type "project" translatable, with custom rewrite slugs for german
• The custom taxonomy "filter" translatable

API

To get an idea about what the plugin can do, it's probably quickest to have a look at the API.

Make ACF fields multilingual

Set ACF fields to be multilingual, so that they can be translated for every language. like e.g. Text, Textarea, WYSIWYG, ... (for the full list see $multilingual_field_types in the class FieldsController):

Now the field can be translated!

If you use vinkla/extended-acf, you can make fields multilingual like so:

\Extended\ACF\Fields\Text::make('Text')
    ->withSettings(['acfml_multilingual' => true]);

If a field is not marked multilingual, it will display the same value in both languages.