Язык интерфейса

Компоненты Framework сами подставляют часть слов: доступные имена кнопок, подписи по умолчанию, сообщения. Эта глава описывает, как компонент выбирает язык этих слов по разметке страницы.

Правило

Компоненты Framework говорят по-английски по умолчанию и по-русски на русской странице. Речь об их собственных словах: доступных именах кнопок, подписях по умолчанию, подсказках для клавиатуры, сообщениях.

Язык определяется одним правилом для всех компонентов. Компонент смотрит на ближайший к себе атрибут lang — поиск проходит и через границы shadow DOM, к элементам, внутри которых компонент собран. Если такого атрибута нет, компонент смотрит на lang документа, а если нет и его, выбирает английский. ru и ru-RU — русский.

<html lang="ru">
  …
  <sf-tag closable text="Отчёт"></sf-tag>
  <!-- кнопка удаления называется «Удалить» -->
</html>

У sf-tag по умолчанию kind="checkbox"; атрибут closable добавляет такому тегу кнопку удаления.

Язык можно задать и для части страницы:

<section lang="en">
  <sf-country-code></sf-country-code>
  <!-- поле и названия стран — по-английски -->
</section>

Откуда берётся слово

Каждое слово компонент ищет в таком порядке и берёт первое найденное:

1. атрибут компонента — если подпись передана, она показывается как есть, на любом языке;
2. слово, которое проект зарегистрировал для этого языка (см. Свой язык и явный выбор языка);
3. слово, которое поставляет сам компонент;
4. шаги 2–3 для языка без региона: для pt-BR — pt;
5. шаги 2–3 для английского;
6. сам ключ слова — пропуск в переводе виден, а не превращается в пустое место.

Поэтому слово, которое проект не перевёл, показывается по-английски, а не на случайном языке страницы.

Свой язык и явный выбор языка

Компоненты поставляют английские и русские слова. Любой другой язык проект добавляет сам, без изменения Framework:

SF.language.registerAll('tr', {
  'sf-pagination': { showMoreText: 'Daha fazla göster' },
});
SF.language.use('tr');   // явно выбрать язык для всей страницы
SF.language.use(null);   // снять явный выбор и снова следовать атрибуту lang

• SF.language.register(component, code, words) добавляет слова одного компонента, registerAll(code, byComponent) — сразу нескольких. Слова дополняют уже зарегистрированные, а words = null убирает их для этого языка.
• SF.language.use(code) переключает язык сразу, без перезагрузки страницы: Smart-компоненты перерисовываются сами. Первую отрисовку определяет атрибут lang. Явный выбор задаёт и язык форматирования: компоненты, которые сами называют месяцы и дни недели через Intl (календарь sf-datepicker), берут выбранный язык вместе с регионом (use('ar-EG')). Регион выбирает и цифры: по данным Intl браузера ar пишет год латинскими цифрами, а ar-EG — арабско-индийскими. Код без региона (use('ru'), lang="ru") Intl дополняет регионом по своему правилу для языка: ru форматирует как ru-RU, en — как en-US. Собственный атрибут locale компонента сильнее явного выбора.
• SF.language.use(null) снимает явный выбор: язык снова определяет ближайший атрибут lang, и компоненты перерисовываются.
• SF.language.current(node) возвращает действующий язык узла вместе с регионом (ru-ru; без аргумента — язык документа), known(component) — языки, для которых проект зарегистрировал слова компонента, components() — компоненты, для которых зарегистрированы слова, onChange(listener) — подписка на смену языка и зарегистрированных слов; возвращает функцию отписки.
• SF.language.forget() удаляет все зарегистрированные слова и снимает явный выбор языка.

Для своих элементов проект использует то же правило: SF.pageLanguage(node) возвращает язык узла без региона (ru), SF.pageText(dictionary, key, node, component?) — слово из словаря на этом языке. Словарь устроен как { en: { key: '…' }, ru: { key: '…' } }. Если слова нет на языке узла, pageText берёт язык без региона, затем en, а если нет и его — возвращает сам ключ. Слова, зарегистрированные через SF.language, pageText находит по имени тега узла; четвёртый аргумент component задаёт имя явно.

Переключатель языка на странице делает две вещи: выбирает язык для компонентов и сам ставит lang и dir документу. Явный выбор сильнее атрибута, поэтому порядок вызовов не важен, а lang нужен вспомогательным технологиям и стилям по :lang():

function switchLanguage(code, direction = 'ltr') {
  SF.language.use(code);                      // слова и форматы компонентов
  document.documentElement.lang = code;       // язык документа
  document.documentElement.dir = direction;   // направление письма
}

switchLanguage('ar', 'rtl');

Framework не запоминает выбранный язык: ни cookie, ни записи в браузере, как у темы (sf-theme), у языка нет. Храните выбор сами и восстанавливайте его до core.js встроенным скриптом: он ставит lang и dir на <html>, и компоненты сразу рисуются на этом языке.

<script>
  try {
    const saved = JSON.parse(localStorage.getItem('project-language') || 'null');
    if (saved) {
      document.documentElement.lang = saved.code;
      document.documentElement.dir = saved.dir;
    }
  } catch {}
</script>

Переключатель сохраняет выбор той же записью: localStorage.setItem('project-language', JSON.stringify({code, dir: direction})). SF.language.use() после восстановления нужен, только если выбран язык с регионом, который нужен календарю и числам; SF.language есть сразу после core.js.

Подпись, переданная атрибутом, сильнее словаря (шаг 1 в Откуда берётся слово), поэтому при смене языка aria-label и другие подписи из атрибутов страница переставляет сама.

Пример переключателя

Переключатель выбирает русский, английский или арабский. Арабских слов компоненты не поставляют: пример регистрирует их для пагинации и тега, а для арабского ставит странице dir="rtl". Подписи, которые пример не перевёл, остаются английскими. Строка внизу показывает действующий язык и подпись кнопки удаления тега, которую видят вспомогательные технологии.

<div class="flex flex-col gap-2" data-language-demo>
  <div class="sf-button-group" role="group" aria-label="Язык интерфейса">
    <button type="button" class="sf-button sf-button--outline sf-button--on-surface sf-button--size-1/2" data-language="ru" data-direction="ltr" aria-pressed="true"><span class="sf-button-text-container">Русский</span></button>
    <button type="button" class="sf-button sf-button--outline sf-button--on-surface sf-button--size-1/2" data-language="en" data-direction="ltr" aria-pressed="false"><span class="sf-button-text-container">English</span></button>
    <button type="button" class="sf-button sf-button--outline sf-button--on-surface sf-button--size-1/2" data-language="ar" data-direction="rtl" aria-pressed="false"><span class="sf-button-text-container">العربية</span></button>
  </div>
  <sf-pagination aria-label="Страницы заказов" current="3" total="240" page-size="20" top="false"></sf-pagination>
  <div class="flex flex-wrap items-cross-center gap-1">
    <sf-tag kind="default" text="SIMAI Framework" closable></sf-tag>
  </div>
  <p class="m-0 color-on-surface-variant" role="status" data-language-result></p>
</div>

// Arabic is not shipped with the components: the page registers its words.
// Words it does not register fall back to English.
const registerArabic = () => {
  SF.language.registerAll('ar', {
    'sf-pagination': {
      pagesLabel: 'الصفحات:',
      totalLabel: 'المجموع:',
      previousLabel: 'الصفحة السابقة',
      nextLabel: 'الصفحة التالية',
      lastLabel: 'الأخيرة',
    },
    'sf-tag': {remove: 'إزالة'},
  });
};

const initializeLanguageSwitch = async () => {
  const root = document.querySelector('[data-language-demo]');
  if (!root || root.dataset.exampleReady === 'true') return;
  await Promise.all([customElements.whenDefined('sf-pagination'), customElements.whenDefined('sf-tag')]);
  root.dataset.exampleReady = 'true';
  registerArabic();

  const result = root.querySelector('[data-language-result]');
  // A label passed as an attribute is stronger than any dictionary, so the
  // page sets its own labels again on every switch.
  const pagination = root.querySelector('sf-pagination');
  const pageLabels = {ru: 'Страницы заказов', en: 'Order pages', ar: 'صفحات الطلبات'};
  const tag = root.querySelector('sf-tag');
  const report = () => {
    const label = tag.isConnected ? tag.closeLabel : '—';
    result.textContent = `Язык: ${SF.language.current()} · подпись кнопки удаления тега: «${label}»`;
  };

  // The switch chooses the components' language and sets the document's own
  // lang and dir: the explicit choice is stronger than the attribute, and
  // lang and dir serve assistive technology, :lang() styles and the layout.
  const switchLanguage = (code, direction) => {
    SF.language.use(code);
    pagination.setAttribute('aria-label', pageLabels[code] ?? pageLabels.en);
    document.documentElement.lang = code;
    document.documentElement.dir = direction;
    // Here the example sits in a documentation frame whose body carries its
    // own dir, so the example's root takes lang and dir too; on a page of
    // your own the document is enough.
    root.lang = code;
    root.dir = direction;
    root.querySelectorAll('[data-language]').forEach((button) => {
      button.setAttribute('aria-pressed', String(button.dataset.language === code));
    });
    requestAnimationFrame(report);
  };

  root.addEventListener('click', (event) => {
    const button = event.target.closest('[data-language]');
    if (button) switchLanguage(button.dataset.language, button.dataset.direction);
  });
  // A removed tag is the page's to remove: the component only asks.
  tag.addEventListener('close', () => tag.remove());
  switchLanguage('ru', 'ltr');
};

if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', initializeLanguageSwitch, {once: true});
} else {
  initializeLanguageSwitch();
}

Что важно заметить:

• SF.language, SF.pageLanguage и SF.pageText приходят с core.js и есть сразу после его выполнения, в том числе на странице без Smart-элементов (см. Когда доступен каждый SF.*). Регистрировать слова можно и после первой отрисовки: компоненты перерисуются сами.
• Перерисовку по языку получает каждый Smart-элемент, в том числе компонент проекта на SF.smart.SfBaseElement: базовый класс подписывает его на SF.language.onChange.
• use() не меняет атрибут lang, а изменение lang после загрузки компоненты не отслеживают. Чтобы сменить язык без перезагрузки, вызывайте SF.language.use(); SF.pageLanguage() и SF.pageText() учитывают явный выбор.
• Направление письма язык не задаёт: dir ставится отдельно (см. Начало и конец вместо левого и правого).
• Ключ слова — не имя атрибута. Подпись кнопки удаления у sf-tag задаёт атрибут close-label, а в словаре это слово remove. Ключ, которого у компонента нет, ничего не меняет: компонент показывает своё слово по порядку из Откуда берётся слово.

Ключи словарей компонентов. Слова регистрируются под именем тега:

Таблица собрана из словарей компонентов выпуска и полна: других встроенных слов, которые заменяются через SF.language, у компонентов нет.

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

SF.language.registerAll('ar', {
  'sf-tag': { remove: 'إزالة' },
  'sf-pagination': { previousLabel: 'الصفحة السابقة', nextLabel: 'الصفحة التالية' },
});

Что остаётся за проектом

Framework переводит только собственные слова компонентов. Проект сам отвечает за:

• данные: названия записей, разделов, вариантов выбора;
• форматы чисел и дат — их приложение передаёт уже отформатированными. Исключение — компоненты, которые сами показывают своё значение: календарь sf-datepicker пишет дату по маске format (цифры латинские, например DD.MM.YYYY), а названия месяцев и дней недели берёт из Intl на языке страницы;
• формы множественного числа.

Правила для нового компонента

• Свои слова компонент берёт через pageText; английское слово лежит в словаре, в записи en.
• Атрибут с подписью всегда важнее словаря. Слово читается так: this.getAttribute('close-label') || SF.pageText(TEXT, 'remove', this). Не берите слово из значения свойства по умолчанию: со значением 'Remove' компонент не отличит «атрибут не задан» от «задано английское слово» и на русской странице покажет английское. Значение по умолчанию у такого свойства — пустая строка.
• Компонент не читает язык браузера и не откатывается к русскому, если страница не назвала язык.
• Язык для форматирования дат и чисел внутри компонента берётся из того же правила, вместе с регионом (ru-RU), и учитывает явный выбор SF.language.use().

Смотрите также

• Направление текста — направление текста.
• Языки — краткая памятка по языкам и добавлению своего.
• Smart-компоненты — языковое поведение каждого компонента.