Documentazione · Guida all'integrazione

Guida alla traduzione e a Poedit

Questo documento spiega come il plugin ADP Car Market Hub gestisce i siti multilingua WordPress, quali file di traduzione sono forniti con il plugin e come tradurre o aggiornare le stringhe del plugin utilizzando Poedit o strumenti equivalenti.

Quando utilizzare questo documento

Utilizzare questo documento se si desidera:

Configurare il plugin su un sito la cui lingua WordPress non è l'inglese e si vuole verificare che le traduzioni vengano caricate.
Un concessionario o un'agenzia che aggiunge o corregge le traduzioni per una lingua già inclusa nel plugin.
Uno sviluppatore che contribuisce con un nuovo file di lingua per una localizzazione non ancora inclusa nel plugin.
Risolvere i problemi relativi al testo del plugin che appare in inglese quando la lingua del sito è impostata su un'altra localizzazione.

Il pubblico di riferimento è un amministratore WordPress o uno sviluppatore che ha familiarità con il flusso di lavoro di internazionalizzazione di WordPress e con l'uso di base della riga di comando.

Panoramica

Il plugin utilizza il meccanismo di localizzazione standard di WordPress. Tutte le stringhe visibili all'utente nel codice PHP del plugin sono racchiuse nelle funzioni di traduzione di WordPress (__(), _e(), esc_html__() e simili) con il text domain adp-car-market-hub. WordPress carica il file di traduzione corrispondente dalla cartella languages/ del plugin quando la lingua del sito è impostata in Impostazioni → Generale → Lingua del sito.

I seguenti file di lingua sono inclusi nel plugin al momento della stesura di questo documento:

Codice locale	Lingua
`de_AT`	Tedesco (Austria)
`de_CH`	Tedesco (Svizzera)
`de_DE`	Tedesco (Germania)
`de_DE_formal`	Tedesco (Germania, formale)
`fr_FR`	Francese (Francia)
`it_IT`	Italiano (Italia)
`es_ES`	Spagnolo (Spagna)
`nl_NL`	Olandese (Paesi Bassi)

Verificare l'elenco corrente controllando la directory languages/ all'interno della cartella del plugin (wp-content/plugins/adp-car-market-hub/languages/). Ogni localizzazione ha un file sorgente .po (modificabile dall'utente) e, dove è presente un file compilato .mo, quest'ultimo è ciò che WordPress carica effettivamente a runtime.

Se il sito utilizza una localizzazione non presente nell'elenco precedente, il plugin mostrerà tutte le stringhe nella lingua di fallback, che è l'inglese.

Requisiti di sistema

Accesso amministratore WordPress.
Per la modifica delle traduzioni: Poedit (https://poedit.net/) o un editor di file .po / .mo equivalente, oppure il plugin WordPress Loco Translate (https://wordpress.org/plugins/loco-translate/).
Per generare un nuovo file POT: WP-CLI versione 2.6 o successiva, oppure lo script make-pot.sh in bin/make-pot.sh.
Per compilare i file .mo dalla riga di comando: l'utility GNU gettext msgfmt, o il comando wp i18n make-mo di WP-CLI.

Come il plugin carica le traduzioni

Il plugin chiama load_plugin_textdomain() sull'azione plugins_loaded con priorità 1. Ciò significa che il file di traduzione per la lingua corrente del sito viene caricato prima che qualsiasi altro codice del plugin venga eseguito alla priorità predefinita, in modo che tutte le stringhe dell'amministratore e del frontend siano disponibili per la traduzione dal momento in cui il plugin viene inizializzato.

WordPress risolve il file di lingua nel seguente ordine:

wp-content/languages/plugins/adp-car-market-hub-{locale}.mo (file di traduzione installati da WordPress stesso o da uno strumento di gestione delle traduzioni).
wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-{locale}.mo (file inclusi nel plugin).

I file in wp-content/languages/plugins/ hanno la priorità. Se si aggiorna una traduzione inclusa utilizzando un plugin come Loco Translate, il file aggiornato viene solitamente memorizzato nel primo percorso, il che protegge le modifiche dalla sovrascrittura quando il plugin viene aggiornato.

Istruzioni passo dopo passo

Utilizzare una traduzione inclusa esistente

In WordPress, aprire Impostazioni → Generale.
Impostare Lingua del sito sulla localizzazione desiderata (ad esempio Tedesco (Svizzera) per de_CH).
Salvare le impostazioni.
Navigare su qualsiasi pagina di amministrazione del plugin o visitare l'archivio dei veicoli sul frontend. Le stringhe del plugin (etichette, pulsanti, messaggi di errore) dovrebbero apparire nella lingua selezionata.
Se le stringhe appaiono ancora in inglese, vedere la sezione Risoluzione dei problemi di seguito.

Modificare o correggere una traduzione esistente con Poedit

Scaricare e installare Poedit da https://poedit.net/.
Individuare il file .po per la localizzazione che si desidera modificare, all'interno della directory languages/ del plugin. Ad esempio: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-de_CH.po.
Aprire il file .po in Poedit.
Trovare la stringa che si desidera modificare nell'elenco delle stringhe. La colonna Testo sorgente mostra l'originale in inglese e la colonna Traduzione mostra il valore attualmente tradotto. Fare clic su una riga per modificare la traduzione nel pannello di modifica sottostante.
Salvare il file. Poedit compila automaticamente il file .mo corrispondente nella stessa directory.
Consigliato: Copiare i file .po e .mo aggiornati in wp-content/languages/plugins/ in modo che gli aggiornamenti del plugin non li sovrascrivano: - wp-content/languages/plugins/adp-car-market-hub-de_CH.po - wp-content/languages/plugins/adp-car-market-hub-de_CH.mo
Svuotare qualsiasi cache di WordPress che potrebbe mostrare contenuti obsoleti, quindi verificare la modifica sulla pagina del plugin pertinente.

Modificare una traduzione esistente con Loco Translate

Installare e attivare il plugin Loco Translate dalla directory dei plugin di WordPress.
In WordPress, navigare su Loco Translate → Plugins.
Trovare ADP Car Market Hub nell'elenco e fare clic su di esso.
Selezionare la lingua che si desidera modificare.
Modificare le stringhe nell'editor di Loco Translate e salvare. Loco Translate compila automaticamente il file .mo e memorizza le modifiche in wp-content/languages/plugins/, proteggendole dagli aggiornamenti del plugin.

Creare una traduzione per una nuova lingua

Aprire il file modello POT: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub.pot. Il file POT contiene tutte le stringhe traducibili nel plugin senza alcuna traduzione.
In Poedit, scegliere File → Nuovo da file POT/PO, selezionare il file .pot e scegliere la lingua di destinazione.
Tradurre le stringhe.
Salvare come adp-car-market-hub-{locale}.po e compilare in adp-car-market-hub-{locale}.mo. Utilizzare l'esatto codice di localizzazione che WordPress utilizza per quella lingua (ad esempio fr_CH per il francese svizzero). Verificare il codice in Impostazioni → Generale → Lingua del sito.
Posizionare entrambi i file in wp-content/languages/plugins/ in modo che non vengano sovrascritti dagli aggiornamenti del plugin.
Impostare la lingua del sito e verificare che la nuova traduzione venga caricata correttamente.

Aggiornare i file di traduzione dopo un aggiornamento del plugin

Quando il plugin viene aggiornato, potrebbero essere aggiunte nuove stringhe. I file .po inclusi vengono aggiornati dai manutentori del plugin, ma le traduzioni personalizzate memorizzate al di fuori della directory del plugin non vengono aggiornate automaticamente.

Per aggiornare il proprio file di traduzione personalizzato:

Scaricare il file POT aggiornato dalla directory languages/ del plugin.
In Poedit, aprire il proprio file .po personalizzato, quindi scegliere Traduzione → Aggiorna da file POT e selezionare il nuovo file .pot. Poedit unirà le nuove stringhe nel file, contrassegnando le stringhe non tradotte per l'attenzione.
Tradurre le nuove stringhe.
Salvare e compilare.

Se si utilizza WP-CLI, aggiornare un file .po con msgmerge:

msgmerge --update languages/adp-car-market-hub-de_CH.po languages/adp-car-market-hub.pot

Compilare il file aggiornato:

msgfmt -o languages/adp-car-market-hub-de_CH.mo languages/adp-car-market-hub-de_CH.po

Oppure compilare tutti i file .po contemporaneamente con WP-CLI:

wp i18n make-mo languages/

Riferimento di configurazione

Non esiste una pagina di impostazioni di traduzione dedicata nell'amministrazione del plugin. La traduzione è gestita interamente tramite l'impostazione della lingua del sito di WordPress e il sistema di localizzazione standard di WordPress.

Cosa configurare	Dove
Lingua del sito che determina quale file di traduzione viene caricato	Impostazioni → Generale → Lingua del sito
Modificare le traduzioni incluse senza perdere le modifiche all'aggiornamento	Utilizzare Loco Translate, che memorizza le modifiche in `wp-content/languages/plugins/`
Generare un file POT aggiornato dal sorgente PHP del plugin	Eseguire `./bin/make-pot.sh` o `wp i18n make-pot` (vedere il file README i18n)

Note operative

Text domain. Ogni stringa traducibile nel plugin utilizza il text domain adp-car-market-hub. Questo text domain è dichiarato nell'intestazione del plugin e deve corrispondere al prefisso del nome del file dei file di traduzione (ad esempio adp-car-market-hub-de_DE.mo). Una mancata corrispondenza tra il text domain e il nome del file è il motivo più comune per cui le stringhe non vengono tradotte.
I file .mo compilati sono richiesti a runtime. WordPress legge i file .mo compilati, non i file sorgente .po leggibili dall'uomo. Compilare sempre un file .po nuovo o aggiornato in .mo prima di aspettarsi di vedere le modifiche nel browser.
Tedesco formale vs. informale. La localizzazione de_DE_formal fornisce uno stile di allocuzione formale (Sie) per il tedesco. Scegliere questa localizzazione sui siti in cui è previsto un linguaggio formale.
Le stringhe del frontend e dell'amministrazione sono entrambe coperte. Il text domain del plugin include stringhe sia per le pagine di amministrazione (impostazioni, stato dell'importazione, log) sia per l'output del frontend (etichette dei veicoli, etichette dei filtri, messaggi del modulo di contatto, calcolatore finanziario). Entrambi i set di stringhe si trovano nello stesso file .po / .mo.
Pacchetti di lingua di WordPress. Se il sistema di pacchetti di lingua di WordPress ha una traduzione della community per adp-car-market-hub per la localizzazione selezionata, WordPress potrebbe proporre di scaricarla automaticamente. I file ottenuti in questo modo sono memorizzati in wp-content/languages/plugins/ e vengono aggiornati insieme al core di WordPress. Verificare che la traduzione della community sia completa prima di fare affidamento su di essa per la produzione.
Caching. Se le traduzioni non appaiono dopo una modifica, svuotare qualsiasi cache degli oggetti, cache di pagina o cache opcode di WordPress. Il bytecode memorizzato nella cache dei vecchi file .mo può sopravvivere fino a quando la cache non viene svuotata.
File di documentazione. La documentazione in docs/ è scritta solo in inglese. Non ci sono file di documentazione tradotti. La traduzione delle stringhe PHP del plugin (come descritto in questa guida) e la traduzione della documentazione sono questioni separate.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa controllare
Le stringhe del plugin appaiono in inglese anche se la lingua del sito è impostata correttamente.	Il file `.mo` per la localizzazione selezionata è mancante o non compilato.	Controllare che entrambi i file `.po` e `.mo` esistano in `wp-content/plugins/adp-car-market-hub/languages/` o `wp-content/languages/plugins/`. Il file `.mo` deve essere presente.
Poedit salva il file `.po` ma le stringhe non cambiano in WordPress.	Poedit ha compilato il file `.mo` accanto al file `.po`, ma WordPress sta caricando un file `.mo` da un percorso diverso.	Controllare sia la directory `languages/` del plugin sia `wp-content/languages/plugins/`. Il file in `wp-content/languages/plugins/` ha la priorità.
Alcune stringhe vengono tradotte ma altre rimangono in inglese.	Tali stringhe sono state aggiunte in una versione successiva all'ultimo aggiornamento della traduzione.	Aggiornare il file `.po` rispetto al file POT corrente come descritto sopra, tradurre le nuove stringhe e ricompilare.
Dopo un aggiornamento del plugin, le traduzioni tornano in inglese.	L'aggiornamento del plugin ha sovrascritto il file `.mo` nella directory `languages/` del plugin stesso.	Spostare i file di traduzione personalizzati in `wp-content/languages/plugins/`. I file in questa posizione non vengono toccati dagli aggiornamenti del plugin.
L'impostazione della lingua del sito mostra che non esiste alcun file `.mo` compilato per una particolare localizzazione.	È incluso solo un file sorgente `.po`, senza un file `.mo` compilato.	Compilare il file `.po` con `msgfmt` o con Poedit, quindi posizionare il file `.mo` risultante nella stessa directory.
Loco Translate mostra avvisi di "nessun riferimento" su alcune stringhe.	La stringa esiste nella traduzione ma non è più presente nel sorgente del plugin.	Queste stringhe orfane sono innocue; non influiscono sul comportamento a runtime. È possibile eliminarle in Loco Translate per mantenere pulito il file.