Widget API (WOVN.io Javascript)

WOVN では、JavaScript で翻訳ページの言語変更・言語確認ができるように、いくつかのメソッドとイベントハンドラーを提供しています。

インフォメーション
本機能の動作は、お客様のご利用環境（OS、ブラウザ、サイト構成、ネットワーク環境等）により異なる場合がございます。
ご利用にあたっては、お客様自身の責任においてご判断いただきますようお願いいたします。

ご不明な点やトラブルが発生した場合は、まずはサポートページ（トラブルシューティング）をご確認ください。

目次

• メソッド

  • WOVN.io.changeLang(langCode)
  • WOVN.io.getCurrentLang()
  • WOVN.io.getTextTranslation(text, toLang)
  • WOVN.io.getWovnUrl(url)
  • WOVN.io.isApiReady()
  • WOVN.io.isPublished(langCode)
  • WOVN.io.manualStart()
  • WOVN.io.optOut()
  • WOVN.io.optInCookies()
  • WOVN.io.translateTexts(fromLang, toLang, texts)
  • WOVN.io.triggerAudit()
  • WOVN.io.swap(element)
  • WOVN.io.version()
  • WOVN.io.getSourceText()

• イベントハンドラー

  • wovnApiReady
  • wovnLangChanged

メソッド

WOVN.io.changeLang(langCode)

ページを表示する言語を変更します。

• 引数に 'en' や 'ja' などの言語コードを設定してください。
• 有効な言語コードが設定された場合、true を返します。それ以外の場合には false を返します。

例：

> WOVN.io.changeLang('en')
< true

WOVN.io.getCurrentLang()

ページ上で現在表示されている言語を取得します。

• 引数はありません。
• 現在の言語オブジェクトを返します。

例：

​ ​> WOVN.io.getCurrentLang()
< Object {name: "English", code: "en", en: "English"}

WOVN.io.getTextTranslation(text, toLang)

翻訳されたテキストを返します。

• 引数 text に元言語のテキストを、toLang に翻訳言語の言語コードを設定してください。
• 翻訳されたテキストが返されます。
• このメソッドは、呼び出したページに紐付く WOVN 上に格納されている翻訳データを用います。
  したがって、過去に一度も翻訳をしたことのないデータは置換されず、元言語のままになります。

例：

> WOVN.io.getTextTranslation('Hello world', 'ja');
< 'こんにちは世界'

WOVN.io.getWovnUrl(url)

選択中の言語とプロジェクト設定に基づいて、URL に対応した 言語コード付き URL を取得します。

• 引数に URL を設定してください。('https://wovn.io', '/top', etc.)
  引数は完全修飾 URL か絶対パスである必要があります。
• 翻訳されたページの URL を返します。('https://wovn.io' -> 'https://wovn.io/ja', '/top' -> '/ja/top', etc)

例：

> WOVN.io.getWovnUrl('/shop')
< '/ja/shop'

WOVN.io.isApiReady()

WOVN スクリプトの読み込みが完了しているか、boolean で返します。

例：

> WOVN.io.isApiReady();
< true

例2：

if (window.WOVN && WOVN.io && WOVN.io.isApiReady()) {
    // something
} else {
    window.addEventListener('wovnApiReady',function(){
        // something
    })
}

WOVN.io.isPublished(langCode)

翻訳言語が公開されているかを確認します。

• 引数に確認したい翻訳言語の言語コードを設定してください。
• 翻訳言語が公開されている場合、true を返します。それ以外の場合は false を返します。

例：

> WOVN.io.isPublished('en');
< true

WOVN.io.manualStart()

WOVN のブラウザ側処理を、任意のタイミングで開始することができます。

独自言語切替ウィジェット を設置する場合、独自言語切替ウィジェットタグがブラウザ上にマウントされた後に WOVN が実行される必要があります。
ただし、対象 Web ページに紐づくサービスの構成によってはこの処理順序を保証できないことがあります。
Web ページの一連の処理完了後に WOVN.io.manualStart() メソッドを実行すると、独自言語切替ウィジェットの処理を正常に実行できるようになります。

> WOVN.io.manualStart();

注意
この機能を利用する場合は、翻訳対象の全ページで manualStart() を実行してください。
自動で WOVN が実行されず、実行待ちの状態になるためです。

インフォメーション
この機能はオプション機能です。利用の際は WOVN 管理画面右上の「お問い合わせ」ボタンからお問い合わせください。

WOVN.io.optOut()

WOVN が利用する Cookie を無効にします。
このメソッドを実行すると、ユーザーが行った言語切替え状態が保持されなくなります。
また、言語切替え状態を保持しないので、毎回ブラウザ言語判定による言語切替えを実行します。

利用するときは、wovnApiReady イベントハンドラーと組み合わせて実行します。

• 引数はありません。
• 戻り値はありません。

window.addEventListener('wovnApiReady', function(evt) {
  WOVN.io.optOut();
});

注意
例外的に wovn-optedOutCookies がセットされます。これはオプトアウト設定を保持するために設定する Cookieです。

WOVN.io.optInCookies()

メソッド実行後から WOVN.io が定義した各種 Cookie の使用を開始します。
この機能を利用するには、WOVN 管理画面右上の「お問い合わせ」ボタンからお問い合わせください。

利用するときは、wovnApiReady イベントハンドラーと組み合わせて実行します。

• 引数はありません。
• 戻り値はありません。

window.addEventListener('wovnApiReady', function(evt) {
  WOVN.io.optInCookies();
});

WOVN.io.translateTexts(fromLang, toLang, texts)

元言語の文字列配列を受け取り、指定した翻訳言語の文字列配列を返します。

• 第 1 引数 fromLang: 元言語の言語コード
• 第 2 引数 toLang: 翻訳言語の言語コード
• 第 3 引数 texts: 翻訳対象の文字列配列
• 翻訳言語の文字列配列をオブジェクトにして返します。

例：

> WOVN.io.translateTexts('en', 'ja', ['good afternoon', 'good night'])
< {'good afternoon': 'こんにちは', 'good night': 'おやすみ'}

WOVN.io.triggerAudit()

ブラウザでページがロードされてから WOVN Javascript によって自動的に実施される翻訳の反映処理を再度トリガーします。

• 引数はありません。
• 戻り値はありません。

WOVN Javascript は、ブラウザでページがロードされてから以下の条件で翻訳の反映処理を行います。

1. 一定時間が経過したとき

• 1 秒後
• 4 秒後
• 9 秒後
• 16 秒後
• 25 秒後

2. ボタンクリックなど、特定の操作を実行したとき
3. 言語切替ウィジェットで言語を切り替えたとき

サイトの Javascript によって HTML の書換えが行われた後、翻訳が反映されるまでに時間がかかる場合があります。
WOVN.io.triggerAudit() メソッドを実行すると、前述 1. の一定時間経過による翻訳反映処理を再度トリガーすることができます。

例：

> WOVN.io.triggerAudit();

WOVN.io.swap(element)

指定した要素に対して WOVN による翻訳を適用します。

• 引数に要素を設定してください。
• 戻り値はありません。

例：

var newEle = document.querySelector('#new-content')
> WOVN.io.swap(newEle)

WOVN.io.version()

現在利用している WOVN ウィジェットのバージョンを出力します。

例：

> WOVN.io.version()

WOVN.io.getSourceText()

任意の要素の元言語テキストを取得することができます。

• 引数に要素を設定してください。
• 翻訳前の文字列を返します。

例：

> WOVN.io.getSourceText(document.querySelector("body > header > div.logo > a > p"));
< 'ヘルプセンター'

イベントハンドラー

wovnApiReady

WOVN スクリプトの読み込みが完了した後に呼び出されます。
JavaScript でページの言語を変更したい場合、このイベントハンドラーを使用して下記のように変更することができます。

例：

window.addEventListener('wovnApiReady', function(evt) {
  WOVN.io.changeLang('en');
});

wovnLangChanged

ウィジェットがページ上の言語を変更するたびに呼び出されます。
言語がユーザーの設定やブラウザの言語に基づいて自動的に変更された場合、このイベントが呼び出されます。

このイベントハンドラーと WOVN.io.getCurrentLang() メソッドで取得できる翻訳言語を併用することで、言語ごとに別の動作をさせることができます。

例：

window.addEventListener('wovnLangChanged', function (evt) {
  var newLang = WOVN.io.getCurrentLang().code;
  document.getElementById('support-content').setAttribute('href', 'http://cdn.com/' + newLang + '/info.pdf');
});