HTML Widget Configuration

The language switcher is an HTML web component and supported by all major browsers.

Quick Start

To add Mondo Translate to your web site, add the translation library and language switcher widget:

1. Add the following javascript tag before the closing </body> tag on your web page

<script
  async
  src="//translate-widget.iife.js"
></script>

2. Add the language switcher on the page where you desire (such as your page header):

   <mondo-translate-widget
     api-host="[[your-mondo-translation-url]]"
     app-id="[[your-mondo-translate-publishable-key]]"
     native-language='{"label":"English", "code":"en"}'
     languages='[
           {"label": "English", "code": "en"},
           {"label": "Spanish", "code": "es"}
       ]'
     translate="no"
   ></mondo-translate-widget>

   Replace api-host and app-id with values found within your Mondo Dashboard.

Language Switcher Params

The HTML widget can be configured with the following params:

app-id v2.0.0

Type: String required

An App Id is the identifier for a configured App; which allows Mondo Translate to be used across multiple sites without conflicting translations, phrases or cache.

<mondo-translate-widget
  app-id="app_*********************"
  ...
></mondo-translate-widget>

api-host v1.0.0

Type: String required

The API Host is the API Gateway url that is configured during initial deployment.

<mondo-translate-widget
  api-host="https://your-mondo-translate-host.com"
  ...
></mondo-translate-widget>

auto-translate v2.2.0

Type: String optional - An ISO 639-1 language code.

Perform an initial translation to the provided language. Note: a user's selected language will take precedence over this value.

<mondo-translate-widget
  auto-translate="es"
  ...
></mondo-translate-widget>

cookie-domain v2.0.0

Type: String optional

Specifying a cookie domain allows a user's selected language preference to be shared across a domain and sub-domains. For example, if you want to share the user's language preference between your brochure site (www.example.com) and your knowledge base (kb.example.com); set this param to .example.com so all domains/sub-domains can access the language preference cookie. Populating this param automatically switches the storage-mode to cookie.

<mondo-translate-widget cookie-domain=".example" ...></mondo-translate-widget>

native-language v1.0.0

Type: Object required

The native language is the page's origination source. A native language object contains the following attributes:

• label required - A string representing the human readable language to display
• code required - An ISO 639-1 language code.

If a page consists of mixed languages, a language code of auto can also be used.

Note: Using the auto lanague code will incur more cost as it requires additional resources to identify the language.

<mondo-translate-widget
  native-language='{"label":"English", "code":"en"}'
  ...
></mondo-translate-widget>

languages v1.0.0

Type: Array of Objects required

Languages are the available translations a user can select. The languages are displayed in the order provided. A language object contains the following attributes:

• label required - A string representing the human readable language to display
• code required - An ISO 639-1 language code.
• terminology optional - A terminology handle that should be applied to the translations. This source and target languages should match the provided terminology.

<mondo-translate-widget
  languages='[
        {"label": "English", "code": "en"},
        {"label": "Arabic", "code": "ar"},
        {"label": "Chinese", "code": "zh"},
        {"label": "Spanish", "code": "es", "terminology": "custom-es"}
    ]'
  ...
></mondo-translate-widget>

watch experimental v1.0.0

Type: "yes" | "no" | empty (shorthand for yes) optional

Default: "no"

If your page contains content that is manipulated after initial page load, the watch param will attempt to detect these change and provide translations on the fly.

<mondo-translate-widget watch ...></mondo-translate-widget>

omit-styles v1.0.0

Type: "yes" | "no" | empty (shorthand for yes) optional

Default: "no"

The widget provides minimal and customizable css styles that are intended to work for most sites. If you would prefer to roll your own, you can omit styles entirely.

<mondo-translate-widget omit-styles ...></mondo-translate-widget>

selected-first v3.0.0

Type: "yes" | "no" | empty (shorthand for yes) optional

Default: "no"

When enabled, the selected language is added to the top of the option list and marked as bold.

<mondo-translate-widget selected-first ...></mondo-translate-widget>

storage-expiry v2.0.0

Type: Number (as String) optional

Default: "2592000" // <- 30 days

Identify how long a user's selected language preference should be stored and used for future visits. To override the default storage expiry, provide a numeric string representing the number of seconds a translation should be cached. Providing a duration of zero (0) results the preference stored for a users session; once the use closes the browser/tab the preference is no longer accessible.

<mondo-translate-widget storage-expiry="3600" ...></mondo-translate-widget>

storage-mode v2.0.0

Type: "local" | "cookie" | "session" optional

Default: "local"

Identify the type of storage used to store a user's selected language preference. Here are a few reasons to specify a storage mode:

• local - versitile, not sharable across domains
• cookie - sharable across domains, not enabled on all browsers
• session - short lived

<mondo-translate-widget storage-mode="session" ...></mondo-translate-widget>

translate-head v3.0.0

Type: "yes" | "no" | empty (shorthand for yes) optional

Default: "no"

When enabled, the page title, description and other meta data is translated.

<mondo-translate-widget translate-head ...></mondo-translate-widget>

dev-mode experimental v1.0.0

Type: "yes" | "no" | empty (shorthand for yes) optional

Default: "no"

Dev mode exposes some helpful tools to manage translations. When enabled, translatable HTML nodes can be highlighted and the source text can be copied by alt + click the highlighted node. Please refer to Customizing dev-mode section for details.

Note: This functionality is subject to change without notice as it's considered experimental.

<mondo-translate-widget dev-mode ...></mondo-translate-widget>

Overriding Default CSS Styles

The language switcher features a clean and simple UI/UX. To customize the widget further, the following CSS variables are available:

/* Trigger */
--mondo-translate-trigger-bg-opacity: 0;
--mondo-translate-trigger-bg-color: rgb(
  0 0 0 / var(--mondo-translate-trigger-bg-opacity)
);

--mondo-translate-trigger-text-opacity: 1;
--mondo-translate-trigger-text-color: rgb(
  0 0 0 / var(--mondo-translate-trigger-text-opacity)
);

--mondo-translate-trigger-hover-bg-opacity: 0.05;
--mondo-translate-trigger-hover-bg-color: rgb(
  0 0 0 / var(--mondo-translate-trigger-hover-bg-opacity)
);

--mondo-translate-trigger-border-size: 1px;
--mondo-translate-trigger-border-opacity: 0.15;
--mondo-translate-trigger-border-color: rgb(
  0 0 0 / var(--mondo-translate-trigger-border-opacity)
);
--mondo-translate-trigger-border: solid var(
    --mondo-translate-trigger-border-size
  ) var(--mondo-translate-trigger-border-color);

/* Items */
--mondo-translate-items-bg-opacity: 1;
--mondo-translate-items-bg-color: rgb(
  255 255 255 / var(--mondo-translate-items-bg-opacity)
);

--mondo-translate-items-border-size: 1px;
--mondo-translate-items-border-opacity: 0.05;
--mondo-translate-items-border-color: rgb(
  0 0 0 / var(--mondo-translate-items-border-opacity)
);
--mondo-translate-items-border: solid var(--mondo-translate-items-border-size) var(
    --mondo-translate-items-border-color
  );

--mondo-translate-items-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px
    6px -4px rgb(0 0 0 / 0.1);
--mondo-translate-items-shadow-colored: 0 10px 15px -3px var(--mondo-translate-items-shadow-color),
  0 4px 6px -4px var(--mondo-translate-items-shadow-color);
--mondo-translate-items-outter: var(0, 0 0 #0000), var(
    --mondo-translate-items-ring-shadow,
    0 0 #0000
  ), var(--mondo-translate-items-shadow);

/* Item */
--mondo-translate-item-action-active-bg-font-weight: bold;

--mondo-translate-item-action-hover-bg-opacity: 0.05;
--mondo-translate-item-action-hover-bg-color: rgb(
  0 0 0 / var(--mondo-translate-item-action-hover-bg-opacity)
);

The default variables can be overwritten by setting them within the widget context:

mondo-translate-widget {
  --mondo-translate-trigger-bg-color: red;
}

To override other aspects of the translation widget apearance, do so via the web component part attribute:

mondo-translate-widget::part(container) {
  /* Custom styles here */
}

mondo-translate-widget::part(trigger) {
  /* Custom styles here */
}

mondo-translate-widget::part(items) {
  /* Custom styles here */
}

mondo-translate-widget::part(item) {
  /* Custom styles here */
}

mondo-translate-widget::part(item-action) {
  /* Custom styles here */
}

mondo-translate-widget::part(item-action-active) {
  /* Custom styles here */
}

Customizing dev-mode view

When the dev-mode param is enabled, default styles are not automatically applied to your web page (so it may appear as though dev mode is not enabled). There are two ways to add these styles:

1. Add the following stylesheet to your site:

<link
  rel="stylesheet"
  href="/style.css"
/>

2. Or, you can roll your own customizations such as:

:root {
  --mondo-translate-dev-node-ring-color: rgb(190, 0, 0);
  --mondo-translate-dev-node-ring-copied-color: rgb(0, 190, 0);
}

.mondo-translate-dev-node:hover {
  box-shadow: var(--mondo-translate-dev-node-ring-color) 0px 0px 0px 1.5px;
  cursor: copy !important;
}

.mondo-translate-dev-node-copied:hover {
  box-shadow: var(--mondo-translate-dev-node-ring-copied-color) 0px 0px 0px 1.5px;
}

Customizing language button

By default, the widget displays the currently selected language. If you would like to provide a different button experience, you may do so via a web component slot.

The following will use icons for the widget button:

<mondo-translate-widget>
  <div slot="label">
    <span class="text" style="display: flex;">
      <svg
        style="height: 20px"
        xmlns="http://www.w3.org/2000/svg"
        fill="none"
        stroke="currentColor"
        stroke-linecap="round"
        stroke-linejoin="round"
        stroke-width="2"
        viewBox="0 0 24 24"
      >
        <path d="m5 8 6 6M4 14l6-6 2-3M2 5h12M7 2h1M22 22l-5-10-5 10M14 18h6" />
      </svg>
      <svg
        style="
                height: 16px;
                margin-left: 4px;
                margin-top: 2px;
                transform: rotate(90deg);
                "
        xmlns="http://www.w3.org/2000/svg"
        fill="none"
        stroke="currentColor"
        stroke-linecap="round"
        stroke-linejoin="round"
        stroke-width="2"
        viewBox="0 0 24 24"
      >
        <path d="m9 18 6-6-6-6" />
      </svg>
    </span>
  </div>
</mondo-translate-widget>