TURBO for Developers

Home > widget-integration > FilterTranslationService

FilterTranslationService class

Service for managing filter translations and applying them to filter UI elements.

This service handles translation of filter options, labels, and UI text using the app's translation configuration. It supports nested translation keys, template variable replacement, and automatic XSS sanitization. It can be extended by Technical Support teams to customize translation behavior for specific shops or languages.

Signature:

export declare class FilterTranslationService

Remarks

The service works with FilterStore to apply translations to both filter options and selected filters. It generates CSS selectors to locate and update filter UI elements dynamically. Translation keys support dot notation for nested objects.

Example

Extend to add custom translation fallback logic:

window.boostWidgetIntegration.extend('FilterTranslationService', (FilterTranslationService) => {
  return class CustomFilterTranslationService extends FilterTranslationService {
    translateByKey(key, defaultValue) {
      // Try primary language
      let translated = super.translateByKey(key, defaultValue);
      // Fallback to secondary language if not found
      if (translated === defaultValue) {
        translated = this.getSecondaryLanguageTranslation(key, defaultValue);
      }
      return translated;
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(appService, filterStore, filterHelper)		Constructs a new instance of the `FilterTranslationService` class

Methods

Method	Modifiers	Description
applyTranslationsToFilterOptions()		Applies translations to all filter options in the current filter state. Iterates through all filter options in the filter state, retrieves their translated labels, sanitizes them for XSS prevention (unless disabled in config), and updates the corresponding DOM elements. Finally updates the filter state with the translated labels.
applyTranslationsToRefineBy(selectedFilters)		Applies translations to the "refine by" selected filters display. Updates the labels of selected filters with their translated values. This is used to display translated filter names in the active filters / "refine by" section of the UI.
buildTranslationKey(filterId, optionKey)		Builds a standardized translation key for a filter option. Constructs a key in the format 'filterOption\|{filterId}\|{optionKey}' used to look up translations in the filterOptions translation object.
getNestedTranslation(key, translations, defaultLabel)		Traverses a nested object structure to retrieve a translation value. Splits the key by dots and traverses the translations object step by step. Returns the default label if any part of the path doesn't exist or if the final value is not a string.
getToggleSelector(id, suffix)		Generates a CSS selector for a filter toggle element. Sanitizes the ID by replacing colons with underscores and properly escapes special characters for use in CSS selectors. Appends the configured suffix (default: '-toggle') to create the final selector.
getTranslatedFilterOption(filterState, key, defaultValue)		Retrieves a translated filter option label from the app's translation configuration. Builds a translation key in the format 'filterOption\|{filterId}\|{optionKey}' and looks it up in the filterOptions translation object. Falls back to the provided default value or the original key if translation is not found.
setElementText(el, newText)		Updates the text content of an HTML element while preserving child elements. This method finds and updates only text nodes within an element, leaving child HTML elements intact. If no text node exists, it creates one as the first child. Also updates aria-label attributes for accessibility.
translate(element, key, defaultValue)		Translates and updates the text content of an HTML element. Convenience method that combines `translateByKey` and `setElementText`. Looks up the translation for the given key and applies it to the element.
translateByKey(key, defaultValue)		Retrieves a translated string by its key from the app's translation configuration. Supports nested keys using dot notation (e.g., 'filter.title.color'). Returns the default value if the key is not found in translations or is invalid.
translateWithComponent(str, obj)		Replaces template variables in a string with values from an object. Finds all {{key}} patterns in the string and replaces them with corresponding values from the provided object. Whitespace around keys is trimmed. Unknown keys are left unchanged in their original {{key}} format.

← Back to Library Reference