Internazionalizzazione per gli sviluppatori

Questo documento descrive come il plugin ADP Car Market Hub gestisce l'internazionalizzazione (i18n) per traduttori e collaboratori. Copre il text domain, il meccanismo di caricamento, i file di traduzione distribuiti con il plugin, gli strumenti utilizzati per generare il file POT e le convenzioni da seguire quando si aggiungono nuove stringhe traducibili.

Quando usare questo documento

Leggi questo documento quando hai bisogno di:

• Aggiungere una nuova stringa traducibile al codice PHP, JavaScript o ai template.
• Rigenerare il file POT dopo aver aggiunto delle stringhe.
• Fornire una nuova traduzione in un'altra lingua per il plugin.
• Capire perché una particolare stringa dell'amministrazione o del front-end è o non è tradotta.

Per le note rivolte ai traduttori, consulta il file README-i18n.md del repository.

Panoramica

Il plugin utilizza le API i18n standard di WordPress (__(), _e(), _n(), _x(), esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e(), …) con un singolo text domain.

• Text domain: adp-car-market-hub.
• Domain path: /languages (dichiarato nell'intestazione del plugin).
• Loader: load_plugin_textdomain( 'adp-car-market-hub', false, '/languages' ) viene chiamato da una funzione agganciata a plugins_loaded con priorità 1, in modo che le traduzioni vengano caricate prima dell'esecuzione del lavoro di init del plugin stesso.

Le stringhe JavaScript utilizzate dagli script inclusi nel plugin sono pre-tradotte in PHP e passate a JavaScript tramite wp_localize_script(). Al momento il plugin non si affida a wp_set_script_translations() e al flusso di lavoro di traduzione JSON associato.

Requisiti o prerequisiti

• File sorgente scritti utilizzando le funzioni i18n di WordPress con 'adp-car-market-hub' come text domain.
• WP-CLI installato quando si rigenera il file POT (lo script di supporto utilizza wp i18n make-pot).
• Un editor compatibile con POEdit (o qualsiasi strumento che supporti GNU gettext) per modificare i file .po.

File di traduzione distribuiti con il plugin

Tutti i file di traduzione si trovano in /languages e seguono la convenzione di denominazione standard di WordPress.

Ogni localizzazione distribuita include sia un sorgente .po sia un file compilato .mo. L'elenco sopra riflette i file attualmente presenti; verifica l'insieme più recente nella cartella /languages prima della pubblicazione.

Strumenti

Rigenerare il file POT

Uno script di supporto è fornito nella directory bin/ del repository. Chiama il comando i18n make-pot di WP-CLI ed esclude le cartelle che non devono essere scansionate (.git, node_modules, vendor, tests, bin).

Per eseguirlo:

1. Assicurati che WP-CLI sia installato e disponibile su PATH.
2. Dalla root del repository, esegui lo script.
3. Il file .pot aggiornato viene scritto in languages/adp-car-market-hub.pot.

Compilare i file .mo

Dopo aver modificato un file .po, compila un file .mo corrispondente con il tuo editor (il comando "Salva" di POEdit produce automaticamente entrambi i file) o con msgfmt da gettext.

Istruzioni passo dopo passo

Aggiungere una stringa traducibile in PHP

1. Avvolgi la stringa con la funzione i18n appropriata di WordPress e passa 'adp-car-market-hub' come text domain. Ad esempio, __( 'Lead saved.', 'adp-car-market-hub' ) o esc_html__( 'Vehicles', 'adp-car-market-hub' ).
2. Laddove la stringa sia concatenata con codice HTML, preferisci le varianti esc_*__ e esc_*_e per combinare l'escape e la traduzione in un'unica chiamata.
3. Per la gestione dei plurali, usa _n() o _nx(). Per la disambiguazione del contesto, usa _x().
4. Rigenera il file POT (vedi sopra) in modo che i traduttori possano rilevare la nuova stringa.

Aggiungere una stringa traducibile utilizzata in JavaScript

1. Traduci prima la stringa in PHP (__( 'Sending…', 'adp-car-market-hub' )).
2. Passala a JavaScript tramite l'array wp_localize_script() utilizzato dall'handle pertinente. Vedi Frontend Assets e Admin Assets per gli oggetti localizzati già in uso (ad esempio AS24CI, as24ciCompare, AS24CI_LEADS, AS24CI_BATCH).
3. Leggi il valore dalla corrispondente variabile globale nel codice JavaScript.

Fornire una nuova traduzione

1. Copia languages/adp-car-market-hub.pot in languages/adp-car-market-hub-<locale>.po utilizzando il codice locale di WordPress (ad esempio es_ES).
2. Traduci le stringhe.
3. Compila il file .mo insieme al file .po.
4. Apri una pull request con entrambi i file.

Note operative

• Singolo text domain. Ogni stringa traducibile nel plugin utilizza 'adp-car-market-hub'. Non introdurre ulteriori text domain.
• Mantieni aggiornato il file POT. Quando un collaboratore aggiunge o rimuove stringhe, rigenera il file POT nella stessa modifica, in modo che i file di traduzione possano essere uniti in modo pulito.
• Stringhe JavaScript. Poiché le stringhe JS vengono tradotte tramite wp_localize_script(), appaiono nel file POT solo quando è presente la corrispondente chiamata __() lato PHP. Traduci sempre le stringhe JS prima in PHP.
• Formattazione sensibile alla localizzazione. La formattazione dei numeri e delle valute è gestita dagli helper di localizzazione del plugin. Usa gli helper esposti dal plugin anziché reimplementare la logica di localizzazione nel tuo codice.
• Piattaforma di traduzione WordPress. Il plugin può essere tradotto al di fuori del repository attraverso qualsiasi flusso di lavoro gettext standard. Non è richiesto alcun servizio di traduzione esterno specifico.

Risoluzione dei problemi

• Una stringa non viene tradotta nel front-end. Verifica che la stringa sia avvolta in una funzione i18n con il text domain corretto. Verifica che la lingua sia installata in WordPress (Impostazioni → Generale → Lingua del sito) e che esista un file .mo per quella localizzazione in /languages.
• Le stringhe appena aggiunte non appaiono nel file POT. Esegui nuovamente lo script di supporto POT. Verifica che il tuo file non si trovi in una delle cartelle escluse.
• Il testo lato JS è ancora in inglese dopo la traduzione in PHP. Verifica che la stringa venga passata tramite wp_localize_script() per l'handle pertinente. Il plugin non rileva automaticamente le stringhe JS non tradotte.
• I plurali mostrano sempre la forma singolare. Usa _n() (o _nx() per il contesto) invece di __() per qualsiasi stringa che varia in base a un conteggio.
• Verifica il comportamento nella versione corrente del plugin prima di pubblicare un'integrazione personalizzata. I nomi degli oggetti JavaScript localizzati possono evolvere tra i rilasci.

Documenti correlati

• Frontend Assets
• Admin Assets
• Coding Standards
• Repository Structure
• Contribution Guidelines