Localization

Run the SearchX widget in your customers' language.

Overview

SearchX ships translations for six languages and renders in the one you pick — no configuration beyond a single setting. If you need a language we don't ship, or you want to reword our copy, you can supply your own locale file instead.

Only English is bundled into the SDK JavaScript. Every other language is fetched at runtime from https://sdk.searchxengine.ai/locales/{{lng}}.json, so adding a language costs you nothing in bundle size.

Built-in languages

Set the widget language with defaultLanguage:

SearchXSDK.init({
  app_id: 'YOUR_APP_ID',
  api_key: 'YOUR_API_KEY',
  components: {
    /* … */
  },
  defaultLanguage: 'bg',
});

You can also set the language from the SearchX dashboard. The dashboard value wins — it is applied after the widget boots, so it overrides whatever the init script passed. Leave defaultLanguage out of both and the SDK falls back to English.

Custom translations

Two ways to override the built-in copy — for a language we don't ship, or to reword ours.

Inline

Pass the strings directly with customLocale. Best when you only need to change a handful of labels.

SearchXSDK.init({
  // … other config
  defaultLanguage: 'el',
  customLocale: {
    el: {
      searches: {
        searchPlaceholder: 'Ψάξε στο κατάστημά μας…',
      },
      buttons: {
        addToCart: 'ΑΓΟΡΑ',
      },
    },
  },
});

Hosted file

Point customLocaleUrl at your own JSON. The {{lng}} placeholder is replaced with the active language code, so one URL serves every language you host.

SearchXSDK.init({
  // … other config
  customLocaleUrl: 'https://cdn.example.com/locales/{{lng}}.json',
  defaultLanguage: 'fr',
});

The file must be publicly reachable and served as application/json. This is also configurable from the dashboard, which again takes precedence over the init script.

Locale file reference

The full English file is the canonical source: sdk.searchxengine.ai/locales/en.json. Copy it and translate the values. The structure is:

{
  "brands": "Brands",
  "categories": "Categories",
  "sizes": "Sizes",
  "colors": "Colors",
  "priceRange": "Price range",
  "onSale": "On Sale",
  "showMore": "Show more",
  "showLess": "Show less",
  "search": "Search",
  "openFacets": "Filters",
  "close": "Close",
  "apply": "Apply",
  "filters": "Filters",
  "clearFilters": "Clear filters",
  "buttons": {
    "addToCart": "PURCHASE",
    "addToWishlist": "Add to Wish List"
  },
  "searches": {
    "results": "Search Results",
    "resultsFor": "Results for \"{{query}}\"",
    "searchPlaceholder": "Search for products…",
    "noResultsFor": "No results found for \"{{query}}\"",
    "recentSearches": "Recent searches",
    "topSearches": "Top Searches",
    "productsPerPage": "Products per page",
    "sortingBy": "Sorting by",
    "pagination": {
      "prev": "Previous page",
      "next": "Next page",
      "page": "Page {{page}}",
      "pageOf_one": "Page {{page}} of {{total}} page",
      "pageOf_other": "Page {{page}} of {{total}} pages"
    },
    "sort": {
      "relevance": "Relevance",
      "priceAsc": "Price: Low to High",
      "priceDesc": "Price: High to Low"
    },
    "aiSearchBadge": "AI Search",
    "voiceTooltip": "Search by voice"
  },
  "products": {
    "count_one": "{{count}} product",
    "count_other": "{{count}} products"
  }
}

Abridged — the real file also carries the settings and playground blocks, which only appear in the admin preview.

Placeholders

{{query}}, {{page}}, {{total}} and {{count}} are substituted at render time. Keep them exactly as written; a translated or missing placeholder renders literally.

Plurals

Keys ending _one and _other are plural forms, selected automatically from {{count}}. Both are required.

"count_one": "{{count}} product",
"count_other": "{{count}} products"

Languages with more plural categories than English (Romanian, Arabic, Polish) currently collapse to these two forms.

Language switching

The SDK reads the language once, at init. There is no runtime language-switch API — to change it, re-initialise the widget with a different defaultLanguage.

On most storefronts the page reloads when the shopper changes language, so the simplest approach is to pass your platform's active language straight into the init script. On OpenCart, initOpenCart() accepts defaultLanguage and forwards it:

SearchXSDK.initOpenCart({
  app_id: 'YOUR_APP_ID',
  api_key: 'YOUR_API_KEY',
  defaultLanguage: '{{ language_code }}', // your template's active language
});

Render the value server-side from whatever your theme exposes, so the widget boots in the same language as the rest of the page.

Dashboard-driven translations

Some widget content comes from the SearchX dashboard rather than your locale file, and is translated per language there:

• Suggested Links — each promotional chip has one URL and a title per language.
• AI Search chips — the prompt suggestions inside the AI Search panel.

Both use a Translate modal per item, offering the same six languages listed above. English is the canonical fallback: leave a language blank and the widget shows the English text. The active language is picked at render time, so there is nothing to configure on the integration side.

Greek uppercase and accents

In Greek, words written in uppercase traditionally drop their accents (Φλεβών → ΦΛΕΒΩΝ, not ΦΛΕΒΏΝ). Browsers apply this automatically under text-transform: uppercase, but only when the element carries lang="el".

The widget sets lang on its root container from the active language, so headings and labels work out of the box. Facet labels coming from your catalogue are handled too: when the widget detects Greek characters it stamps lang="el" on those items individually, so a Greek catalogue uppercases correctly even under an English interface.

/* Uppercase brand names on cards — Greek accents strip correctly */
.searchx__page.searchx__theme .searchx__page-item-brand {
  text-transform: uppercase;
}

This works as long as your CSS uses text-transform: uppercase rather than a JavaScript transform. See Widget Styling: Greek typography.