Options

This page describes options

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.

Property

Description

Default

Example

api_key

Your Weglot API Key

""

dynamic

CSS selectors to translate dynamic elements

""

dynamic: "#cookie-consent,.my-class"

button_style

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

button_style["with_name"]

true to display a label text next to each language options. false otherwise

true

button_style["full_name"]

If withname is true, true to display the full name of the language.false to just show the 2-letter language code

true

button_style["is_dropdown"]

true to display the language selector as a dropdown. false to show it as a list

true

button_style["with_flags"]

. The extra CSS class to apply to the button elements. Add wg-flags to show flags (by default they will be mat rectangles).

true

button_style["flag_type"]

When with_flagsis true, you can choose flag style:

  • 1: shine rectangle

  • 2: square

  • 3: circle

  • 4: mat rectangle

4

wait_transition

true to prevent content blinking when translating a new page.

true

hide_switcher

true to prevent Weglot from creating language switchers, false otherwise. Defaults to false. 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

false

translate_search

true to translate search queries on the website, false otherwise.

false

search_forms

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

""

"form#side-search, form.search-form"

search_parameter

Name of the input in your form(s) which will send keywords. Frequently, this is the parameter which contain your keywords in URL "?q=xxxxx"

"q"

whitelist

A comma-separated list of CSS selectors of only elements you want to translate on your page. This will cancel all others translations in the same page.

""

".checkout-banner, .product-name"

translate_images

true to translate images' URLs on the website, false otherwise

true

cache

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

false

switchers

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

[]

switchers[]["styleOpt"]

A Javascript Object defined exactly like styleOpt

switchers[]["target"]

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

".site-header__section--title"

switchers[]["sibling"]

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

null

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

"input.someclass[type=text]"

extra_definitions[]["attribute"]

The name of the attribute you'd like to translate

"data-tooltip"

extra_definitions[]["type"]

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

1

2

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
// Customizing floating default switcher
button_style : {
full_name: true, // false is only 2-letter code (EN, FR, ES...)
with_name: true,
is_dropdown: true, // false is a list, all languages visible
with_flags: true,
flag_type: 4 // 1: shiny, 2: square, 3: circle, 4: mat rectangle
},
// Translate dynamics elements which appear later in page
dynamic: "#newsletterPopup,.dynamic-elements",
// 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",
// 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
hide_switcher: false,
// Use front cache between pages
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
// Multiple switchers
switchers: [
{
// Same as button_style at root
button_style:{
full_name: true,
with_name: true,
is_dropdown: true,
with_flags: true,
flag_type: 4
},
// Move switcher somewhere in the page
target: ".header-nav",
sibling: null
}
],
// 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
selectors: "input.someclass[type=text]", // Selector to find element with attribute
attribute: "data-tooltip" // Name of attribute which is translated
}
]
});