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.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
) Whenwith_flags
istrue
, you can choose flag style option:shiny
square
circle
rectangle_mat
- switchers.style.invert_flags (default:
true
) Whenis_dropdown
isfalse
, 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 tofalse
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.targetThe CSS selector of the node that the switcher will be a child of
- switchers.location.siblingThe 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
}
}
],
}
Default:
true
true
to prevent content blinking when translating a new page.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
optionsDefault:
""
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"
}
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" />
}
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"
}
]
}
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.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
{
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
}
]
}
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.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"]
}
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"]
});
Last modified 4mo ago