Frontend API: Initialization

This page details the options available when initializing the Localize code snippet.

• Check out the Quickstart for Web guide for step-by-step instructions for adding our client-side JavaScript library to your site.
• See the Frontend API: Methods page for the available methods in the Localize object after the Localize.initialize() method has been called.

This is the Localize snippet with the default library options.

<script src="https://global.localizecdn.com/localize.js"></script>

<script>(function(a){if(!a.Localize){a.Localize={};for(var e=["translate","untranslate","phrase","initialize","translatePage","setLanguage","getLanguage","detectLanguage","getAvailableLanguages","untranslatePage","bootstrap","prefetch","on","off","hideWidget","showWidget","getSourceLanguage"],t=0;t<e.length;t++)a.Localize[e[t]]=function(){};}})(window);</script>

<script>
  Localize.initialize({
    key: '[[app:key]]', 
    rememberLanguage: true,
    // other options go here, separated by commas
  });
</script>

The following are the available options for the initialize() method.

📘

NOTE: All option names are case-sensitive!!

Only the first option is required, all others are optional.

key

Required. Your Project Key. Find it here.

allowInlineBreakTags

Defaults to false.
If true, whenever you have a <BR> element in your content, Localize will not break up the parent element's content but instead will keep all sibling child elements together in the parent or containing element.

Example:
With the allowInlineBreakTags set to false, the source phrase:

<div>
  Hello George! How was your first day as a CIT?<br>
  I hope it wasn't too <span style="color: red">hot</span> for you!
</div>

...will be brought into your dashboard as the following phrases:

1. Hello George! How was your first day as a CIT?
2. I hope it wasn't too
3. {{1}}hot{{/1}}
4. for you!

With the allowInlineBreakTags set to true, the source phrase above will be brought into your dashboard as the following phrase:

1. Hello George! How was your first day as a {{1}}CIT{{/1}}?{{2}}{{/2}} I hope it wasn't too {{3}}hot{{/3}} for you!

autoApprove

Defaults to false.
If true and you have machine translations enabled, any new phrases found in your website will be automatically moved to the Published bin, and a machine translation will be generated.

autodetectLanguage

Defaults to true.
Automatically set the language to the detected language.
Read about this option in more detail here...

🚧

Overrides Project Setting

This setting overrides the one in the Project Settings: Library Settings.

basePath

This specifies the 'base' or 'root' path of your application. This will be stripped from the URL of the phrase when seen in the "Filter by pages" feature. For example:

• full URL = https://example.com/one/two/three
• basePath = https://example.com/one
• relative path = /two - phrases will be found by Localize in pages starting at this relative path and in any subfolders contained within this folder
• If not specified, the default value would be https://example.com in the example above.

blockedClasses

An array of CSS class selectors.
When applied, any phrase(s) contained inside an HTML element with the class(es) will not be brought into the Localize dashboard, allowing you to filter out your unwanted content.
Conversely, if you add a class to this list after there is already content in the Localize dashboard, Localize will not display any translations within that HTML element, even if they exist.

blockedClasses: ['admin-mode', 'editing-mode']

blockedIds

An array of CSS ID selectors.
When applied, any phrase(s) contained inside an HTML element with one of the ID(s) will not be brought into the Localize dashboard, allowing you to filter out your unwanted content.
If you add an ID to this list after there is already content in the Localize dashboard, Localize will not display any translations within that HTML element, even if they exist.

defaultLanguage

defaultLanguage: ‘LANG_CODE’
Localize will set the initial language on your website to LANG_CODE. Language codes can be found here.

Defaults to the source language of your website.

🚧

Overrides Browser Language Choice

Note that if you set the defaultLanguage option, this will override any language preference that the user has set in their browser.

disableWidget

Defaults to false.
When true, the default Localize language-switching widget is hidden in your web pages (via CSS).

• Note: This won't remove the widget from the DOM, it just hides it from view.
• Note: If you have the Widget Customization setting set to NOT display the widget, then setting disableWidget to false still won't display the widget (after all, 2 falses don't make a true!).
• If you want the widget enabled on some pages but disabled on others, you can use the Localize.showWidget() and Localize.hideWidget() functions. Just be sure to call either of these functions after you've called Localize.initialize().

🚧

Overrides Project Setting

This option overrides the Widget Customization setting in the Project.

enabledLanguages

An array of language codes that determine which target languages should be shown on the default Localize language-switching widget.

enabledLanguages: ['es', 'fr'],

In the example above, only Spanish (es) and French (fr) will be shown on the language-switching widget. This option allows you to programmatically set the available languages on a page or user basis, depending on your needs.

Language codes can be found here.

👍

Example Use Case: Customer-based Languages

As a SaaS company that offers translations to our customers, we want to be able to customize the list of languages on a per-customer basis, so our customers only see the languages they need.

You can store the list of languages per customer in the company profile in your database, then use that list of languages when Localize is initialized for that customer.

localizeImages

Defaults to false.
If true, the image URLs used in your website will appear in your phrases bin to allow for image replacement based on language.

🚧

Overrides Project Setting

This setting overrides the one in the Project Settings: Library Settings.

rememberLanguage

Defaults to false.
If true, Localize will remember the user’s previous language choice and will translate your website to that language.

retranslateOnNewPhrases

Defaults to false.
If set to true, Localize will automatically translate content that is added dynamically to your webpage.

For example:

• If your webpage dynamically adds HTML into the source of the page, our library will translate it once the translations have been generated.
• Behind the scenes this means the dictionary file with all your translated content is available for use with Localize.translate().
• However, translations are not generated instantly, so use with our Localize.on() library method with the updatedDictionary event is recommended.
• When phrases are saved to Localize (either new phrases or deprecated phrases), Localize:
  • ...waits 3.5 seconds, then it checks if the current version of the translation file has been updated since the page originally loaded.
    • If the translation file version has changed since loading the page, the new file is fetched and the page retranslates with the updated translations.
    • Else if the translation file has not changed, then the translation file is not fetched.
  • It repeats the check once more after 6.5 seconds, and fetches the file if it did change.

saveNewPhrases

Defaults to true.
If true, unrecognized phrases will be added to your Localize account.

saveNewPhrasesFromSource

Defaults to false.
New phrases are only detected when a user is displaying a page in a target language. If true, Localize will detect phrases only when the user is viewing a page in the source language.

🚧

Contact Support

Please contact [email protected] prior to updating this option.

targetLanguage

targetLanguage: ‘LANG_CODE’
Localize will set the target language of your website to the specified language, ignoring the cookie that Localize normally saves in the user's browser.

You must provide the language code as the value. Language codes can be found on your Languages page.

Example Use Case

One possible use case would be: if you are saving the language preference for your users in your website/database, then you can manually set the user's language even if they log in with a totally different computer/device or clear their browser's cache.

<script>
  // Get the user's preferred language from your database.
  var preferredLanguage = 'Language_Code_From_Your_Database';

  Localize.initialize({
    key: '[[app:key]]', 
    targetLanguage: preferredLanguage
    // other options go here, separated by commas
  });

  Localize.on("setLanguage", function(data) {
    var newLanguage = data.to;
    // Save the user's new language preference to your database.
  });
</script>

translateAlt

Defaults to true.
If true, alt attributes within HTML elements will be found by Localize and brought into the dashboard, allowing you to translate them.

translateAriaLabels

Defaults to true.
If true, aria-label attributes within HTML elements will be found by Localize and brought into the dashboard, allowing you to translate them.

Translating aria-labels optimizes your site for use with assistive technologies.

🚧

Overrides Project Setting

This setting overrides the one in the Project Settings: Library Settings.

translateBody

Defaults to true.
If true, Localize will translate the contents in the entire <body> element of the page.

If false, Localize will only translate the content within an HTML element(s) that contains the attribute class="localizejs" or id="localizejs".

translateClasses

translateClasses: ['example-class1', ‘example-class2’]

An array of class names for which Localize will translate. If you use this option, Localize will ONLY translate content contained in these classes and will ignore all other content in the body of the page.

translateMetaTags

Defaults to true.
If true, metadata tags in the <head> section of the web page will be found by Localize and brought into the dashboard, allowing you to translate them.

Translating metadata tags optimizes your site for SEO. See the list of supported metadata tags here.

🚧

Overrides Project Setting

This setting overrides the one in the Project Settings: Library Settings.

translateNumbers

Defaults to false.
If true, the Localize library will pick up numbers as phrases.
For example: <p>43525234543<p> will be saved as a phrase when set to true.

translateSVGElement

Defaults to true.
If true, text contained within SVGs will be found by Localize and brought into the dashboard, allowing you to translate the text. (SVG files are not supported)

translateTimeElement

Defaults to false.
If true, the Localize library will pick up phrases in <time> elements.
For example: <time>July 7</time> will be saved as a phrase when set to true.

translateTitle

Defaults to true.
If true, the <title> tag of the page in the <head> section of the web page will be translatable.

useSubdirectoriesWithWidget

Defaults to false.
If true, when a target language is selected in the default Localize language-switching widget, the system will add the appropriate language code to the current page's URL. See the example for the "contact-us" page in the following table.

useSubdomainsWithWidget

Defaults to false.
If true, when a target language is selected in the default Localize language-switching widget, the system will add the appropriate language code to the current page's URL. See the example for the "contact-us" page in the following table.

vueSafe

Defaults to false.

Set this to true if you are working on a website that uses the Vue.js framework to build your website to avoid DOM-based conflicts.

In general, if you are having problems when using Localize on your site and see an error in the console that states "Cannot remove a child from a different parent", then you may also need to set this option to true even if you are not working on a Vue.js-based website.

• One example is if you are localizing a Salesforce Digital Experience app.

Looking for the available methods? See the Frontend API: Methods page for the available methods in the Localize object after the Localize.initialize() method has been called.