Da Idea a Plugin WordPress: Creare una Modalità Manutenzione (con Traduzione!)

> pub_date:

Hai mai pensato di creare un tuo plugin per WordPress? Può sembrare complicato, ma con gli strumenti giusti e un approccio passo-passo, è più accessibile di quanto pensi.

In questo post vedremo come creare un plugin semplice ma utile: una modalità di manutenzione personalizzabile per il tuo sito. Seguiremo insieme l’intero processo, dalla scrittura del codice alla preparazione per la distribuzione, inclusa la traduzione multilingua e il controllo di conformità.

Per esemplificare il processo utilizzeremo un caso reale: la creazione del plugin OperWEB Maintenance Mode per i clienti del mio brand OperWEB.

Il plugin è disponibile su GitHub — e nel frattempo è stato aggiornato con auto-aggiornamento integrato direttamente dalla bacheca WordPress: 👉 github.com/fabrizioortis/operweb-maintenance-mode

Cosa creeremo

Un plugin “OperWEB Maintenance Mode” che:

  • Mostra una pagina di manutenzione personalizzata ai visitatori.
  • Permette agli amministratori di vedere il sito normalmente.
  • Ha una pagina di impostazioni per attivare/disattivare, caricare un logo, inserire testo e scegliere colori.
  • È traducibile in diverse lingue (Italiano e Inglese inclusi).
  • È conforme agli standard di WordPress.org.

Strumenti che useremo

  • Un editor di codice (es. VS Code, Sublime Text, ecc.)
  • Una installazione locale o di test di WordPress
  • Il plugin Loco Translate (gratuito)
  • Il plugin Plugin Check (gratuito, da WordPress.org)

1. La Struttura Base del Plugin

Ogni plugin inizia con una cartella e un file PHP principale.

Crea la cartella: dentro wp-content/plugins/, crea una cartella chiamata operweb-maintenance-mode.

Crea il file principale: dentro questa cartella, crea operweb-maintenance-mode.php.

L’intestazione (Header): apri il file e inserisci l’header PHP. Questa dice a WordPress tutto sul tuo plugin:

<?php
/**
 * Plugin Name:       OperWEB Maintenance Mode
 * Description:       Attiva una pagina di manutenzione personalizzata con opzioni.
 * Version:           2.3.3
 * Author:            Fabrizio Ortis | OperWEB
 * Author URI:        https://www.operweb.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       operweb-maintenance-mode
 * Domain Path:       /languages
 */

// Impedisci l'accesso diretto
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
  • Plugin Name, Description, Author, ecc.: informazioni mostrate nella bacheca.
  • License: fondamentale per la distribuzione (GPLv2 or later è lo standard).
  • Text Domain & Domain Path: cruciali per le traduzioni (ne parleremo dopo).

2. La Logica Principale: Mostrare la Pagina

Vogliamo che il plugin controlli ogni caricamento di pagina sul frontend e, se necessario, mostri la pagina di manutenzione. Usiamo l’hook template_redirect:

function owm_maintenance_mode_check() {
    $options = get_option( 'owm_options' );

    // 1. Manutenzione attiva dalle impostazioni?
    if ( empty( $options['enable'] ) || $options['enable'] != 1 ) {
        return;
    }

    // 2. L'utente è un admin?
    if ( current_user_can( 'manage_options' ) ) {
        return;
    }

    // 3. Per tutti gli altri: mostra la pagina di manutenzione
    $maintenance_file = plugin_dir_path( __FILE__ ) . 'maintenance.php';
    if ( file_exists( $maintenance_file ) ) {
        if ( ! headers_sent() ) {
            header( 'HTTP/1.1 503 Service Unavailable', true, 503 );
            header( 'Content-Type: text/html; charset=utf-8' );
            header( 'Retry-After: 3600' ); // Riprova tra 1 ora
        }
        include( $maintenance_file );
        die();
    }
}
add_action( 'template_redirect', 'owm_maintenance_mode_check' );

L’header 503 Service Unavailable è importante per la SEO: dice ai motori di ricerca che il sito è temporaneamente non disponibile. Avremo bisogno anche di un file maintenance.php nella stessa cartella, che conterrà l’HTML e il CSS della pagina.

3. Creare una Pagina di Impostazioni (Settings API)

Per permettere all’utente di configurare il plugin, usiamo la Settings API di WordPress.

  • Aggiungere la pagina: con add_options_page() aggiungiamo una voce sotto “Impostazioni” nel menu admin.
  • Registrare le impostazioni: con register_setting() diciamo a WordPress quale opzione salvare nel database (es. owm_options) e quale funzione usare per “pulire” i dati (owm_sanitize_options).
  • Definire sezioni e campi: con add_settings_section() e add_settings_field() definiamo la struttura della pagina e i singoli campi (checkbox, uploader logo, editor testo, color picker).
  • Funzioni callback: ogni campo ha bisogno di una funzione PHP che stampa il suo HTML (es. owm_field_enable_cb() per la checkbox).
  • Render pagina: una funzione (owm_options_page_html()) stampa l’HTML base della pagina con settings_fields() e do_settings_sections().

Per campi avanzati come l’uploader media e il color picker, dobbiamo accodare gli script e gli stili necessari con wp_enqueue_media(), wp_enqueue_style('wp-color-picker') e wp_enqueue_script().

4. Internazionalizzazione (i18n): Preparare per la Traduzione

Per rendere il plugin multilingua, ogni stringa visibile all’utente deve essere “avvolta” in una funzione di traduzione:

  • __( 'Stringa', 'text-domain' ) — restituisce la stringa tradotta.
  • _e( 'Stringa', 'text-domain' ) — stampa direttamente la stringa tradotta.
  • esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e() — come sopra, ma con escape automatico per la sicurezza.
  • printf() / sprintf() — per stringhe con variabili, accompagnate da commenti /* translators: ... */.

Esempio pratico:

// Prima:
echo '<h1>Sito in Manutenzione</h1>';

// Dopo:
echo '<h1>' . esc_html__( 'Sito in Manutenzione', 'operweb-maintenance-mode' ) . '</h1>';

5. Tradurre con Loco Translate

Con il codice pronto, usiamo Loco Translate per creare i file di lingua.

Installa e attiva il plugin Loco Translate sul tuo sito di test, poi vai su Loco Translate > Plugins e trova “OperWEB Maintenance Mode”.

Crea il modello .pot: clicca “Crea modello” e salvalo in languages/operweb-maintenance-mode.pot. Questo file contiene l’elenco di tutte le stringhe originali.

Crea la traduzione Italiana (it_IT):

  1. Clicca “Nuova lingua” e scegli “Italiano (Italia)”.
  2. Importante: scegli la posizione “File dell’autore” (salverà in wp-content/plugins/operweb-maintenance-mode/languages/).
  3. Traduci ogni stringa e clicca “Salva”. Verranno creati it_IT.po (modificabile) e it_IT.mo (compilato).

Crea la traduzione Inglese (en_US): stesso procedimento, scegliendo “Inglese (Stati Uniti)“.

6. Recuperare i File di Traduzione

I file .pot, .po e .mo vengono creati da Loco Translate direttamente nella cartella /wp-content/plugins/operweb-maintenance-mode/languages/.

Se non hai lavorato in locale, scaricali via FTP/SFTP o dal File Manager del tuo hosting e includili nella cartella /languages prima di distribuire il plugin.

7. Controllo di Conformità con “Plugin Check”

Prima di pubblicare su WordPress.org, è fondamentale verificare che il plugin rispetti gli standard.

Installa e attiva Plugin Check, poi vai su Strumenti > Plugin Check, seleziona il tuo plugin e clicca “Check it!”.

Il plugin riporterà:

  • Errori: vanno corretti obbligatoriamente (problemi di sicurezza, funzioni deprecate, output non escapato).
  • Avvisi: fortemente consigliato correggerli (standard di codice, commenti mancanti per i traduttori).

Correggi tutto ciò che riporta, seguendo i link “Approfondisci” per capire il problema. Riesegui il check finché non ci sono più errori critici.

Prossimi Passi: Verso la Pubblicazione

Con un plugin funzionante, traducibile e controllato, rimangono tre passi:

  1. Creare un readme.txt: è la “vetrina” del plugin su WordPress.org. Deve essere in inglese e descrivere il plugin, l’installazione, le FAQ, ecc. (leggi le linee guida).
  2. Preparare lo ZIP: la cartella deve contenere tutti i file (PHP, JS, CSS, assets, cartella languages con .pot/.po/.mo, e readme.txt).
  3. Inviare per la revisione: carica il .zip tramite la pagina Add Your Plugin su WordPress.org e attendi la revisione manuale.

Il Plugin su GitHub

Il codice completo è disponibile su GitHub. Nel frattempo il plugin è stato aggiornato e include ora un sistema di auto-aggiornamento direttamente dalla bacheca di WordPress — senza bisogno di passare per WordPress.org:

👉 github.com/fabrizioortis/operweb-maintenance-mode

Conclusione

Creare un plugin per WordPress, anche semplice, tocca molti aspetti dello sviluppo: PHP, API di WordPress, sicurezza, internazionalizzazione. Seguendo questi passaggi e usando strumenti come Loco Translate e Plugin Check, puoi trasformare la tua idea in un plugin robusto e pronto per essere condiviso con la community.