Options

This page describes options available for the Javascript integration.

As you've seen in the "Getting started" section, Weglot gets initialized through this code:

Weglot.initialize(options)

Where options is a Javascript object with properties defined as follows. Only api_key, (in bold) are required. Weglot uses the api_key to retrieve the link to your project and know what language to show on the language button. You can change options directly in your project settings : https://dashboard.weglot.com/projects/edit

You can also add in the option variable custom parameters that will change the default behavior of the library.

Options

api_key

Your Weglot API Key. Find it in your project settings : https://dashboard.weglot.com/projects/edit.

switchers

A Javascript Array of Objects representing several language switchers on the page

switchers.style

A javascript object describing the default styling of the Weglot language switcher button.

• switchers.style.with_name (default: true) Display a label text next to each language options. false otherwise

• switchers.style.full_name (default: true) Display the full name of the language.false to just show the 2-letter language code (eg. FR, ES, DE, EN...)

• switchers.style.is_dropdown (default: true) Display the language selector as a dropdown. false to show it as a list

• switchers.style.with_flags (default: true) Display flags on switcher. false otherwise

• switchers.style.flag_type (default: rectangle_mat) When with_flags is true, you can choose flag style option:

  • shiny

  • square

  • circle

  • rectangle_mat

• switchers.style.invert_flags (default: true) When is_dropdown is false , the switcher is a list. When you select a language, it has the same behavior as a dropdown: the selected one is always at first. You can set this option to false to disable this behavior and show a fixed list when language changed.

switchers.location

A Javascript Object to define position of your switcher in the page.

• switchers.location.target

  The CSS selector of the node that the switcher will be a child of

• switchers.location.sibling

  The CSS selector of the next sibling element of the switcher. null for the last element inside the target

{
    switchers: [
        {
            // Same as button_style at root
            style: {
                full_name: true,
                with_name: true,
                is_dropdown: false,
                with_flags: true,
                flag_type: "circle",
                invert_flags: false
            },
            // Move switcher somewhere in the page
            location: {
                target: ".header-nav",
                sibling: null
            }
        }
    ],
}

wait_transition

Default: true trueto prevent content blinking when translating a new page.

hide_switcher

Default: false true to prevent Weglot from creating language switchers, false otherwise. If you set it to true, it's your responsibility to use the Client-side API or link hooks to change languages on the page. It's also useful with the auto-switch option.

translate_search

Default: false true to translate search queries on the website, false otherwise. You need to add details to select forms to translate with search_forms & search_parameter options

search_forms

Default: "" A comma-separated list of CSS selectors of search form elements to watch for. Useful only if translate_search is true. The form has to send the q parameter for it to work (or the search_parameter, if present)

{
    translate_search: true, // Need to be true, otherwise search_forms is useless
    search_forms: "form#side-search, form.search-form"
}

search_parameter

Default: "" Name of the input in your form(s) which will send keywords.

Frequently, this is the parameter which contain your keywords in URL.For example, if you have "?q=xxxxx", it will be q

{
    translate_search: true,
    search_forms: ".my-form", // <form class="my-form">
    search_parameter: "q" // it's the name value of your form's search input : <input name="q" />
}

whitelist

Default: ""

An array of objects containing CSS selectors of elements you want to translate on your page. This will disable all others translations in the same page.

// all other elements won't be translated
{
    whitelist: [
        {
            value: ".my-translated-block"
        },
        {
            value: ".my-another-block"
        }
    ]
}

cache

Default: false

Setting this to true greatly improves user experience by caching Weglot's translations into your visitors' browser. Translations are kept up-to-date asynchronously.

extra_definitions

A Javascript Array of Objects representing extra translation definitions

extra_definitions.selector

A CSS selector to the element(s) you want to target

extra_definitions.attribute

The name of the attribute you'd like to translate

extra_definitions.type

Default: 1

Optional. The WordType of the text that you'd like to translate

{
  extra_definitions: [
      {
        type: 1, // Type of translation, 1 for text, others: https://developers.weglot.com/api/reference#wordtype
        selector: "input.someclass[type=text]", // Selector to find element with attribute
        attribute: "data-tooltip" // Name of attribute which is translated
      }
   ]
 }

remove_unused_link_hooks

Default: false

If you use link hooks you may have some excluded pages, so your links will be inactive with anchors #Weglot-xx. Turn this option to true and we'll remove this HTML links.

extra_merged_selectors

Array of CSS selectors to merge your own HTML nodes in your translations. More information here about translation engine.

{
    extra_merged_selectors: ["code", ".wg-merged-nodes"]
}

Examples

A full example could look like this:

// EXAMPLE VALUES, NOT DEFAULT

Weglot.initialize({
  // Only mandatory value is api_key:
  api_key: "wg_1234567897e2ea993d291b571c2ec93b0",
  
  // Next are optionals, often editable on your Weglot dashboard.
  // Options written here are concatenated with dashboard options when it's possible, otherwise these one have priority
  
  // Manually design switcher
  switchers: [
    {
      style: {
        full_name: true,
        with_name: true,
        is_dropdown: false,
        with_flags: true,
        flag_type: "circle",
        invert_flags: false
      },
      // Move switcher somewhere in the page
      location: {
        target: ".header-nav",
        sibling: null
      }
    }
  ],
  
  
  // Automatically redirect visitor by its navigator's language
  auto_switch: true,
  // If auto switch is true, but you don't have visitor's language, redirect on this language code, otherwise original language
  auto_switch_fallback: "en",
  
  // Only translate these blocks
  whitelist: [
    {
      value: ".only-translate-me" // All other elements in the same page won't be translated anymore!
    }
  ],
  
  // Exclude some blocks from translation
  excluded_blocks: [
    {
      value: ".no-translate" // All elements with this class won't be translated
    }
  ],
  // Exclude some path in website from translation
  excluded_paths: [
    {
      value: "/blog",
      type: "START_WITH" // IS_EXACTLY, CONTAIN, START_WITH, END_WITH, MATCH_REGEX
    }
  ],
  
  // Don't display default switcher, nothing else change, translation works. Useful with Auto-switch feature!
  hide_switcher: false,
  // Use front cache between pages, speed up your page loading!
  cache: true,
  
  // Shopify special options:
  customer_tag: true, // Add a tag on your customer when they signup, 2-letter code eg. "EN"
  order_tag: true, // Add a tag on your order when they are filled, 2-letter code eg. "EN"
  
  // Translate search
  translate_search: true, // Translate search keywords from visitors' language
  search_parameter: "s", // Because my search input has name="s" attribute.
  search_forms: "#sidebar-search, #main-search", // CSS selectors of <form> which contain search input
  
  // Hide original text before loading translated one, true by default
  wait_transition: true,
  extra_definitions: [
    {
      type: 1, // Type of translation, 1 for text, others: https://developers.weglot.com/api/reference#wordtype
      selector: "input.someclass[type=text]", // Selector to find element with attribute
      attribute: "data-tooltip" // Name of attribute which is translated
    }
  ],
  
  remove_unused_link_hooks: true, // If some languages are disable, remove HTML element which contains #Weglot-xx links
  
  extra_merged_selectors: ["code", ".wg-merged-nodes"]
});