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.
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.falseotherwiseswitchers.style.full_name (default:
true) Display the full name of the language.falseto 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.falseto show it as a listswitchers.style.with_flags (default:
true) Display flags on switcher.falseotherwiseswitchers.style.flag_type (default:
rectangle_mat) Whenwith_flagsistrue, you can choose flag style option:shinysquarecirclerectangle_mat
switchers.style.invert_flags (default:
true) Whenis_dropdownisfalse, 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 tofalseto 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.
nullfor 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
}
}
],
}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)
{
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", // <form class="my-form">
search_parameter: "q" // it's the name value of your form's search input : <input name="q" />
}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.
// all other elements won't be translated
{
whitelist: [
{
value: ".my-translated-block"
},
{
value: ".my-another-block"
}
]
}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
{
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
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.
{
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
// 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 updated