Step-by-Step Guide to building a custom automatic translation switcher block for Gutenberg using Vue micro-frontends

Project Setup: Vue Micro-Frontend and WordPress Integration

This guide details the construction of a custom Gutenberg block for WordPress, enabling an automatic translation switcher. We’ll leverage Vue.js for the frontend component, treating it as a micro-frontend integrated into the WordPress editor and frontend. This approach offers a modern, component-driven development experience for a critical e-commerce feature.

Our setup involves two primary components: the WordPress plugin acting as the host and the Vue application serving as the micro-frontend. We’ll use a build process to compile the Vue app and make its assets available to WordPress.

Step 1: Initialize the Vue Micro-Frontend

First, we need a standalone Vue project. We’ll use Vue CLI for this. If you don’t have Node.js and npm/yarn installed, please install them first.

Create a new Vue project:

npm init vue@latest translation-switcher-vue

Follow the prompts. For this example, we’ll select ‘No’ for TypeScript, ‘No’ for JSX, ‘Yes’ for Vue Router, ‘No’ for Pinia, ‘No’ for Vitest, and ‘No’ for End-to-End Testing. We’ll also choose ‘No’ for manually importing components and ‘No’ for auto-importing directives.

cd translation-switcher-vue
npm install
npm run dev

This starts a development server. We’ll modify the `src/App.vue` and `src/views/HomeView.vue` to create our basic switcher UI. For simplicity, we’ll assume a basic structure where the user can select a language. The actual translation logic will be handled by an external service or a WordPress plugin’s backend.

Step 2: Configure Vue for Micro-Frontend Deployment

To integrate Vue into WordPress, we need to build the Vue app into static assets (JavaScript and CSS) that WordPress can enqueue. We’ll configure Vite (the default bundler in Vue CLI 3+) for this.

Modify the `vite.config.js` file in your Vue project:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  build: {
    outDir: '../wp-content/plugins/my-translation-plugin/assets/js/vue-app', // Output directory relative to the plugin root
    assetsDir: '.', // Keep assets in the root of outDir
    manifest: true, // Generate manifest.json for asset mapping
    rollupOptions: {
      input: {
        main: fileURLToPath(new URL('./src/main.js', import.meta.url)),
      },
      output: {
        entryFileNames: `[name]-[hash].js`,
        chunkFileNames: `[name]-[hash].js`,
        assetFileNames: `[name]-[hash].[ext]`,
      },
    },
  }
})

The key changes here are:

build.outDir: Specifies where Vite should output the built assets. We’re pointing it to a directory within our future WordPress plugin.
build.manifest: true: This is crucial. Vite will generate a manifest.json file that maps the original entry point names (like main) to their hashed, versioned output filenames. WordPress will use this to correctly enqueue the built assets.
build.rollupOptions.input: Defines the entry point(s) for our Vue application.
build.rollupOptions.output: Configures the naming pattern for output files, including hashing for cache busting.

Step 3: Create the WordPress Plugin Structure

Now, let’s set up the WordPress plugin that will host our Vue micro-frontend and Gutenberg block.

Create a new directory in wp-content/plugins/ named my-translation-plugin. Inside it, create the main plugin file:

// my-translation-plugin.php
<?php
/**
 * Plugin Name: My Translation Switcher
 * Description: Adds a custom Gutenberg block for automatic translation switching using a Vue micro-frontend.
 * Version: 1.0.0
 * Author: Your Name
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

define( 'MY_TRANSLATION_PLUGIN_PATH', plugin_dir_path( __FILE__ ) );
define( 'MY_TRANSLATION_PLUGIN_URL', plugin_dir_url( __FILE__ ) );

// Enqueue Gutenberg block assets
function my_translation_plugin_enqueue_block_assets() {
    // Enqueue Vue app assets based on manifest.json
    $manifest_file = MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/manifest.json';

    if ( file_exists( $manifest_file ) ) {
        $manifest = json_decode( file_get_contents( $manifest_file ), true );

        if ( isset( $manifest['main.js'] ) ) {
            wp_enqueue_script(
                'my-translation-plugin-vue-app',
                MY_TRANSLATION_PLUGIN_URL . 'assets/js/vue-app/' . $manifest['main.js'],
                array(), // Dependencies (e.g., 'react', 'react-dom' if using React)
                filemtime( MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/' . $manifest['main.js'] )
            );
        }

        if ( isset( $manifest['style.css'] ) ) { // Assuming Vite also outputs a style.css
            wp_enqueue_style(
                'my-translation-plugin-vue-app-style',
                MY_TRANSLATION_PLUGIN_URL . 'assets/js/vue-app/' . $manifest['style.css'],
                array(),
                filemtime( MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/' . $manifest['style.css'] )
            );
        }
    } else {
        // Fallback or error handling if manifest.json is not found
        error_log('Manifest file not found for My Translation Switcher Vue app.');
    }

    // Enqueue Gutenberg block editor specific assets
    wp_enqueue_script(
        'my-translation-plugin-editor-script',
        MY_TRANSLATION_PLUGIN_URL . 'build/index.js',
        array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components', 'wp-i18n' ),
        filemtime( MY_TRANSLATION_PLUGIN_PATH . 'build/index.js' )
    );

    wp_enqueue_style(
        'my-translation-plugin-editor-style',
        MY_TRANSLATION_PLUGIN_URL . 'build/index.css',
        array( 'wp-edit-blocks' ),
        filemtime( MY_TRANSLATION_PLUGIN_PATH . 'build/index.css' )
    );
}
add_action( 'enqueue_block_editor_assets', 'my_translation_plugin_enqueue_block_assets' );

// Enqueue Vue app assets for the frontend
function my_translation_plugin_enqueue_frontend_assets() {
    $manifest_file = MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/manifest.json';

    if ( file_exists( $manifest_file ) ) {
        $manifest = json_decode( file_get_contents( $manifest_file ), true );

        if ( isset( $manifest['main.js'] ) ) {
            wp_enqueue_script(
                'my-translation-plugin-vue-app-frontend',
                MY_TRANSLATION_PLUGIN_URL . 'assets/js/vue-app/' . $manifest['main.js'],
                array(), // Dependencies
                filemtime( MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/' . $manifest['main.js'] )
            );
        }

        if ( isset( $manifest['style.css'] ) ) {
            wp_enqueue_style(
                'my-translation-plugin-vue-app-style-frontend',
                MY_TRANSLATION_PLUGIN_URL . 'assets/js/vue-app/' . $manifest['style.css'],
                array(),
                filemtime( MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/' . $manifest['style.css'] )
            );
        }
    }
}
add_action( 'wp_enqueue_scripts', 'my_translation_plugin_enqueue_frontend_assets' );

// Register the Gutenberg block
function my_translation_plugin_register_block() {
    register_block_type( 'my-translation-plugin/translation-switcher', array(
        'editor_script' => 'my-translation-plugin-editor-script',
        'editor_style'  => 'my-translation-plugin-editor-style',
        'style'         => 'my-translation-plugin-editor-style', // Can be the same or a separate frontend style
        'render_callback' => 'my_translation_plugin_render_block',
    ) );
}
add_action( 'init', 'my_translation_plugin_register_block' );

// Render callback for the block (optional, can also be handled by JS)
function my_translation_plugin_render_block( $attributes ) {
    // This function can render static HTML or a placeholder for the Vue app
    // For a micro-frontend, it's often better to let the JS handle mounting
    // and rendering, but a fallback is good.
    return '<div id="my-translation-switcher-app"></div>';
}
?>

Create the following directories and files within my-translation-plugin:

assets/js/vue-app/: This is where Vite will output the built Vue application.
src/: This directory will contain the JavaScript for our Gutenberg block.
src/index.js: The main entry point for the Gutenberg block.
src/edit.js: The component for the block’s editor view.
src/save.js: The component for the block’s frontend view (often a placeholder for the Vue app).
src/block.json: Metadata for the Gutenberg block.

Step 4: Build the Gutenberg Block with JavaScript

We’ll use the WordPress Script package (formerly @wordpress/scripts) to build our block’s JavaScript and CSS. Install it as a development dependency in your plugin’s root directory:

cd my-translation-plugin
npm init -y
npm install @wordpress/scripts --save-dev

Add build scripts to your package.json:

{
  "name": "my-translation-plugin",
  "version": "1.0.0",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "^26.10.0"
  }
}

Now, create the block’s source files:

`my-translation-plugin/src/block.json`

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-translation-plugin/translation-switcher",
  "version": "0.1.0",
  "title": "Translation Switcher",
  "category": "widgets",
  "icon": "translation",
  "description": "An automatic translation switcher block using a Vue micro-frontend.",
  "attributes": {
    "message": {
      "type": "string",
      "default": "Hello from Translation Switcher!"
    }
  },
  "editorScript": "file:../build/index.js",
  "editorStyle": "file:../build/index.css",
  "style": "file:../build/index.css"
}

`my-translation-plugin/src/index.js`

import { registerBlockType } from '@wordpress/blocks';
import './style.scss'; // Global styles for the block
import Edit from './edit';
import save from './save';
import metadata from './block.json';

registerBlockType( metadata.name, {
    edit: Edit,
    save,
} );

`my-translation-plugin/src/edit.js`

import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';
import './editor.scss'; // Editor-specific styles

export default function Edit( { attributes, setAttributes } ) {
    const blockProps = useBlockProps();
    const { message } = attributes;

    const onChangeMessage = ( newMessage ) => {
        setAttributes( { message: newMessage } );
    };

    return (
        <>
            <InspectorControls>
                <PanelBody title={ __( 'Settings', 'my-translation-plugin' ) }>
                    <TextControl
                        label={ __( 'Message', 'my-translation-plugin' ) }
                        value={ message }
                        onChange={ onChangeMessage }
                    />
                </PanelBody>
            </InspectorControls>
            <div { ...blockProps }>
                <p>{ message }</p>
                <p>{ __( 'This is the editor view. The Vue app will mount here.', 'my-translation-plugin' ) }</p>
                <div id="my-translation-switcher-app"></div> {/* Mount point for Vue app */}
            </div>
        </>
    );
}

`my-translation-plugin/src/save.js`

import { useBlockProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
    const blockProps = useBlockProps.save();
    const { message } = attributes;

    return (
        <div { ...blockProps }>
            <p>{ message }</p>
            <div id="my-translation-switcher-app"></div> {/* Mount point for Vue app */}
        </div>
    );
}

`my-translation-plugin/src/style.scss`

/**
 * Styles shared between the editor and the frontend.
 */

.wp-block-my-translation-plugin-translation-switcher {
    border: 1px solid #ccc;
    padding: 15px;
    margin-bottom: 15px;
    background-color: #f9f9f9;
}

`my-translation-plugin/src/editor.scss`

/**
 * Editor-specific styles.
 */

.wp-block-my-translation-plugin-translation-switcher {
    background-color: #e0f0ff;
}

After creating these files, run the build command in your plugin’s root directory:

cd my-translation-plugin
npm run build

This will compile your block’s JavaScript and CSS into the build/ directory. Now, activate “My Translation Switcher” in your WordPress admin. You should be able to add the “Translation Switcher” block to your posts and pages.

Step 5: Integrate Vue App Mounting

The Gutenberg block’s `edit.js` and `save.js` include a <div id="my-translation-switcher-app"></div>. This `div` will serve as the mount point for our Vue application. We need to write JavaScript that finds this element and mounts the Vue app.

Modify your Vue app’s src/main.js to export a mount function:

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router' // Assuming you have Vue Router configured

// Function to mount the Vue app to a specific element
export function mountVueApp(selector) {
  const app = createApp(App)
  app.use(router)
  app.mount(selector)
  return app; // Return the app instance if needed
}

// Optional: Auto-mount if this is the main entry point and not a micro-frontend
// This part might be commented out or removed when used as a micro-frontend
// if (document.getElementById('app')) {
//   mountVueApp('#app');
// }

Now, in your WordPress plugin, create a JavaScript file (e.g., assets/js/vue-app-initializer.js) to handle mounting the Vue app. This script will be enqueued on both the frontend and the editor.

Create my-translation-plugin/assets/js/vue-app-initializer.js:

/**
 * Initializes the Vue micro-frontend translation switcher.
 */

// Import the mount function from your Vue app
// The path needs to be relative to this file after Vite builds it.
// Vite's build process will handle resolving this import.
import { mountVueApp } from '../../../../assets/js/vue-app/src/main.js'; // Adjust path as needed

document.addEventListener('DOMContentLoaded', () => {
    // Find all potential mount points for the translation switcher
    const mountPoints = document.querySelectorAll('#my-translation-switcher-app');

    mountPoints.forEach(mountPoint => {
        // Check if the Vue app is already mounted to avoid duplicates
        if (!mountPoint.__vue_app__) {
            console.log('Mounting Vue translation switcher app to:', mountPoint);
            const vueAppInstance = mountVueApp(mountPoint);
            // Store the app instance on the element for potential future reference
            mountPoint.__vue_app__ = vueAppInstance;
        }
    });
});

You need to tell Vite to also build this initializer script. Modify your vite.config.js:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  build: {
    outDir: '../wp-content/plugins/my-translation-plugin/assets/js/vue-app',
    assetsDir: '.',
    manifest: true,
    rollupOptions: {
      input: {
        // Main Vue app entry point
        main: fileURLToPath(new URL('./src/main.js', import.meta.url)),
        // Add the initializer script as another entry point
        'initializer': fileURLToPath(new URL('./assets/js/vue-app-initializer.js', import.meta.url)),
      },
      output: {
        entryFileNames: `[name]-[hash].js`,
        chunkFileNames: `[name]-[hash].js`,
        assetFileNames: `[name]-[hash].[ext]`,
      },
    },
  }
})

Now, rebuild your Vue app:

cd my-translation-plugin/translation-switcher-vue
npm run build

This will generate main-hash.js, initializer-hash.js, and manifest.json in my-translation-plugin/assets/js/vue-app/. The `manifest.json` will now contain entries for both `main.js` and `initializer.js`.

Finally, enqueue the initializer script in your WordPress plugin’s PHP file. We need to enqueue it on both the editor and the frontend.

Step 6: Enqueue the Initializer Script

Update the my_translation_plugin_enqueue_block_assets and my_translation_plugin_enqueue_frontend_assets functions in my-translation-plugin.php to include the initializer script.

// ... (previous PHP code) ...

// Enqueue Vue app assets for the editor
function my_translation_plugin_enqueue_block_assets() {
    // ... (existing Vue app asset enqueuing) ...

    // Enqueue the initializer script for the editor
    $manifest_file = MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/manifest.json';
    if ( file_exists( $manifest_file ) ) {
        $manifest = json_decode( file_get_contents( $manifest_file ), true );
        if ( isset( $manifest['initializer.js'] ) ) {
            wp_enqueue_script(
                'my-translation-plugin-vue-initializer',
                MY_TRANSLATION_PLUGIN_URL . 'assets/js/vue-app/' . $manifest['initializer.js'],
                array( 'wp-element', 'my-translation-plugin-vue-app' ), // Dependency on Vue app script
                filemtime( MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/' . $manifest['initializer.js'] )
            );
        }
    }

    // ... (existing Gutenberg block editor asset enqueuing) ...
}
add_action( 'enqueue_block_editor_assets', 'my_translation_plugin_enqueue_block_assets' );

// Enqueue Vue app assets for the frontend
function my_translation_plugin_enqueue_frontend_assets() {
    // ... (existing Vue app asset enqueuing) ...

    // Enqueue the initializer script for the frontend
    $manifest_file = MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/manifest.json';
    if ( file_exists( $manifest_file ) ) {
        $manifest = json_decode( file_get_contents( $manifest_file ), true );
        if ( isset( $manifest['initializer.js'] ) ) {
            wp_enqueue_script(
                'my-translation-plugin-vue-initializer-frontend',
                MY_TRANSLATION_PLUGIN_URL . 'assets/js/vue-app/' . $manifest['initializer.js'],
                array( 'my-translation-plugin-vue-app-frontend' ), // Dependency on Vue app script
                filemtime( MY_TRANSLATION_PLUGIN_PATH . 'assets/js/vue-app/' . $manifest['initializer.js'] )
            );
        }
    }
}
add_action( 'wp_enqueue_scripts', 'my_translation_plugin_enqueue_frontend_assets' );

// ... (rest of the PHP code) ...

After rebuilding your Vue app and ensuring the PHP is updated, you should see the Vue application mount within the Gutenberg editor and on the frontend when the block is present. The `console.log` message should appear in your browser’s developer console.

Step 7: Implementing Translation Logic

The Vue application now mounts, but it doesn’t perform any translation. This is where you’d integrate with a translation service (e.g., Google Translate API, DeepL API) or a WordPress translation plugin’s API.

Example: Basic Language Selection in Vue

In your Vue app (e.g., src/App.vue or a dedicated component), you might have:

<template>
  <div id="app">
    <h1>Translation Switcher</h1>
    <select v-model="selectedLanguage" @change="switchLanguage">
      <option disabled value="">Please select one</option>
      <option v-for="lang in languages" :key="lang.code" :value="lang.code">
        {{ lang.name }}
      </option>
    </select>
    <p>Current language: {{ currentLanguage }}</p>
    <!-- Content to be translated -->
    <div>
      <p>{{ translatedContent }}</p>
    </div>
  </div>
</template>

<script>
import { ref, onMounted } from 'vue';
// Assume you have a service to fetch translations
// import TranslationService from './services/TranslationService';

export default {
  name: 'App',
  setup() {
    const selectedLanguage = ref('');
    const currentLanguage = ref('en'); // Default language
    const translatedContent = ref('This is the content to be translated.');
    const languages = ref([
      { code: 'en', name: 'English' },
      { code: 'es', name: 'Spanish' },
      { code: 'fr', name: 'French' },
    ]);

    const switchLanguage = async () => {
      currentLanguage.value = selectedLanguage.value;
      // In a real app, you'd call a translation API here
      // For example:
      // const response = await TranslationService.translate(translatedContent.value, currentLanguage.value);
      // translatedContent.value = response.translatedText;
      console.log(`Switching to ${currentLanguage.value}`);
      // For demonstration, just update the displayed text
      if (currentLanguage.value === 'es') {
        translatedContent.value = 'Este es el contenido a traducir.';
      } else if (currentLanguage.value === 'fr') {
        translatedContent.value = 'Ceci est le contenu à traduire.';
      } else {
        translatedContent.value = 'This is the content to be translated.';
      }
    };

    onMounted(() => {
      // Initialize with current language or detect from browser/URL
      // Fetch initial translations if needed
    });

    return {
      selectedLanguage,
      currentLanguage,
      translatedContent,
      languages,
      switchLanguage,
    };
  },
};
</script>

<style scoped>
/* Add your styles here */
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
select {
  padding: 10px;
  margin: 10px;
  border-radius: 5px;
  border: 1px solid #ccc;
}
p {
  font-size: 1.2em;
}
</style>

Backend Integration (WordPress)

For e-commerce, you’ll likely need to:

Store translation settings (API keys, default languages) in WordPress options.
Potentially use WordPress REST API or AJAX to fetch translations server-side if client-side API calls are not desired.
Integrate with existing WordPress translation plugins (e.g., WPML, Polylang) if they provide APIs.

Step 8: Deployment and Production Build

For production, you’ll need to:

Run the Vue build command: cd my-translation-plugin/translation-switcher-vue && npm run build. This creates optimized, minified assets in my-translation-plugin/assets/js/vue-app/.
Run the WordPress block build command: cd my-translation-plugin && npm run build. This creates optimized, minified assets in my-translation-plugin/build/.
Ensure your web server is configured to serve these static assets efficiently.

The `filemtime()` function used in `wp_enqueue_script` and `wp_enqueue_style` will automatically add a version query string based on the file’s last modification time, aiding cache busting. For more robust cache busting, you could use a hash from the Vite manifest directly in the version parameter.

Conclusion

By following these steps, you’ve successfully integrated a Vue.js micro-frontend into a WordPress Gutenberg block. This architecture provides a flexible and modern way to build complex features like translation switchers for your e-commerce site, separating concerns and allowing for independent development and deployment of frontend components.

Step-by-Step Guide to building a custom automatic translation switcher block for Gutenberg using Vue micro-frontends

Project Setup: Vue Micro-Frontend and WordPress Integration

Step 1: Initialize the Vue Micro-Frontend

Step 2: Configure Vue for Micro-Frontend Deployment

Step 3: Create the WordPress Plugin Structure

Step 4: Build the Gutenberg Block with JavaScript

my-translation-plugin/src/block.json

my-translation-plugin/src/index.js

my-translation-plugin/src/edit.js

my-translation-plugin/src/save.js

my-translation-plugin/src/style.scss

my-translation-plugin/src/editor.scss