Options

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