Documentazione · Documentazione tecnica

Internazionalizzazione e Poedit

Questo documento spiega come il plugin ADP Car Market Hub gestisce le traduzioni, dove risiedono i file di lingua e come aggiornare o aggiungere traduzioni utilizzando Poedit (o qualsiasi editor gettext compatibile).

Quando utilizzare questo documento

Leggi questo documento se hai la necessità di:

Tradurre il plugin in una nuova lingua.
Aggiornare una traduzione esistente dopo l'aggiornamento del plugin.
Verificare quali localizzazioni sono incluse e come vengono caricate.
Diagnosticare stringhe che appaiono non tradotte nell'amministrazione o nel front-end.

Panoramica

Il plugin utilizza i meccanismi standard di internazionalizzazione (i18n) di WordPress:

Tutte le stringhe traducibili sono racchiuse in funzioni gettext (__(), _e(), _n(), _x(), ecc.) utilizzando il text domain adp-car-market-hub.
Le traduzioni vengono caricate dalla cartella languages/ del plugin tramite load_plugin_textdomain() su plugins_loaded con priorità 1, prima che venga renderizzata qualsiasi stringa visibile all'utente.
Un modello POT (adp-car-market-hub.pot) viene fornito con il plugin e può essere aperto o rigenerato con Poedit o WP-CLI.

Il text domain corrisponde allo slug della cartella del plugin (adp-car-market-hub), in modo che le traduzioni provenienti da catene di strumenti in stile translate.wordpress.org vengano rilevate automaticamente quando distribuite nelle posizioni standard.

File in `languages/`

La cartella languages/ inclusa contiene:

adp-car-market-hub.pot — modello di traduzione generato da i18n make-pot di WP-CLI (visibile nell'intestazione del file POT).
adp-car-market-hub-de_DE.po — Tedesco (Germania).
adp-car-market-hub-de_DE_formal.po / adp-car-market-hub-de_DE_formal.mo — Tedesco (formale).
adp-car-market-hub-de_AT.po — Tedesco (Austria).
adp-car-market-hub-de_CH.po — Tedesco (Svizzera).
adp-car-market-hub-fr_FR.po — Francese (Francia).
adp-car-market-hub-it_IT.po — Italiano (Italia).

Verifica l'elenco esatto dei file .po e .mo nella versione corrente del plugin prima di pubblicare i testi visibili ai clienti. WordPress carica il file .mo corrispondente alla localizzazione attiva del sito; i soli file .po non sono sufficienti in fase di runtime.

Requisiti o prerequisiti

Un editor gettext — Poedit è lo strumento GUI consigliato. La versione gratuita è sufficiente.
Opzionale: WP-CLI con il comando i18n, utilizzato per rigenerare il file POT dai sorgenti.
Accesso in scrittura alla cartella languages/ del plugin (o a una posizione di override, vedi sotto).

Istruzioni passo dopo passo

Tradurre in una nuova localizzazione

Apri Poedit e seleziona File → Nuovo da file POT/PO.
Seleziona languages/adp-car-market-hub.pot.
Scegli la localizzazione di destinazione. Salva il file come adp-car-market-hub-<locale>.po all'interno della stessa cartella languages/, dove <locale> è il codice di localizzazione di WordPress (ad esempio es_ES, nl_NL).
Traduci le stringhe nell'editor.
Salva. Poedit scrive automaticamente un file .mo corrispondente accanto al file .po.
Imposta la lingua del sito di WordPress sulla tua nuova localizzazione e ricarica le pagine dell'amministrazione e del front-end per verificare le traduzioni.

Aggiornare una traduzione esistente dopo un aggiornamento del plugin

Apri il file .po esistente in Poedit.
Scegli Catalogo → Aggiorna da file POT e seleziona il nuovo adp-car-market-hub.pot.
Traduci le stringhe nuove o modificate (Poedit le evidenzia come non tradotte o fuzzy).
Salva. Il file .mo viene rigenerato automaticamente.

Rigenerare il modello POT dai sorgenti (opzionale)

Se gestisci il codice sorgente del plugin e hai la necessità di aggiornare autonomamente il file POT, puoi farlo con WP-CLI:

wp i18n make-pot . languages/adp-car-market-hub.pot --domain=adp-car-market-hub

Esegui questo comando dalla directory principale del plugin. L'intestazione del file registra la versione di WP-CLI che lo ha prodotto.

Utilizzare le traduzioni al di fuori della cartella del plugin

WordPress cerca le traduzioni anche in wp-content/languages/plugins/adp-car-market-hub-<locale>.mo. Inserisci un file .mo personalizzato in quella posizione se desideri che le traduzioni sopravvivano agli aggiornamenti del plugin che sovrascrivono languages/.

Note operative

Il text domain viene caricato con priorità plugins_loaded su 1, che è intenzionalmente precedente all'esecuzione del callback principale init() del plugin alla priorità predefinita. Ciò garantisce che ogni stringa traducibile registrata successivamente abbia già accesso al file .mo caricato.
Salva sempre nuovamente il file .po con Poedit (o compila il file .mo con msgfmt) dopo la modifica — WordPress legge il file binario .mo a runtime, non il file testuale .po.
I codici di localizzazione fanno distinzione tra maiuscole e minuscole sui file system sensibili alle maiuscole/minuscole. Utilizza l'identificatore esatto di localizzazione di WordPress.
Gli aggiornamenti delle traduzioni non devono modificare alcun file sorgente; questa attività di documentazione li esclude esplicitamente.
Alcune stringhe (ad esempio gli identificatori dei modelli di provider nell'AI Assistant o le etichette delle opzioni tecniche) vengono intenzionalmente mantenute in inglese. Traduci i testi visibili all'utente e lascia inalterati gli identificatori.

Risoluzione dei problemi

Una stringa appare ancora in inglese — verifica che esista un file .mo per la localizzazione attiva in languages/ (o in wp-content/languages/plugins/), che il file corrisponda al text domain del plugin (adp-car-market-hub) e che la lingua del sito di WordPress sia impostata correttamente.
Una nuova traduzione non viene caricata finché non si svuota la cache — alcuni plugin di object-cache memorizzano in cache le traduzioni. Svuota la cache degli oggetti di WordPress dopo aver distribuito i nuovi file .mo.
Poedit mostra molte stringhe fuzzy dopo un aggiornamento — questo è normale quando il testo sorgente cambia. Esamina ogni voce fuzzy, correggi la traduzione e deselezionala come fuzzy.
Le traduzioni personalizzate vengono sovrascritte dagli aggiornamenti del plugin — memorizza le traduzioni personalizzate in wp-content/languages/plugins/ invece che nella cartella languages/ del plugin.