Negozia la lingua solo in / e fai in modo che gli URL espliciti come /en/ e /fr/ mostrino sempre la lingua indicata. Questa guida mostra a chi pubblica contenuti dal Mac come specificare questo comportamento, mantenere individuabili i link ai documenti e verificare il risultato.

L’esempio pratico è una raccolta pubblica fittizia di documenti, con versioni in inglese e francese di una breve guida alla disposizione delle forme. La sua pagina principale è una pagina di selezione della lingua, il cui testo introduttivo può adattarsi alla richiesta. Tutti gli indirizzi degli esempi descrivono una configurazione proposta; non affermano che esistano pagine attualmente ospitate a quegli indirizzi.

Definire il comportamento degli URL prima di modificare le impostazioni della lingua

Inizia con un semplice accordo sul routing. In questo esempio, la pagina principale aiuta i lettori a scegliere una lingua, mentre i due percorsi espliciti contengono il documento tradotto completo. Google consiglia URL distinti per le versioni linguistiche e sconsiglia di reindirizzare automaticamente i lettori tra queste versioni in base a una lingua presunta. I link visibili consentono ai lettori di scegliere autonomamente. Gestire siti multiregionali e multilingue.

Percorso richiesto Risposta prevista Effetto della preferenza linguistica
/ Selettore della lingua con una breve introduzione Può modificare l’introduzione e il link suggerito
/en/ Documento completo in inglese La lingua del documento non cambia
/fr/ Documento completo in francese La lingua del documento non cambia
Percorso non pubblicato Risposta di pagina non trovata Non deve diventare silenziosamente un altro documento

Considera questa tabella come specifica di implementazione. Applica la selezione della lingua solo dopo aver verificato se la richiesta punta alla pagina principale. Una regola generale applicata prima di ogni richiesta di pagina può sovrascrivere una scelta esplicita e violare l’accordo.

Per esempio, chi visita /fr/ dovrebbe comunque ricevere il documento in francese, anche se la richiesta preferisce l’inglese. La preferenza per l’inglese è utile nel punto d’ingresso in cui la scelta non è ancora stata fatta; altrove, il percorso esplicito indica già la decisione. Questa precedenza è la raccomandazione progettuale adottata in tutto l’articolo.

Mantieni visibili su ogni pagina i link a entrambe le lingue. Nella pagina principale, suggerire una lingua può facilitare la prima scelta senza nascondere l’altra opzione. Nei documenti completi, il selettore dovrebbe rimandare direttamente al documento equivalente.

Scegliere una politica prevedibile per la lingua della pagina principale

Accept-Language esprime le lingue preferite per la risposta, con pesi di qualità come fr;q=0.9,en;q=0.5. Non obbliga un server a fornire tutte le lingue richieste. Un valore di qualità pari a zero indica una lingua non accettabile. Content-Language descrive il pubblico a cui è destinata la rappresentazione restituita; non seleziona un percorso. RFC 9110: semantica HTTP, sezioni 8.5, 12.4.2 e 12.5.4.

Prima di configurare qualsiasi cosa, annota l’insieme delle lingue supportate e la lingua di ripiego. In questo esempio, usa introduzioni in inglese e francese; se la richiesta non fornisce una corrispondenza utilizzabile, mostra un’introduzione in inglese e entrambe le opzioni linguistiche. Questa lingua di ripiego è una scelta editoriale illustrativa, non un requisito HTTP.

Usa un’implementazione di corrispondenza linguistica con una politica esplicita. RFC 4647 distingue il filtraggio dalla ricerca: la ricerca seleziona un singolo risultato, considera le lingue richieste in ordine di priorità e rimuove progressivamente i sottotag per trovare una corrispondenza. Richiede inoltre che le applicazioni che usano la ricerca definiscano un comportamento predefinito. Perciò, con la ricerca, una richiesta di fr-CA può raggiungere un’introduzione generica supportata in fr. RFC 4647: corrispondenza dei tag linguistici, sezioni 3.4–3.4.1.

Non selezionare una lingua cercando nell’header la prima occorrenza di fr o en. Questa scorciatoia ignora i pesi e le esclusioni. Il livello di corrispondenza dovrebbe analizzare le preferenze, tenere conto delle esclusioni con peso zero e poi applicare la lingua di ripiego documentata.

Preferenza della richiesta alla pagina principale Risultato previsto in questo esempio
Header assente Introduzione in inglese con entrambe le opzioni
fr Introduzione in francese con entrambe le opzioni
fr-CA,fr;q=0.9,en;q=0.5 Introduzione in francese
en;q=0.9,fr;q=0.2 Introduzione in inglese
de Selettore di ripiego
fr;q=0,en;q=1 Introduzione in inglese; il francese non viene selezionato
*;q=0 Gestione delle lingue non corrispondenti definita esplicitamente

L’ultima riga richiede una decisione deliberata. Per questo selettore, specifica che una richiesta che esclude tutte le lingue riceve il selettore di ripiego perché l’applicazione non rispetta tale preferenza, senza sostenere che l’inglese corrisponda alla richiesta. Se invece è necessaria una negoziazione rigorosa, definisci e verifica il comportamento corrispondente per le risposte non accettabili. In entrambi i casi, evita di trattare accidentalmente lo zero come una normale preferenza di bassa priorità.

Mantenere coerenti la lingua del documento, i link e le annotazioni per i motori di ricerca

Per ogni documento HTML, imposta l’attributo lang del documento sulla sua lingua principale effettiva: en per la pagina in inglese e fr per quella in francese. WHATWG definisce lang come la lingua principale dei contenuti e degli attributi contenenti testo di un elemento; se manca, viene ereditata dall’elemento genitore. Il solo prefisso della lingua non costituisce questa dichiarazione. Standard HTML: gli attributi lang e xml:lang.

Controlla i link di navigazione oltre al testo della pagina. Gli URL relativi vengono risolti rispetto a un URL di base secondo lo standard URL WHATWG. Per esempio, se la base del documento non è stata modificata, fr/ da https://example.com/en/ viene risolto in https://example.com/en/fr/; /fr/ viene risolto nel percorso francese dell’origine. Usa il percorso assoluto previsto per il selettore visibile. Standard URL: scrittura e analisi degli URL.

Le annotazioni per i motori di ricerca hanno uno scopo distinto. Google supporta le annotazioni delle versioni linguistiche equivalenti tramite HTML, header HTTP o sitemap. Scegli un metodo gestibile. Ogni versione dovrebbe identificare sé stessa e le versioni corrispondenti con URL completi, e le versioni dovrebbero rimandare l’una all’altra tramite queste annotazioni. Il selettore della pagina principale può essere la destinazione x-default. Comunicare a Google le versioni localizzate della pagina.

Per la raccolta fittizia, la mappatura delle annotazioni è la seguente:

Annotazione Destinazione fittizia
en https://example.com/en/
fr https://example.com/fr/
x-default https://example.com/

Inserisci queste relazioni tramite il meccanismo di annotazione supportato dal sistema di pubblicazione. La mappatura è una specifica, non markup eseguibile. x-default non configura la negoziazione lato server né fornisce una traduzione. Google dichiara inoltre di determinare algoritmicamente la lingua della pagina, senza usare hreflang o l’HTML lang per rilevarla. Comunicare a Google le versioni localizzate della pagina.

Mantieni le traduzioni complete accessibili indipendentemente dall’adattamento della pagina principale. Google documenta che il suo crawler invia richieste senza Accept-Language e avverte che le pagine adattate alla lingua locale potrebbero lasciare alcune varianti non individuate. Una lingua di ripiego affidabile e URL diretti per le lingue risolvono il problema di individuabilità senza richiedere a un crawler di richiedere introduzioni diverse per la pagina principale. Come Google esegue la scansione delle pagine adattate alla lingua locale.

Fare in modo che le risposte della pagina principale in cache rispettino la scelta della lingua

Quando la selezione della pagina principale dipende da Accept-Language, includi Vary: Accept-Language nelle risposte della pagina principale, compresa quella di ripiego. Mantieni eventuali campi di variazione già presenti. La risposta francese illustrativa della pagina principale includerebbe il seguente frammento di header; non è un messaggio HTTP completo: RFC 9110: semantica HTTP, sezione 12.5.5.

Content-Type: text/html; charset=utf-8
Content-Language: fr
Vary: Accept-Language

RFC 9111 richiede che una cache confronti i campi della richiesta indicati da Vary prima di riutilizzare una risposta memorizzata senza rivalidazione. È importante perché l’URL della pagina principale resta invariato mentre cambia l’introduzione. Vary descrive gli input di selezione, ma non implementa il sistema di corrispondenza linguistica. RFC 9111: caching HTTP, sezione 4.1.

Per /en/ e /fr/, questo progetto non varia il documento in base a Accept-Language. Verifica l’intero percorso di distribuzione, comprese eventuali cache condivise, rispetto all’accordo di routing. Come controllo pratico, alterna richieste alla pagina principale in inglese e francese, poi invertine l’ordine. Se la pagina principale restituisce ripetutamente la lingua richiesta in precedenza, controlla insieme il comportamento della cache e il routing.

Verificare l’accordo da un Mac

Prepara prima le tre pagine fittizie su un’origine di dimostrazione pubblica. Il test seguente richiede che tale origine contenga soltanto la raccolta dimostrativa in /, /en/ e /fr/. Non crea pagine né configura un host. Gli indirizzi illustrativi example.com sopra riportati non costituiscono un’installazione di test funzionante.

Apri l’app Terminale del Mac ed esegui curl --version per verificare che curl sia disponibile. Poi incolla la diagnostica shell completa riportata di seguito. Quando richiesto, inserisci l’origine di dimostrazione, compreso https://, senza percorso né barra finale.

printf 'Public demo origin, without a trailing slash: '
IFS= read -r demo_origin
case "$demo_origin" in
  https://*) ;;
  *) printf 'Enter an HTTPS origin.\n' >&2; exit 1 ;;
esac

for demo_path in / /en/ /fr/; do
  for demo_language in '' 'en' 'fr' 'fr-CA,fr;q=0.9,en;q=0.5' 'en;q=0.9,fr;q=0.2' 'de' 'fr;q=0,en;q=1'; do
    printf '\nPath: %s | Accept-Language: %s\n' \
      "$demo_path" "${demo_language:-absent}"
    curl --silent --show-error --connect-timeout 5 --max-time 15 \
      --dump-header - --header "Accept-Language: $demo_language" \
      "$demo_origin$demo_path" || exit 1
  done
done

Questa diagnostica stampa gli header e i corpi delle risposte. Curl usa --header per fornire la preferenza; il valore vuoto rimuove quell’header. --dump-header - stampa gli header sullo standard output e i limiti di tempo circoscrivono ogni trasferimento. Il reindirizzamento automatico è intenzionalmente disattivato, così un reindirizzamento inatteso resta visibile. curl — come si usa.

La sintassi dello script è stata verificata; qui non si dichiara alcuna distribuzione dimostrativa né alcun risultato effettivo del routing linguistico. Lo script si interrompe in caso di errore di trasferimento curl, ma una risposta HTTP di errore può comunque comparire nell’output e deve essere esaminata.

Confronta le risposte della pagina principale con la tabella delle preferenze. Poi controlla che ogni risposta a /en/ contenga testo inglese e ogni risposta a /fr/ testo francese, indipendentemente dalla preferenza fornita. Verifica i codici di stato, eventuali campi Location inattesi, la dichiarazione della lingua restituita e il testo effettivo del documento. Un header corretto con un corpo errato equivale comunque a un risultato non valido.

Infine, apri entrambi gli URL espliciti in un browser. Segui ciascun selettore della lingua, ricarica la destinazione e controlla la barra degli indirizzi. Così individui errori di navigazione che una richiesta diretta riuscita non rileverebbe. Verifica separatamente un percorso non pubblicato e accertati che non mostri di nascosto uno dei documenti completi.

Usare un selettore stabile quando la negoziazione non è disponibile

Questo progetto richiede un livello di distribuzione in grado di leggere un header di richiesta e scegliere una risposta. I meccanismi di WHATWG relativi alla lingua del documento e agli URL descrivono documenti e indirizzi; aggiungere un attributo lang o modificare il testo dei link non crea da sé una negoziazione HTTP. La selezione basata sulla richiesta appartiene alla configurazione della distribuzione HTTP. Standard HTML, RFC 9110: semantica HTTP.

Se il sistema di pubblicazione non offre questa capacità di distribuzione, usa un selettore fisso nella pagina principale con link diretti alle pagine linguistiche complete. Questo preserva la possibilità di scelta dei lettori e segue la raccomandazione di Google di usare URL distinti per le lingue e link visibili per passare dall’una all’altra. Qui non si presuppone alcuna funzionalità di negoziazione specifica di un prodotto di pubblicazione. Gestire siti multiregionali e multilingue.

Il criterio pratico di accettazione è semplice: le preferenze possono essere d’aiuto nella pagina principale, mentre i link espliciti alle lingue restano destinazioni affidabili. Concludi documentando la lingua di ripiego, le dichiarazioni linguistiche corrispondenti nei documenti, le annotazioni reciproche delle lingue e le prove, richiesta per richiesta, che confermano il rispetto dell’accordo di routing.

Fonti