Dokumentacja HTML z przykładami: Atrybut lang

Q: Co wpisać w atrybucie lang elementu html?

Kod języka ze standardu BCP 47: en dla angielskiego, es dla hiszpańskiego, fr dla francuskiego, ja dla japońskiego. Region dodawaj tylko wtedy, gdy ma znaczenie, jak w en-US, en-GB czy pt-BR.

Q: Użyć lang="en" czy lang="en-US"?

Oba są poprawne. en wystarcza dla większości angielskich stron. Użyj en-US lub en-GB, gdy odmiana regionalna ma znaczenie, na przykład dla pisowni, dat albo wymowy niektórych słów.

Q: Jak oznaczyć tekst w innym języku?

Dodaj lang do elementu, który go otacza: bon appétit . Czytniki ekranu zmieniają wymowę dla tej frazy, a CSS może ją ostylować przez :lang(fr).

Q: Czym różni się lang od hreflang?

lang mówi, w jakim języku jest treść elementu. hreflang umieszcza się na linku i mówi, w jakim języku jest strona docelowa; w ten sposób strony wskazują wyszukiwarkom wersje w innych językach.

Ustaw język strony

Umieść atrybut lang na elemencie <html>, z kodem języka, w którym napisana jest strona:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>lang</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <p>Hello! This page is in English.</p>
  <p id="out" style="color: #6b7280;"></p>
  <script>
    document.getElementById('out').textContent =
      'Page language: ' + document.documentElement.lang +
      '. Your browser language: ' + navigator.language + '.';
  </script>
</body>
</html>

Atrybut nie zmienia wyglądu tego akapitu, ale zmienia sposób obsługi strony: czytnik ekranu czyta ją angielskim głosem, przeglądarka bierze go pod uwagę, gdy decyduje, czy zaproponować tłumaczenie, a narzędzie do sprawdzania pisowni może dzięki niemu wybrać słownik angielski. Bez niego narzędzia muszą zgadywać, a czytnik ekranu ustawiony na inny język może czytać angielski tekst z błędną wymową.

Kody języków

Wartość to znacznik języka ze standardu BCP 47. Większość to dwuliterowy kod języka, opcjonalnie z regionem lub systemem pisma:

Kod	Język
`en`	angielski
`en-US`, `en-GB`	angielski w Stanach Zjednoczonych, w Wielkiej Brytanii
`es`, `es-MX`	hiszpański, hiszpański w Meksyku
`pt-BR`	portugalski w Brazylii
`fr`, `de`, `it`	francuski, niemiecki, włoski
`ar`, `he`	arabski, hebrajski (od prawej do lewej, zobacz niżej)
`ja`, `ko`	japoński, koreański
`zh-Hans`, `zh-Hant`	chiński w znakach uproszczonych, tradycyjnych

Wielkość liter w kodach nie ma znaczenia, ale przyjęło się pisać język małymi literami, a region wielkimi. Region dodawaj tylko wtedy, gdy odmiana ma znaczenie; en to pełna i poprawna wartość.

Widoczne zmiany, które wprowadza lang

Większość efektów lang dotyczy oprogramowania, ale kilka widać na ekranie. Cudzysłowy z elementu <q> zależą od języka, podobnie jak zasady wielkości liter:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Visible effects</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; font-size: 18px; }
    td { padding: 4px 12px; border-bottom: 1px solid #e5e7eb; }
    .up { text-transform: uppercase; }
  </style>
</head>
<body>
  <table>
    <tr><td>English</td><td lang="en"><q>quote</q></td><td lang="en" class="up">istanbul</td></tr>
    <tr><td>French</td><td lang="fr"><q>quote</q></td><td lang="fr" class="up">istanbul</td></tr>
    <tr><td>German</td><td lang="de"><q>quote</q></td><td lang="de" class="up">istanbul</td></tr>
    <tr><td>Japanese</td><td lang="ja"><q>quote</q></td><td lang="ja" class="up">istanbul</td></tr>
    <tr><td>Turkish</td><td lang="tr"><q>quote</q></td><td lang="tr" class="up">istanbul</td></tr>
  </table>
</body>
</html>

Każdy wiersz dostaje własny styl cudzysłowów. W ostatniej kolumnie ta sama reguła text-transform: uppercase daje "ISTANBUL" po angielsku i "İSTANBUL" po turecku, bo w tureckim wielka litera i zachowuje kropkę. Zmień lang w tureckim wierszu na en, a kropka zniknie. Automatyczne dzielenie wyrazów (hyphens: auto w CSS) też zależy od lang: przeglądarka musi znać język, żeby wiedzieć, gdzie można dzielić słowa.

Oznaczanie fraz w innym języku

lang działa na każdym elemencie, nie tylko na <html>. Gdy strona w jednym języku cytuje frazę w innym, otocz frazę elementem i nadaj jej własny kod. CSS może wybierać języki selektorem :lang():

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Mixed languages</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    :lang(fr), :lang(es) { font-style: italic; color: #2563eb; }
  </style>
</head>
<body>
  <p>The chef said <span lang="fr">bon appétit</span> and left.</p>
  <p>Our team motto is <span lang="es">poco a poco</span>: little by little.</p>
</body>
</html>

Czytnik ekranu przełącza się na francuską wymowę dla "bon appétit", a potem wraca do angielskiej. :lang(fr) pasuje też do fr-CA i każdej innej odmiany francuskiego oraz do elementów, które dziedziczą język po przodku, czego selektor atrybutu taki jak [lang="fr"] by nie wychwycił.

Języki pisane od prawej do lewej: dir

Arabski, hebrajski, perski i urdu zapisuje się od prawej do lewej. lang określa język; atrybut dir ustawia kierunek. Cała strona po arabsku używa obu na <html>:

<html lang="ar" dir="rtl">

Dla krótkiej frazy pisanej od prawej do lewej na stronie pisanej od lewej do prawej umieść oba atrybuty na otaczającym ją elemencie:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>dir</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    blockquote { border-inline-start: 4px solid #16a34a; margin: 12px 0; padding-inline-start: 12px; }
  </style>
</head>
<body>
  <p>The Arabic word for hello is <span lang="ar" dir="rtl">مرحبا</span>.</p>
  <blockquote lang="ar" dir="rtl">مرحبا بكم في الموقع</blockquote>
</body>
</html>

Cytat wyrównuje się do prawej, a jego zielony pasek również przesuwa się na prawo, bo border-inline-start podąża za kierunkiem. Właściwości logiczne, takie jak margin-inline-start zamiast margin-left, utrzymują poprawny układ w obu kierunkach.

lang vs hreflang

lang opisuje treść elementu. hreflang umieszcza się na linku i opisuje stronę, na którą on wskazuje. Strony z tłumaczeniami wymieniają każdą wersję w <head>, żeby wyszukiwarki mogły kierować każdego czytelnika do właściwej:

<link rel="alternate" hreflang="en" href="https://example.com/">
<link rel="alternate" hreflang="de" href="https://example.com/de/">
<link rel="alternate" hreflang="x-default" href="https://example.com/">

Każda przetłumaczona strona nadal ustawia własny lang na <html>: lang="de" na niemieckiej.

Częste błędy

Pominięcie lang. Wiele szablonów o nim zapomina; ustawiaj go obok doctype na każdej stronie.
Kopiowanie lang="en" do przetłumaczonych stron. Niemiecka strona oznaczona jako angielska jest czytana z angielską wymową. Dopasuj go do treści.
Kod kraju zamiast kodu języka. lang="jp" i lang="gr" to nie japoński i grecki; właściwe kody to ja i el.
Ustawianie kierunku przez lang. Samo lang="ar" nie sprawi, że tekst popłynie od prawej do lewej. Dodaj dir="rtl".
Pisanie lang="en_US". Separatorem jest łącznik: en-US.

Najczęściej zadawane pytania

Co robi atrybut lang w HTML?

Deklaruje język treści elementu. Czytniki ekranu używają go do wyboru właściwego głosu i wymowy, przeglądarki do proponowania tłumaczenia, wyboru cudzysłowów i dzielenia wyrazów, a niektóre narzędzia do sprawdzania pisowni do wyboru słownika.

Co wpisać w atrybucie lang elementu html?

Kod języka ze standardu BCP 47: en dla angielskiego, es dla hiszpańskiego, fr dla francuskiego, ja dla japońskiego. Region dodawaj tylko wtedy, gdy ma znaczenie, jak w en-US, en-GB czy pt-BR.

Użyć lang="en" czy lang="en-US"?

Oba są poprawne. en wystarcza dla większości angielskich stron. Użyj en-US lub en-GB, gdy odmiana regionalna ma znaczenie, na przykład dla pisowni, dat albo wymowy niektórych słów.

Czy atrybut lang wpływa na SEO?

Google podaje, że rozpoznaje język z samego tekstu i nie opiera się na atrybucie lang. Mimo to ustaw go poprawnie: używają go inne wyszukiwarki, narzędzia do tłumaczenia i czytniki ekranu. Do łączenia przetłumaczonych wersji strony służą linki hreflang.

Jak oznaczyć tekst w innym języku?

Dodaj lang do elementu, który go otacza: <span lang="fr">bon appétit</span>. Czytniki ekranu zmieniają wymowę dla tej frazy, a CSS może ją ostylować przez :lang(fr).

Czym różni się lang od hreflang?

lang mówi, w jakim języku jest treść elementu. hreflang umieszcza się na linku i mówi, w jakim języku jest strona docelowa; w ten sposób strony wskazują wyszukiwarkom wersje w innych językach.

Powiązane zagadnienia