1.0.2 • Published 7 months ago

msc-ai-translator v1.0.2

Weekly downloads
-
License
MIT
Repository
github
Last release
7 months ago

msc-ai-translator

Published on webcomponents.org DeepScan grade

<msc-ai-translator /> is a web component based on Chrome Built-in AI > Language Detector API and Translator API. Web developers could use <msc-ai-translator /> wrap article which want to adopt translate language feature.

<msc-ai-translator />

Basic Usage

<msc-ai-translator /> is a web component. All we need to do is put the required script into your HTML document. Then follow <msc-ai-translator />'s html structure and everything will be all set.

  • Required Script
<script
  type="module"
  src="https://unpkg.com/msc-ai-translator/mjs/wc-msc-ai-translator.js">        
</script>
  • Structure

Put <msc-ai-translator /> into HTML document. It will have different functions and looks with attribute mutation.

<msc-ai-translator>
  <script type="application/json">
    {
      "l10n": {
        "subject": "Gemini",
        "introduction": "Here comes a translation.",
        "selectlanguage": "Select language",
        "translate": "Translate this article to 「{{language}}」"
      },
      "optionslanguage": "en"
    }
  </script>

  <!-- Put content element(s) which like to adopt translate feature here -->
  <div class="intro">
    萬代南夢宮娛樂於今日(3/16)宣布,由萬代南夢宮娛樂及
    ...
    ...
    ...
  </div>
</msc-ai-translator>

Otherwise, developers could also choose remoteconfig to fetch config for <msc-ai-translator />.

<msc-ai-translator
  remoteconfig="https://your-domain/api-path"
>
  ...
</msc-ai-translator>

JavaScript Instantiation

<msc-ai-translator /> could also use JavaScript to create DOM element. Here comes some examples.

<script type="module">
import { MscAiTranslator } from 'https://unpkg.com/msc-ai-translator/mjs/wc-msc-ai-translator.js';

const contentElementTemplate = document.querySelector('.my-content-element-template');

// use DOM api
const nodeA = document.createElement('msc-ai-translator');
document.body.appendChild(nodeA);
nodeA.appendChild(contentElementTemplate.content.cloneNode(true));
nodeA.l10n = {
  subject: 'Gemini',
  introduction: 'Here comes a translation.',
  selectlanguage: 'Select language',
  translate: 'Translate this article to 「{{language}}」'
};

// new instance with Class
const nodeB = new MscAiTranslator();
document.body.appendChild(nodeB);
nodeB.appendChild(contentElementTemplate.content.cloneNode(true));
nodeB.l10n = {
  subject: 'Gemini',
  introduction: 'Here comes a translation.',
  selectlanguage: 'Select language',
  translate: 'Translate this article to 「{{language}}」'
};

// new instance with Class & default config
const config = {
  l10n: {
    subject: 'Gemini',
    introduction: 'Here comes a translation.',
    selectlanguage: 'Select language',
    translate: 'Translate this article to 「{{language}}」'
  }
};
const nodeC = new MscAiTranslator(config);
document.body.appendChild(nodeC);
nodeC.appendChild(contentElementTemplate.content.cloneNode(true));
</script>

Style Customization

Developers could apply styles to decorate <msc-ai-translator />'s looking.

<style>
msc-ai-translator {
  /* dialog */
  --msc-ai-translator-dialog-background-color: rgba(255 255 255);
  --msc-ai-translator-dialog-backdrop-color: rgba(35 42 49/.6);
  --msc-ai-translator-dialog-head-text-color: rgba(35 42 49);
  --msc-ai-translator-dialog-line-color: rgba(199 205 210);
  --msc-ai-translator-dialog-close-icon-color: rgba(95 99 104);
  --msc-ai-translator-dialog-close-hover-background-color: rgba(245 248 250);
  --msc-ai-translator-dialog-introduction-color: rgba(35 42 49);
  --msc-ai-translator-content-text-color: rgba(35 42 49);
  --msc-ai-translator-content-highlight-text-color: rgba(68 71 70);
  --msc-ai-translator-content-highlight-background-color: rgba(233 238 246);
  --msc-ai-translator-content-group-background-color: rgba(241 244 248);
  --msc-ai-translator-button-voice-background-color: rgba(202 230 252);
  --msc-ai-translator-button-voice-icon-color: rgba(8 28 53);
  --msc-ai-translator-button-voice-box-shadow: 0px 4px 10px rgba(0 0 0/.15);
}
</style>

Delevelopers could add className - align-container-size to make <msc-ai-translator />'s size same as container's size.(default is inline-size: 100% only)

<msc-ai-translator class="align-container-size">
  ...
</msc-ai-translator>

Otherwise, apply pseudo class ::part(trigger) to direct style the translate button.

<style>
msc-ai-translator {
  &::part(trigger) {
    background: red;
  }

  &::part(trigger):hover {
    background: green;
  }
}
</style>

Attributes

<msc-ai-translator /> supports some attributes to let it become more convenience & useful.

  • disabled

Hides the translate trigger button once set. It is false by default (not set).

<msc-ai-translator disabled>
  ...
</msc-ai-translator>
  • l10n

Set localization for title or action buttons.

subject:Set dialog subject.\ introduction:Set dialog result title.\ selectlanguage:Set language select title.\ translate:Set translate trigger button's content. Web developer could add keyword {{language}} in sentence, <msc-ai-translator /> will replace it with the language you picked.

<msc-ai-translator l10n='{"subject":"Gemini","introduction":"Here comes a translation.","selectlanguage":"Select language","translate":"Translate to {{language}}"}'>
  ...
</msc-ai-translator>
  • optionslanguage

Set language select's option display language. Default is "en".

<msc-ai-translator optionslanguage="zh-Hant">
  ...
</msc-ai-translator>

Properties

Property NameTypeDescription
disabledBooleanGetter / Setter disabled. Hides the summarize trigger button once set. It is false by default.
l10nObjectGetter / Setter localization for title or action buttons. Developers could set subjectintroductionselectlanguage and translate here.
availableStringGetter available. Web developers will get "no" if current browser doesn't support Build-in AI.
translationStringGetter the last translation.
optionslanguageStringGetter / Setter language select's option display language.

Mathods

Mathod SignatureDescription
translate({ content = '', useDialog = false, targetLanguage })Go translating. This is an async function. Default will take <msc-ai-translator />'s children's text content to translate.Developers could set useDialog to decide display translation by dialog or not.

Event

Event SignatureDescription
msc-ai-translator-errorFired when translate process error occured. Developers could gather message information through event.detail.
msc-ai-translator-processFired when prompt processing.
msc-ai-translator-process-endFired when prompt process end.

Reference