If your website is available in different languages, for example English and Ukrainian, you can make the HelpCrunch widget follow the language of the current page. To do this, create a separate localization for each language and select the required Phrase List with the setLocalization JavaScript API method.
Before you start
Open your website widget settings and go to the Localization tab. Make sure you have enabled the required Phrase Lists:
-
en for English;
-
uk for Ukrainian.
The examples below assume that your Phrase Lists are named en and uk. If you use different names, replace these values in the code with the exact names of your Phrase Lists.
Note: The standard language code for Ukrainian is uk, not ua (see full list of ISO 639-1 codes). Your Ukrainian website can still use yourdomain.com/ua/ in its URL – you only need to map ua in the URL to the uk Phrase List.
You can learn more about creating Phrase Lists in this localization guide.
Recommended option: use the page language
The most reliable option is to read the language from the lang attribute of the webpage:
<html lang="en">
on English pages and:
<html lang="uk">
on Ukrainian pages.
Then add the following code immediately after the standard HelpCrunch widget code:
const pageLanguage = document.documentElement.lang
.toLowerCase()
.split(/[-_]/)[0];
const helpCrunchLanguage =
pageLanguage === 'uk' || pageLanguage === 'ua' ? 'uk' : 'en';
HelpCrunch('setLocalization', helpCrunchLanguage);
This option works regardless of the website URL structure. It also supports values such as en-US and uk-UA.
If both language versions have a language code in the URL
For example:
-
yourdomain.com/en/pricing -
yourdomain.com/ua/pricing
Use the first URL segment to select the localization:
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);
This code maps /en/ to the en Phrase List and /ua/ or /uk/ to the uk Phrase List. English is used as a fallback for URLs that do not contain a recognized language code.
If English pages do not have a language code
For example:
-
yourdomain.com/pricing -
yourdomain.com/ua/pricing
Check whether the URL starts with the Ukrainian path:
const path = window.location.pathname.toLowerCase();
const isUkrainianPage = path === '/ua' || path.startsWith('/ua/');
HelpCrunch('setLocalization', isUkrainianPage ? 'uk' : 'en');
The Ukrainian localization will be displayed on /ua and all pages inside /ua/. All other pages will use English.
If your website uses /uk/ instead, replace ua with uk in the condition.
If different subdomains are used
For example:
-
en.yourdomain.com -
ua.yourdomain.com
You can detect the language from the hostname:
const hostname = window.location.hostname.toLowerCase();
const isUkrainianPage =
hostname.startsWith('ua.') || hostname.startsWith('uk.');
HelpCrunch('setLocalization', isUkrainianPage ? 'uk' : 'en');
If you use completely different domains for each language, check the full hostname instead:
const ukrainianDomains = ['yourdomain.ua', 'www.yourdomain.ua'];
const isUkrainianPage = ukrainianDomains.includes(
window.location.hostname.toLowerCase()
);
HelpCrunch('setLocalization', isUkrainianPage ? 'uk' : 'en');
If the language is not included in the URL
When English and Ukrainian pages have the same URL pattern, the URL cannot be used to determine the language. In this case, use one of the following values:
-
the page’s <html lang> attribute;
-
the current language provided by your CMS;
-
the current locale stored by your website or application.
Using the <html lang> attribute is usually the simplest option. Make sure your CMS outputs lang="en" on English pages and lang="uk" on Ukrainian pages, and use the recommended code from the beginning of this article.
You can use the navigator.language for this scenario, but It detects the visitor’s browser language, which may be different from the language of the page they selected.
CMS examples
WordPress, WPML, or Polylang
WordPress and multilingual plugins normally update the <html lang> attribute for each language version. If the rendered page contains the correct lang="en" or lang="uk" value, use the recommended page-language code without any WordPress-specific changes.
If you add the localization directly to a PHP theme template, you can pass the current WordPress locale to JavaScript:
<script>
const wordpressLanguage =
<?php echo wp_json_encode(substr(get_locale(), 0, 2)); ?>;
HelpCrunch(
'setLocalization',
wordpressLanguage === 'uk' ? 'uk' : 'en'
);
</script>
Add PHP code only to a theme or plugin file that processes PHP. It will not work inside a plain JavaScript field.
Shopify
Shopify exposes the current storefront language through request.locale.iso_code. Add this to the theme after the HelpCrunch widget code:
<script>
const shopifyLanguage = {{ request.locale.iso_code | json }};
HelpCrunch(
'setLocalization',
shopifyLanguage.toLowerCase().startsWith('uk') ? 'uk' : 'en'
);
</script>
Webflow and other website builders
If the platform sets the correct <html lang> value, use the recommended page-language code. Otherwise, use the URL-based option that matches your website structure.
If you install HelpCrunch through Google Tag Manager, keep the widget code and localization logic in the same Custom HTML tag or make sure the localization code runs after the tag that defines HelpCrunch.
Single-page applications (SPA)
If your React, Vue, Angular, or another single-page application changes languages without reloading the page, call setLocalization during the initial widget setup and whenever the application locale changes:
function updateHelpCrunchLocalization(locale) {
const language = String(locale)
.toLowerCase()
.split(/[-_]/)[0];
HelpCrunch(
'setLocalization',
language === 'uk' || language === 'ua' ? 'uk' : 'en'
);
}
updateHelpCrunchLocalization(currentLocale);
Call the same function again after the user selects another language:
updateHelpCrunchLocalization(newLocale);
If your language switcher reloads the whole page, the initial call on every page load is enough.
Where should I place the code?
Add the setLocalization call:
-
On every language version of your website.
-
Immediately after the standard HelpCrunch widget code has defined the HelpCrunch function.
-
Before a visitor opens the widget.
Only call setLocalization once during a regular page load. In a single-page application, call it again only when the application language changes.
See the setLocalization method reference for more details.
How to test the setup
-
Open an English page and check that the widget is displayed in English.
-
Open the matching Ukrainian page and check that the widget is displayed in Ukrainian.
-
Test both pages in an incognito window to avoid cached website data.
-
If the wrong localization appears, check the Phrase List names, the page’s lang attribute, and the URL value used by your condition.
If the Phrase List name passed to setLocalization does not match an available localization, the widget will use the default localization instead.
