Vai al contenuto principale

JS SDK

The Immersive Translate JS SDK helps you implement bilingual translation on your website.

How to Use​

  1. Initialize Immersive Translate:
<script>
  window.immersiveTranslateConfig = {
    pageRule: {}
  }
</script>
  1. Add the following script code to your webpage
<script src="https://download.immersivetranslate.com/immersive-translate-sdk-latest.js"></script>

Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Immersive Translate JS SDK</title>
  <script>
    window.immersiveTranslateConfig = {
      pageRule: {}
    }
  </script>
  <script async src="https://download.immersivetranslate.com/immersive-translate-sdk-latest.js"></script>
</head>

<body>
  <div>
    <p>Night gathers, and now my watch begins. It shall not end until my death. I shall take no wife, hold no lands,
      father no children. I shall wear no crowns and win no glory. I shall live and die at my post.</p>
  </div>
</body>
</html>

Parameters​

With pageRule, you can customize the configuration of the website, deciding which content needs to be translated or adjusting the webpage styles.

initImmersiveTranslate({
  pageRule: {
    "selectors": [".text"],
    "excludeSelectors": ["nav", "footer"],
  },
});

Using selectors will override the smart translation range, translating only elements matched by the selector.

Using excludeSelectors can exclude elements from translation.

Using selectors.add will add some selectors on top of the default ones.

Using selectors.remove will remove some selectors from the default ones.

If you want to translate a specific area and consider an element as a whole without breaking it into lines, you can use the atomicBlockSelectors selector. Note that you need to select elements using selectors before using atomicBlockSelectors.

{
  "selectors": [
    "div._aa_c h1",
    "li._acaz div[role=\"menuitem\"]"
  ],
  "atomicBlockSelectors": [
    "div._aa_c h1",
    "li._acaz div[role=\"menuitem\"]"
  ]
}

pageRule more parameter explanations:

export interface PageRule {
  excludeMatches?: string | string[]; // Exclude specific websites.
  selectorMatches?: string | string[]; // Match using selectors without specifying all URLs
  excludeSelectorMatches?: string | string[]; // Exclude rules, same as above.

  // Specify translation range
  selectors?: string | string[]; // Translate only matched elements
  excludeSelectors?: string | string[]; // Exclude elements, do not translate matched elements
  excludeTags?: string | string[]; // Exclude tags, do not translate matched tags

  // Add translation range, not override
  additionalSelectors?: string | string[]; // Add translation range. Add translation positions in smart translation areas.
  additionalExcludeSelectors?: string | string[]; // Add excluded elements to prevent smart translation in specific positions.
  additionalExcludeTags?: string | string[]; // Add excluded tags

  // Keep original
  stayOriginalSelectors?: string | string[]; // Matched elements will remain original. Commonly used for tags on forum websites.
  stayOriginalTags?: string | string[]; // Matched tags will remain original, such as `code`

  // Region translation
  atomicBlockSelectors?: string | string[]; // Region selector, matched elements will be considered as a whole, not translated in segments
  atomicBlockTags?: string | string[]; // Region tag selector, same as above

  // Block or Inline
  extraBlockSelectors?: string | string[]; // Extra selectors, matched elements will be treated as block elements, occupying one line.
  extraInlineSelectors?: string | string[]; // Extra selectors, matched elements will be treated as inline elements.

  inlineTags?: string | string[]; // Matched tags will be treated as inline elements
  preWhitespaceDetectedTags?: string | string[]; // Matched tags will automatically wrap lines

  // Translation styles
  translationClasses?: string | string | string[]; // Add extra classes to the translation

  // Global styles
  globalStyles?: Record<string, string>; // Modify page styles, useful when translations cause page disorder.
  globalAttributes?: Record<string, Record<string, string>>; // Modify attributes of page elements

  // Embedded styles
  injectedCss?: string | string[]; // Embed CSS styles
  additionalInjectedCss?: string | string[]; // Add CSS styles instead of directly overriding.

  // Context
  wrapperPrefix?: string; // Prefix of the translation area, default is smart, decides whether to wrap lines based on the number of characters.
  wrapperSuffix?: string; // Suffix of the translation area

  // Translation wrapping character count
  blockMinTextCount?: number; // Minimum character count for translation as a block, otherwise, the translation will be an inline element.
  blockMinWordCount?: number; // Same as above. To always wrap lines, set both to 0.

  // Minimum character count for translatable content
  containerMinTextCount?: number; // Minimum character count for elements to be translated during smart recognition, default is 18
  paragraphMinTextCount?: number; // Minimum character count for original paragraph, content greater than the number will be translated
  paragraphMinWordCount?: number; // Minimum word count for original paragraph

  // Forced line break character count for long paragraphs
  lineBreakMaxTextCount?: number; // Maximum character count for forced line break when translating long paragraphs.

  // Timing to start translation
  urlChangeDelay?: number; // Delay in milliseconds before starting translation after entering the page. Default is 250ms to wait for webpage initialization.

  // AI streaming translation
  aiRule: {
    streamingSelector: string; // GPT webpage selector marking the translating element
    messageWrapperSelector: string; // Message body selector
    streamingChange: boolean; // Incremental or full update for repeated messages in GPT-like webpages. GPT is incremental
  };
}