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.

dynamic

CSS selectors to translate dynamic elements which are not translated yet. Separated by a comma.

button_style

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

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

button_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...)

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

button_style.with_flags (default: true) Display flags on switcher. false otherwise

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

  • shiny

  • square

  • circle

  • rectangle_mat

button_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.

// These are default values
{
button_style: {
with_name: true, // false is only 2-letter code (EN, FR, ES...)
full_name: true,
is_dropdown: true, // false is a list, all languages visible
with_flags: true,
flag_type: "rectangle_mat", // shiny, square, circle, rectangle_mat,
invert_flags: true // display selected language in first. true by default, only effective on list style
}
}

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.

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", // <input name="q" class=".my-form" />
search_parameter: "q" // it's the name value of your form's search input
}

whitelist

Default: ""

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

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

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.

switchers

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

switchers.button_style

A Javascript Object defined exactly like button_style

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
button_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
}
}
],
}

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
}
]
}

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
// 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: "rectangle_mat" // shiny, square, circle, rectangle_mat,
invert_flags: true // display selected language in first. true by default, only effective on list style
},
// 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, 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
// Multiple switchers
switchers: [
{
// Same as button_style at root
button_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
}
}
],
// 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
}
],
extra_merged_selectors: ["code", ".wg-merged-nodes"]
});