Як налаштувати локалізацію віджета для кожної мовної версії вашого сайту

Англійська локалізація для сторінок /en, німецька — для /de тощо...

Написано Konstantine

Оновлено 4 дні тому

Якщо ваш сайт доступний різними мовами, наприклад англійською та українською, ви можете налаштувати віджет HelpCrunch так, щоб він відображався мовою поточної сторінки. Для цього створіть окрему локалізацію для кожної мови та виберіть потрібний список фраз за допомогою методу JavaScript API setLocalization

Перед початком

Відкрийте налаштування віджета для сайту та перейдіть на вкладку Локалізація. Переконайтеся, що потрібні списки фраз увімкнено:

en для англійської;
uk для української.

У наведених нижче прикладах передбачається, що ваші списки фраз мають назви en та uk. Якщо ви використовуєте інші назви, замініть ці значення в коді точними назвами ваших списків фраз.

Примітка: Стандартний код мови для української – uk, а не ua (див.повний список кодів ISO 639-1). Українська версія вашого сайту все одно може використовувати yourdomain.com/ua/ у своїй URL-адресі – вам потрібно лише зіставити ua в URL-адресі зі списком фраз uk.

Докладніше про створення списків фраз можна дізнатися в інструкції з локалізації.

Рекомендований варіант: використовуйте мову сторінки

Найнадійніший варіант – зчитувати мову з атрибута lang вебсторінки:

<html lang="en">

на англомовних сторінках та:

<html lang="uk">

на україномовних сторінках.

Потім додайте наведений нижче код одразу після стандартного коду віджета HelpCrunch:

const pageLanguage = document.documentElement.lang
  .toLowerCase()
  .split(/[-_]/)[0];

const helpCrunchLanguage =
  pageLanguage === 'uk' || pageLanguage === 'ua' ? 'uk' : 'en';

HelpCrunch('setLocalization', helpCrunchLanguage);

Цей варіант працює незалежно від структури URL-адрес вашого сайту. Він також підтримує такі значення, як en-US та uk-UA.

Якщо обидві мовні версії мають код мови в URL-адресі

Наприклад:

yourdomain.com/en/pricing
yourdomain.com/ua/pricing

Використовуйте перший сегмент URL-адреси, щоб вибрати локалізацію:

const firstPathSegment = window.location.pathname
  .split('/')
  .filter(Boolean)[0]
  ?.toLowerCase();

const languageMap = {
  en: 'en',
  ua: 'uk',
  uk: 'uk',
};

const helpCrunchLanguage = languageMap[firstPathSegment] || 'en';

HelpCrunch('setLocalization', helpCrunchLanguage);

Цей код зіставляє /en/ зі списком фраз en, а /ua/ або /uk/ — зі списком фраз uk. Англійська використовується як резервна мова для URL-адрес, які не містять розпізнаного коду мови.

Якщо англомовні сторінки не мають коду мови

Наприклад:

yourdomain.com/pricing
yourdomain.com/ua/pricing

Перевірте, чи починається URL-адреса з шляху української версії:

const path = window.location.pathname.toLowerCase();
const isUkrainianPage = path === '/ua' || path.startsWith('/ua/');

HelpCrunch('setLocalization', isUkrainianPage ? 'uk' : 'en');

Українська локалізація відображатиметься на /ua та на всіх сторінках у розділі /ua/. На всіх інших сторінках використовуватиметься англійська.

Якщо ваш сайт натомість використовує /uk/, замініть ua на uk в умові.

Якщо використовуються різні субдомени

Наприклад:

en.yourdomain.com
ua.yourdomain.com

Мову можна визначити за hostname:

const hostname = window.location.hostname.toLowerCase();
const isUkrainianPage =
  hostname.startsWith('ua.') || hostname.startsWith('uk.');

HelpCrunch('setLocalization', isUkrainianPage ? 'uk' : 'en');

Якщо для кожної мови ви використовуєте повністю різні домени, перевіряйте повний hostname:

const ukrainianDomains = ['yourdomain.ua', 'www.yourdomain.ua'];
const isUkrainianPage = ukrainianDomains.includes(
  window.location.hostname.toLowerCase()
);

HelpCrunch('setLocalization', isUkrainianPage ? 'uk' : 'en');

Якщо мову не вказано в URL-адресі

Якщо англомовні та україномовні сторінки мають однаковий формат URL-адрес, визначити мову за URL-адресою неможливо. У такому разі використовуйте одне з наведених нижче значень:

атрибут <html lang> сторінки
поточну мову, яку надає ваша CMS
поточну локаль, збережену вашим сайтом або застосунком

Зазвичай найпростіший варіант — використовувати атрибут <html lang>. Переконайтеся, що ваша CMS виводить lang="en" на англомовних сторінках і lang="uk" на україномовних, а потім скористайтеся рекомендованим кодом із початку цієї статті.

Для цього сценарію можна використовувати navigator.language, але він визначає мову браузера відвідувача, яка може відрізнятися від вибраної ним мови сторінки.

Приклади для CMS

WordPress, WPML або Polylang

WordPress і багатомовні плагіни зазвичай оновлюють атрибут <html lang> для кожної мовної версії. Якщо згенерована сторінка містить правильне значення lang="en" або lang="uk", використовуйте рекомендований код, який визначає мову сторінки, без жодних змін для WordPress.

Якщо ви додаєте локалізацію безпосередньо до PHP-шаблону теми, ви можете передати поточну локаль WordPress до JavaScript:

<script>
  const wordpressLanguage =
    <?php echo wp_json_encode(substr(get_locale(), 0, 2)); ?>;

  HelpCrunch(
    'setLocalization',
    wordpressLanguage === 'uk' ? 'uk' : 'en'
  );
</script>

Додавайте PHP-код лише до файлу теми або плагіна, який обробляє PHP. Він не працюватиме у звичайному полі для JavaScript.

Shopify

Shopify надає поточну мову сайту через request.locale.iso_code. Додайте цей код до теми після коду віджета HelpCrunch:

<script>
  const shopifyLanguage = {{ request.locale.iso_code | json }};

  HelpCrunch(
    'setLocalization',
    shopifyLanguage.toLowerCase().startsWith('uk') ? 'uk' : 'en'
  );
</script>

Webflow та інші конструктори сайтів

Якщо платформа встановлює правильне значення <html lang>, використовуйте рекомендований код, який визначає мову сторінки. В іншому разі скористайтеся варіантом на основі URL-адреси, який відповідає структурі вашого сайту.

Якщо ви встановлюєте HelpCrunch через Google Tag Manager, розмістіть код віджета й логіку локалізації в одному тегу Custom HTML або переконайтеся, що код локалізації виконується після тегу, який визначає HelpCrunch.

Односторінкові застосунки (SPA)

Якщо ваш односторінковий застосунок на React, Vue, Angular або іншому фреймворку змінює мову без перезавантаження сторінки, викликайте setLocalization під час початкового налаштування віджета та щоразу, коли змінюється локаль застосунку:

function updateHelpCrunchLocalization(locale) {
  const language = String(locale)
    .toLowerCase()
    .split(/[-_]/)[0];

  HelpCrunch(
    'setLocalization',
    language === 'uk' || language === 'ua' ? 'uk' : 'en'
  );
}

updateHelpCrunchLocalization(currentLocale);

Викличте ту саму функцію ще раз після того, як користувач вибере іншу мову:

updateHelpCrunchLocalization(newLocale);

Якщо перемикач мов перезавантажує всю сторінку, достатньо початкового виклику під час кожного завантаження сторінки.

Де розмістити код локалізації?

Додайте виклик setLocalization:

На кожній мовній версії вашого сайту.
Одразу після того, як стандартний код віджета HelpCrunch визначить функцію HelpCrunch.
Перш ніж відвідувач відкриє віджет.

Під час звичайного завантаження сторінки викликайте setLocalization лише один раз. В односторінковому застосунку викликайте його повторно лише тоді, коли змінюється мова застосунку.

Докладнішу інформацію див. у довідці про метод setLocalization.

Як перевірити налаштування

Відкрийте англомовну сторінку та перевірте, чи віджет відображається англійською.
Відкрийте відповідну україномовну сторінку та перевірте, чи віджет відображається українською.
Перевірте обидві сторінки у вікні інкогніто, щоб уникнути впливу кешованих даних сайту.
Якщо відображається неправильна локалізація, перевірте назви списків фраз, атрибут lang сторінки та значення URL-адреси, яке використовується у вашій умові.

Якщо назва списку фраз, передана до setLocalization, не відповідає жодній доступній локалізації, віджет використає локалізацію за замовчуванням.

Чи була наша стаття корисною?