Negocjuj język tylko pod adresem /, a jawne adresy URL, takie jak /en/ i /fr/, zawsze niech wyświetlają wskazaną w nich wersję językową. Ten poradnik pokazuje wydawcy korzystającemu z Maca, jak określić takie działanie, zachować łatwo znajdowane odnośniki do dokumentów i przetestować rezultat.

Przykład dotyczy syntetycznego, publicznego zbioru dokumentów z angielską i francuską wersją krótkiego poradnika o układaniu kształtów. Strona główna jest stroną wyboru języka, której tekst wprowadzający może dostosowywać się do żądania. Wszystkie przykładowe adresy opisują proponowaną konfigurację; nie oznaczają, że pod tymi adresami są obecnie hostowane strony.

Określ działanie adresów URL przed zmianą ustawień języka

Zacznij od krótkiej specyfikacji routingu. W tym przykładzie strona główna pomaga czytelnikom wybrać język, a dwie jawne ścieżki zawierają kompletny przetłumaczony dokument. Google zaleca osobne adresy URL dla wersji językowych i odradza automatyczne przekierowywanie czytelników między nimi na podstawie założonego języka. Widoczne odnośniki pozwalają czytelnikom samodzielnie dokonać wyboru. Zarządzanie witrynami wieloregionalnymi i wielojęzycznymi.

Żądana ścieżka Oczekiwana odpowiedź Wpływ preferencji językowej
/ Selektor języka z krótkim wprowadzeniem Może zmienić wprowadzenie i sugerowany odnośnik
/en/ Kompletny dokument w języku angielskim Język dokumentu pozostaje bez zmian
/fr/ Kompletny dokument w języku francuskim Język dokumentu pozostaje bez zmian
Nieopublikowana ścieżka Odpowiedź o braku strony Nie może po cichu zmienić się w inny dokument

Potraktuj tę tabelę jako specyfikację wdrożenia. Wybieraj język dopiero po sprawdzeniu, czy żądanie dotyczy strony głównej. Ogólna reguła uruchamiana przed każdym żądaniem strony może nadpisać jawny wybór i złamać specyfikację.

Na przykład osoba otwierająca /fr/ powinna nadal otrzymać francuski dokument, nawet jeśli w żądaniu preferuje język angielski. Preferencja angielskiego przydaje się w punkcie wejścia, w którym wybór nie został jeszcze dokonany; jawna ścieżka w innym miejscu już wskazuje wybór. Taka kolejność priorytetów jest zaleceniem projektowym stosowanym w całym artykule.

Na każdej stronie pozostaw widoczne odnośniki do obu wersji językowych. Na stronie głównej sugerowany język może ułatwić pierwszy wybór, nie ukrywając drugiej opcji. W kompletnych dokumentach przełącznik powinien prowadzić bezpośrednio do odpowiadającego mu dokumentu.

Wybierz przewidywalną politykę językową strony głównej

Accept-Language określa preferowane języki odpowiedzi, z wagami jakości, takimi jak fr;q=0.9,en;q=0.5. Nie wymaga od serwera udostępnienia każdego żądanego języka. Waga jakości równa zero oznacza, że język jest nieakceptowalny. Content-Language opisuje zamierzoną grupę odbiorców zwracanej reprezentacji; nie wybiera trasy. RFC 9110: Semantyka HTTP, sekcje 8.5, 12.4.2 i 12.5.4.

Zanim cokolwiek skonfigurujesz, zapisz listę obsługiwanych języków i język domyślny. W tym przykładzie użyj angielskich i francuskich wprowadzeń, a gdy żądanie nie zawiera użytecznego dopasowania, wyświetl angielskie wprowadzenie i wybór obu języków. Taki język domyślny to przykładowa decyzja wydawnicza, a nie wymóg HTTP.

Zastosuj mechanizm dopasowania języka z jawną polityką. RFC 4647 rozróżnia filtrowanie i wyszukiwanie: wyszukiwanie wybiera jeden wynik, uwzględnia żądane zakresy w kolejności priorytetu i stopniowo usuwa podtagi w poszukiwaniu dopasowania. Wymaga również, by aplikacje korzystające z wyszukiwania określiły zachowanie domyślne. Dzięki temu żądanie fr-CA może przez wyszukiwanie dopasować się do obsługiwanego ogólnego wprowadzenia fr. RFC 4647: Dopasowywanie tagów językowych, sekcje 3.4–3.4.1.

Nie wybieraj języka, wyszukując w nagłówku pierwsze wystąpienie fr lub en. Taki skrót pomija wagi i wykluczenia. Warstwa dopasowania powinna analizować preferencje, uwzględniać wykluczenia z wagą zero, a następnie stosować udokumentowany język domyślny.

Preferencja w żądaniu strony głównej Oczekiwany rezultat w tym przykładzie
Brak nagłówka Angielskie wprowadzenie i obie opcje
fr Francuskie wprowadzenie i obie opcje
fr-CA,fr;q=0.9,en;q=0.5 Francuskie wprowadzenie
en;q=0.9,fr;q=0.2 Angielskie wprowadzenie
de Selektor domyślny
fr;q=0,en;q=1 Angielskie wprowadzenie; język francuski nie zostaje wybrany
*;q=0 Jawnie określone postępowanie z niedopasowanym językiem

Ostatni wiersz wymaga świadomej decyzji. W przypadku tego projektu selektora określ, że żądanie wykluczające wszystkie języki otrzymuje selektor domyślny, ponieważ aplikacja nie uwzględnia tej preferencji — nie należy twierdzić, że dopasowano język angielski. Jeśli negocjacja ma być rygorystyczna, określ i przetestuj odpowiednie zachowanie dla języka nieakceptowalnego. W obu przypadkach nie traktuj przypadkowo zera jak zwykłej niskiej preferencji.

Zachowaj zgodność języka dokumentu, odnośników i adnotacji wyszukiwania

W każdym dokumencie HTML ustaw atrybut lang na rzeczywisty główny język dokumentu: en dla strony angielskiej i fr dla francuskiej. WHATWG definiuje lang jako główny język zawartości elementu i atrybutów zawierających tekst; gdy go pominięto, język jest dziedziczony po elemencie nadrzędnym. Sam prefiks językowy nie zastępuje tej deklaracji. Standard HTML: atrybuty lang i xml:lang.

Sprawdź nawigację oraz tekst strony. Względne adresy URL są rozwiązywane względem adresu bazowego zgodnie ze standardem URL WHATWG. Na przykład, jeśli dokument nie ma innego adresu bazowego, fr/ z https://example.com/en/ rozwiązuje się do https://example.com/en/fr/; /fr/ prowadzi do francuskiej ścieżki w obrębie tej samej domeny. W widocznym przełączniku użyj zamierzonej ścieżki bezwzględnej. Standard URL: zapisywanie i analizowanie adresów URL.

Adnotacje dla wyszukiwarek służą innemu celowi. Google obsługuje adnotacje równoważnych wersji językowych w HTML, nagłówkach HTTP lub mapie witryny. Wybierz jedną łatwą w utrzymaniu metodę. Każda wersja powinna wskazywać siebie i odpowiedniki za pomocą w pełni kwalifikowanych adresów URL, a wersje powinny wzajemnie się wskazywać przez te adnotacje. Miejscem docelowym dla x-default może być selektor na stronie głównej. Informowanie Google o zlokalizowanych wersjach strony.

W przypadku syntetycznego zbioru mapowanie adnotacji wygląda następująco:

Adnotacja Syntetyczny adres docelowy
en https://example.com/en/
fr https://example.com/fr/
x-default https://example.com/

Wprowadź te relacje za pomocą mechanizmu adnotacji obsługiwanego przez system wydawniczy. Mapowanie jest specyfikacją, a nie wykonywalnym kodem. x-default nie konfiguruje negocjacji po stronie serwera ani nie dostarcza tłumaczenia. Google podaje też, że określa język strony algorytmicznie, zamiast używać do jego wykrywania hreflang lub HTML lang. Informowanie Google o zlokalizowanych wersjach strony.

Zapewnij niezależny dostęp do kompletnych tłumaczeń, tak aby ich dostępność nie zależała od dostosowywania strony głównej. Google podaje, że jego robot indeksujący wysyła żądania bez Accept-Language, i ostrzega, że strony dostosowujące się do ustawień regionalnych mogą pozostać częściowo nieodkryte. Niezawodna wersja domyślna i bezpośrednie adresy URL wersji językowych rozwiązują problem wykrywalności bez konieczności wysyłania przez robota żądań o różne wprowadzenia na stronie głównej. Jak Google indeksuje strony dostosowujące się do ustawień regionalnych.

Dopilnuj, by pamięć podręczna uwzględniała wybór języka strony głównej

Gdy wybór języka strony głównej zależy od Accept-Language, dołącz Vary: Accept-Language do odpowiedzi tej strony, również do odpowiedzi domyślnej. Zachowaj istniejące pola zmienności. Przykładowa odpowiedź francuskiej strony głównej zawierałaby poniższy fragment nagłówka; nie jest to kompletna wiadomość HTTP: RFC 9110: Semantyka HTTP, sekcja 12.5.5.

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

RFC 9111 wymaga, by pamięć podręczna dopasowała pola żądania wymienione w Vary, zanim ponownie użyje zapisaną odpowiedź bez ponownej walidacji. Ma to znaczenie, ponieważ adres URL strony głównej pozostaje taki sam, a jej wprowadzenie się zmienia. Vary opisuje dane wejściowe wyboru; nie implementuje mechanizmu dopasowywania języka. RFC 9111: Buforowanie HTTP, sekcja 4.1.

W tym projekcie dokumenty pod /en/ i /fr/ nie różnią się w zależności od Accept-Language. Sprawdź całą ścieżkę dostarczania, w tym wszystkie współdzielone pamięci podręczne, pod kątem zgodności ze specyfikacją routingu. Jako praktyczny test diagnostyczny wykonuj naprzemiennie żądania strony głównej po angielsku i francusku, a potem odwróć ich kolejność. Jeśli strona główna wielokrotnie zwraca wcześniej żądaną wersję językową, sprawdź jednocześnie działanie pamięci podręcznej i routingu.

Przetestuj specyfikację na Macu

Najpierw przygotuj trzy syntetyczne strony w publicznym środowisku demonstracyjnym. Poniższy test wymaga, by pod adresem /, /en/ i /fr/ znajdowała się wyłącznie demonstracyjna kolekcja. Test nie tworzy stron ani nie konfiguruje hosta. Podane wyżej przykładowe adresy example.com nie oznaczają działającej instalacji testowej.

Otwórz aplikację Terminal na Macu i uruchom curl --version, aby potwierdzić, że curl jest dostępny. Następnie wklej poniższy kompletny skrypt diagnostyczny powłoki. Po wyświetleniu monitu wpisz adres środowiska demonstracyjnego wraz z https://, bez ścieżki i końcowego ukośnika.

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

Ten skrypt diagnostyczny wyświetla nagłówki i treści odpowiedzi. Opcja --header programu curl ustawia preferencję; pusta wartość usuwa ten nagłówek. Opcja --dump-header - wyświetla nagłówki na standardowym wyjściu, a limity czasu ograniczają czas każdego transferu. Celowo nie użyto przekierowań, aby nieoczekiwane przekierowanie było widoczne. curl — jak używać.

Składnia powłoki skryptu została sprawdzona; nie twierdzimy, że wdrożono wersję demonstracyjną ani uzyskano wynik działania routingu językowego na żywo. Skrypt zatrzymuje się w przypadku błędu transferu curl, ale odpowiedź HTTP z kodem błędu może nadal pojawić się w wynikach i trzeba ją sprawdzić.

Porównaj odpowiedzi strony głównej z tabelą preferencji. Następnie sprawdź, czy każda odpowiedź /en/ zawiera angielską treść, a każda odpowiedź /fr/ — francuską, niezależnie od podanej preferencji. Sprawdź kody statusu, nieoczekiwane pola Location, deklarację języka w odpowiedzi i rzeczywistą treść dokumentu. Prawidłowy nagłówek przy nieprawidłowej treści nadal oznacza niepowodzenie.

Na koniec otwórz oba jawne adresy URL w przeglądarce. Kliknij przełącznik języka, wczytaj ponownie stronę docelową i sprawdź pasek adresu. To pozwala wykryć błędy nawigacji, których nie ujawniłoby udane bezpośrednie żądanie. Osobno przetestuj nieopublikowaną ścieżkę i potwierdź, że nie wyświetla po cichu jednego z kompletnych dokumentów.

Użyj stabilnego selektora, gdy negocjacja jest niedostępna

Ten projekt wymaga warstwy dostarczającej treści, która potrafi odczytać nagłówek żądania i wybrać odpowiedź. Mechanizmy WHATWG dotyczące języka dokumentu i adresów URL opisują dokumenty i adresy; dodanie atrybutu lang lub zmiana tekstu odnośnika nie tworzą same z siebie negocjacji HTTP. Wybór zależny od żądania należy skonfigurować w ustawieniach dostarczania HTTP. Standard HTML, RFC 9110: Semantyka HTTP.

Jeśli system wydawniczy nie oferuje takiej funkcji dostarczania, użyj stałego selektora na stronie głównej z bezpośrednimi odnośnikami do kompletnych stron językowych. Zachowuje to możliwość wyboru przez czytelnika i odpowiada zaleceniom Google, by stosować osobne adresy URL wersji językowych oraz widoczne odnośniki przełączające. Nie zakłada się tu dostępności funkcji negocjacji w żadnym konkretnym produkcie wydawniczym. Zarządzanie witrynami wieloregionalnymi i wielojęzycznymi.

Praktyczne kryterium akceptacji jest proste: preferencje mogą pomagać na stronie głównej, a jawne odnośniki językowe pozostają niezawodnymi miejscami docelowymi. Zakończ pracę, dokumentując język domyślny, deklaracje języka w dokumentach, wzajemne adnotacje wersji językowych i dowody z poszczególnych żądań, że specyfikacja routingu jest spełniona.

Źródła