Языковые атрибуты в HTML

При локализации веб-приложений недостаточно перевести текст интерфейса. Браузеры, поисковые системы, программы экранного доступа и различные инструменты обработки контента должны понимать, на каком языке представлен документ или его отдельные части. Для этого используются языковые атрибуты HTML.

При работе с I18next языковые атрибуты обычно синхронизируются с текущим выбранным языком приложения. Это обеспечивает корректное отображение контента, улучшает доступность и помогает поисковым системам правильно интерпретировать страницу.

Основным атрибутом является lang.

<html lang="en">

Для русского языка:

<html lang="ru">

Для немецкого:

<html lang="de">

Атрибут может устанавливаться как для всего документа, так и для отдельных элементов.

Атрибут lang

Атрибут lang определяет язык содержимого элемента.

Пример:

<p lang="en">Hello World</p>
<p lang="ru">Привет мир</p>

Браузер получает информацию о языке текста и может:

  • использовать соответствующие правила переноса слов;
  • выбирать правильное произношение в синтезаторах речи;
  • применять языковые правила проверки орфографии;
  • передавать корректные данные вспомогательным технологиям.

Для мультиязычных интерфейсов это особенно важно.

Стандарт языковых кодов

Для атрибута lang используются коды согласно стандарту BCP 47.

Наиболее распространённые значения:

Язык Код
Русский ru
Английский en
Немецкий de
Французский fr
Испанский es
Итальянский it
Китайский zh
Японский ja
Корейский ko
Казахский kk

Пример:

<html lang="kk">

Указание региона

Иногда одного языкового кода недостаточно. Один язык может использоваться в нескольких странах с различиями в орфографии, терминологии и форматировании.

Для таких случаев используется комбинация:

язык-РЕГИОН

Примеры:

<html lang="en-US">
<html lang="en-GB">
<html lang="pt-BR">
<html lang="fr-CA">

Различия между вариантами языка могут быть существенными:

Код Описание
en-US Английский (США)
en-GB Английский (Великобритания)
pt-BR Португальский (Бразилия)
pt-PT Португальский (Португалия)

I18next полностью поддерживает подобные языковые обозначения.

Связь lang и текущего языка I18next

После инициализации I18next выбранный язык хранится в свойстве:

i18next.language

Например:

console.log(i18next.language);

Результат:

ru

или

en-US

Логично синхронизировать значение атрибута lang с текущим языком приложения.

Пример:

document.documentElement.lang = i18next.language;

После выполнения:

<html lang="ru">

или

<html lang="en-US">

Таким образом HTML-документ всегда отражает текущее состояние локализации.

Автоматическое обновление lang при смене языка

При переключении языка через I18next необходимо обновлять атрибут автоматически.

Пример:

i18next.on('languageChanged', (lng) => {
    document.documentElement.lang = lng;
});

Смена языка:

i18next.changeLanguage('de');

Приведёт к обновлению:

<html lang="de">

Без необходимости ручного вмешательства.

Полный пример интеграции

Инициализация:

i18next.init({
    lng: 'en',
    resources: {
        en: {
            translation: {
                title: 'Welcome'
            }
        },
        ru: {
            translation: {
                title: 'Добро пожаловать'
            }
        }
    }
});

Установка языка документа:

document.documentElement.lang = i18next.language;

Подписка на изменения:

i18next.on('languageChanged', (lng) => {
    document.documentElement.lang = lng;
});

Переключатель:

document
    .getElementById('languageSwitcher')
    .addEventListener('change', (event) => {
        i18next.changeLanguage(event.target.value);
    });

HTML:

<select id="languageSwitcher">
    <option value="en">English</option>
    <option value="ru">Русский</option>
</select>

Теперь текст интерфейса и атрибут документа изменяются синхронно.

Использование lang для отдельных фрагментов текста

Даже внутри локализованного интерфейса могут встречаться вставки на других языках.

Пример:

<p>
    Термин
    <span lang="en">Single Sign-On</span>
    означает единый вход в систему.
</p>

Или:

<p>
    Немецкое слово
    <span lang="de">Datenschutz</span>
    означает защиту данных.
</p>

Такая разметка помогает программам чтения с экрана правильно произносить иностранные слова.

Смешанные языки в локализованных переводах

Иногда перевод содержит брендовые названия или международные термины.

Файл перевода:

{
    "description": "Работает через <span lang=\"en\">API Gateway</span>"
}

Вывод:

element.innerHTML = i18next.t('description');

Результат:

Работает через
<span lang="en">API Gateway</span>

Подобная практика улучшает доступность интерфейса.

Атрибут dir и его связь с lang

Некоторые языки пишутся справа налево.

Наиболее распространённые:

Язык Код
Арабский ar
Иврит he
Персидский fa
Урду ur

Для них дополнительно используется атрибут:

dir="rtl"

Пример:

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

Для большинства европейских языков используется:

dir="ltr"

Автоматическая настройка dir через I18next

Можно поддерживать направление текста автоматически.

Список RTL-языков:

const rtlLanguages = ['ar', 'he', 'fa', 'ur'];

Функция обновления:

function updateDocumentLanguage(language) {
    document.documentElement.lang = language;

    document.documentElement.dir =
        rtlLanguages.includes(language)
            ? 'rtl'
            : 'ltr';
}

Подписка:

i18next.on('languageChanged', updateDocumentLanguage);

Первоначальная установка:

updateDocumentLanguage(i18next.language);

Теперь документ корректно настраивается как для английского, так и для арабского интерфейса.

Получение языка браузера

Для определения предпочтений пользователя часто используется:

navigator.language

Пример результата:

en-US

или

ru-RU

Это значение может использоваться при первоначальной настройке I18next.

i18next.init({
    lng: navigator.language
});

После инициализации язык документа также можно синхронизировать:

document.documentElement.lang = i18next.language;

Использование fallback-языков

Браузер может вернуть язык, который отсутствует среди поддерживаемых переводов.

Например:

fr-CA

При этом приложение поддерживает только:

fr
en

Настройка I18next:

i18next.init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr']
});

После выбора языка следует устанавливать именно итоговое значение:

document.documentElement.lang = i18next.resolvedLanguage;

Свойство:

i18next.resolvedLanguage

отражает фактически используемый язык после применения механизмов fallback.

SEO и языковые атрибуты

Поисковые системы анализируют атрибут lang для определения языка страницы.

Корректная разметка:

<html lang="ru">

помогает:

  • правильно индексировать страницы;
  • улучшать релевантность результатов поиска;
  • определять целевую аудиторию контента;
  • корректно обрабатывать мультиязычные сайты.

Для проектов с несколькими языками это является обязательной практикой.

Доступность и программы экранного доступа

Screen Reader активно используют атрибут lang.

Если язык не указан:

<html>

программа может использовать неверное произношение текста.

Правильный вариант:

<html lang="ru">

Для встроенных иностранных слов:

<p>
    Используется технология
    <span lang="en">Machine Learning</span>.
</p>

В таком случае синтезатор речи автоматически переключает правила произношения.

Проверка текущих настроек документа

Получение текущего языка:

console.log(document.documentElement.lang);

Получение направления текста:

console.log(document.documentElement.dir);

Установка новых значений:

document.documentElement.lang = 'es';
document.documentElement.dir = 'ltr';

Проверка после смены языка:

i18next.on('languageChanged', (lng) => {
    console.log('Language:', lng);
    console.log('HTML lang:', document.documentElement.lang);
});

Распространённые ошибки

Отсутствие атрибута lang

Неправильно:

<html>

Правильно:

<html lang="en">

Несинхронизированный язык документа

Неправильно:

<html lang="en">

При этом интерфейс уже отображается на русском языке.

Правильно:

document.documentElement.lang = i18next.language;

Игнорирование региональных вариантов

Неправильно:

document.documentElement.lang = 'en';

если приложение работает в режиме:

en-GB

Правильно:

document.documentElement.lang = i18next.language;

Отсутствие настройки dir для RTL-языков

Неправильно:

<html lang="ar">

Правильно:

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

или динамически:

document.documentElement.dir = 'rtl';

Практический шаблон для проектов с I18next

function applyLanguageSettings(language) {
    const rtlLanguages = ['ar', 'he', 'fa', 'ur'];

    document.documentElement.lang = language;

    document.documentElement.dir =
        rtlLanguages.includes(language)
            ? 'rtl'
            : 'ltr';
}

i18next.init({
    lng: 'en',
    fallbackLng: 'en'
}).then(() => {
    applyLanguageSettings(i18next.resolvedLanguage);
});

i18next.on('languageChanged', (lng) => {
    applyLanguageSettings(lng);
});

Такой подход обеспечивает синхронизацию языка интерфейса, языковых атрибутов HTML, направления текста, требований доступности и механизмов поисковой индексации во всех локализованных разделах приложения.

Оглавление