This is intended to be used by webmasters/bloggers wishing to add pop-up annotation to their web pages. If you are interested in adding this functionality to your browser instead, have a look at our browser extension.

Yes, this is completely free.

Quick Start

Add the following before </body>, where you'd usually put Google analytics and such

<script src="//mandarinspot.com/static/mandarinspot.min.js" charset="UTF-8"></script>
<script>mandarinspot.annotate();</script>

That's it. It should work with all the assumed defaults.

Now some more details

The script can be loaded anywhere, but to avoid delaying loading of the main content, it either needs to be done asynchronously or at the bottom of the body as suggested above.

The call to the annotate() has to be done after the script is loaded and the DOM (at least the part that we want to annotate) is ready. Again, placing the call at the bottom of the page, as suggested in the previous section, will work well.

The main call is mandarinspot.annotate(selector, options). Both arguments are optional.

selector can either be:

• a DOM element, like document.body, for example;
• element ID, could be "#chinesetext";
• or class name, ".post" or something.

If omitted, document.body is used.

options is an object with three optional members:

• phonetic, can either be "pinyin" or "zhuyin", pinyin is the default;
• show, boolean value to indicate whether pop-ups need to be shown initially, default is true;
• inline, boolean value to indicate whether phonetics should also be shown inline above text, default is false;

These two calls can be used to switch pop-ups on and off respectively

mandarinspot.showPopups(true);
mandarinspot.showPopups(false);

If you want pop-ups initially be inactive, you can call it like this:

<script>mandarinspot.annotate('#annotste-this', {phonetic: 'pinyin', show: false});</script>

It's also possible to show phonetics above text. To do this you need to add option inline: true like this:

<script>mandarinspot.annotate('#annotste-this', {inline: true});</script>

To control visibility of inline phonetics you can use the following calls:

• mandarinspot.showInline("visible") - to show inline,
• mandarinspot.showInline("hidden") - to hide phonetics without reformating text,
• mandarinspot.showInline(false) - to remove phonetics completely.

Compatibility

To detect whether API is supported in the browser you can call mandarinspot.supported(), which will return true or false based on best guess after detecting some browser features.

Branding

By default, the pop-up window contains the string MandarinSpot.com at the bottom. This serves as a subtle attribution and helps users discover the service.

However, you can choose to replace this text attribution with a graphical badge placed directly next to the annotated text. This is particularly useful if you want to maintain visual consistency with your site's design or make the attribution more noticeable.

We provide three badge versions:

• badge-light.svg - black text, suitable for light backgrounds
• badge-dark.svg - white text, suitable for dark backgrounds
• badge-auto.svg - automatically adapts to the user's system preference (light/dark mode)

Option 1: Using an Image

If your website has a consistent background color, choose the appropriate badge (badge-light.svg or badge-dark.svg) and add it using an image element:

<a href="https://mandarinspot.com/#api">
  <img id="mandarinspot-badge"
       src="badge-light.svg"
       alt="Annotated by MandarinSpot.com"
       style="width:140px;height:40px;border:0;">
</a>

Use this approach when your site has a fixed color theme and you want simple, static badge placement.

Option 2: Automatic Theme Switching

If your site supports both light and dark modes (or if you want the badge to adapt automatically based on user preferences), use badge-auto.svg. This version uses CSS media queries inside the SVG to switch text color based on the user's system preference:

<a href="https://mandarinspot.com/#api">
  <img id="mandarinspot-badge"
       src="badge-auto.svg"
       alt="Annotated by MandarinSpot.com"
       style="width:140px;height:40px;border:0;">
</a>

Use this approach when you want the badge to work automatically without needing to detect themes in JavaScript. However, note that this only responds to the user's system preference, not your site's specific theme.

Option 3: Manual Theme Detection

For full control over which badge to show based on your site's actual theme (not just system preference), use JavaScript:

<a href="https://mandarinspot.com/#api">
  <img id="mandarinspot-badge"
       src="badge-light.svg"
       alt="Annotated by MandarinSpot.com"
       style="width:140px;height:40px;border:0;">
</a>
<script>
  function updateBadge(isDark) {
    var img = document.getElementById('mandarinspot-badge');
    img.src = isDark ? 'badge-dark.svg' : 'badge-light.svg';
  }
</script>

Use this approach when your site has custom theme switching that may not match the user's system preference. You have full control over which badge appears.

Annotate Chinese text on any website directly in your browser with the MandarinSpot extension. Get pop-up definitions and pronunciation without leaving the page.

Features

• Hover over Chinese characters to see definitions and pronunciation
• Works on any website
• Completely offline