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:
1
Weglot.initialize(options)
Copied!
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.

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
1
{
2
switchers: [
3
{
4
// Same as button_style at root
5
style: {
6
full_name: true,
7
with_name: true,
8
is_dropdown: false,
9
with_flags: true,
10
flag_type: "circle",
11
invert_flags: false
12
},
13
// Move switcher somewhere in the page
14
location: {
15
target: ".header-nav",
16
sibling: null
17
}
18
}
19
],
20
}
Copied!

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)
1
{
2
translate_search: true, // Need to be true, otherwise search_forms is useless
3
search_forms: "form#side-search, form.search-form"
4
}
Copied!

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
1
{
2
translate_search: true,
3
search_forms: ".my-form", // <input name="q" class=".my-form" />
4
search_parameter: "q" // it's the name value of your form's search input
5
}
Copied!

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.
1
// all other elements won't be translated
2
{
3
whitelist: [
4
{
5
value: ".my-translated-block"
6
},
7
{
8
value: ".my-another-block"
9
}
10
]
11
}
Copied!

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
1
{
2
extra_definitions: [
3
{
4
type: 1, // Type of translation, 1 for text, others: https://developers.weglot.com/api/reference#wordtype
5
selector: "input.someclass[type=text]", // Selector to find element with attribute
6
attribute: "data-tooltip" // Name of attribute which is translated
7
}
8
]
9
}
Copied!
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.
1
{
2
extra_merged_selectors: ["code", ".wg-merged-nodes"]
3
}
Copied!

Examples

A full example could look like this:
1
// EXAMPLE VALUES, NOT DEFAULT
2
3
Weglot.initialize({
4
// Only mandatory value is api_key:
5
api_key: "wg_1234567897e2ea993d291b571c2ec93b0",
6
7
// Next are optionals, often editable on your Weglot dashboard.
8
// Options written here are concatenated with dashboard options when it's possible, otherwise these one have priority
9
10
// Manually design switcher
11
switchers: [
12
{
13
style: {
14
full_name: true,
15
with_name: true,
16
is_dropdown: false,
17
with_flags: true,
18
flag_type: "circle",
19
invert_flags: false
20
},
21
// Move switcher somewhere in the page
22
location: {
23
target: ".header-nav",
24
sibling: null
25
}
26
}
27
],
28
29
// Translate dynamics elements which appear later in page
30
dynamic: "#newsletterPopup,.dynamic-elements",
31
32
// Automatically redirect visitor by its navigator's language
33
auto_switch: true,
34
// If auto switch is true, but you don't have visitor's language, redirect on this language code, otherwise original language
35
auto_switch_fallback: "en",
36
37
// Only translate these blocks
38
whitelist: [
39
{
40
value: ".only-translate-me" // All other elements in the same page won't be translated anymore!
41
}
42
],
43
44
// Exclude some blocks from translation
45
excluded_blocks: [
46
{
47
value: ".no-translate" // All elements with this class won't be translated
48
}
49
],
50
// Exclude some path in website from translation
51
excluded_paths: [
52
{
53
value: "/blog",
54
type: "START_WITH" // IS_EXACTLY, CONTAIN, START_WITH, END_WITH, MATCH_REGEX
55
}
56
],
57
58
// Don't display default switcher, nothing else change, translation works. Useful with Auto-switch feature!
59
hide_switcher: false,
60
// Use front cache between pages, speed up your page loading!
61
cache: true,
62
63
// Shopify special options:
64
customer_tag: true, // Add a tag on your customer when they signup, 2-letter code eg. "EN"
65
order_tag: true, // Add a tag on your order when they are filled, 2-letter code eg. "EN"
66
67
// Translate search
68
translate_search: true, // Translate search keywords from visitors' language
69
search_parameter: "s", // Because my search input has name="s" attribute.
70
search_forms: "#sidebar-search, #main-search", // CSS selectors of <form> which contain search input
71
72
// Hide original text before loading translated one, true by default
73
wait_transition: true,
74
extra_definitions: [
75
{
76
type: 1, // Type of translation, 1 for text, others: https://developers.weglot.com/api/reference#wordtype
77
selector: "input.someclass[type=text]", // Selector to find element with attribute
78
attribute: "data-tooltip" // Name of attribute which is translated
79
}
80
],
81
82
remove_unused_link_hooks: true, // If some languages are disable, remove HTML element which contains #Weglot-xx links
83
84
extra_merged_selectors: ["code", ".wg-merged-nodes"]
85
});
Copied!
Last modified 14d ago