ヘルプセンター記事一覧

翻訳APIの仕様

最終更新: 2026年8月11日

#概要

Autolingualにおいては、Autolingual SDKの初期化状態、言語情報や言語切替タイミング取得をする下記のAPIを提供しております。

  • isReady()

  • getCurrentLanguage()

  • autolingual:ready

  • autolingual:language-changed

  • isTranslationBlocked()

  • autolingual:translation-blocked-changed

  • cookieOptIn()

    • ※オプション機能でのご提供

  • cookieOptOut()

    • ※オプション機能でのご提供

#isReady()

#概要

window.Autolingual.isReady() は、Autolingual SDK の初期化が完了しているかどうかを確認するための関数です。

SDKの初期化が完了すると、現在の表示言語など、SDK が管理している情報を安全に取得できる状態になります。

#返り値

window.Autolingual.isReady(): boolean

  • true: SDK の初期化が完了している
  • false: SDK の初期化がまだ完了していない

#基本的な使い方

if (window.Autolingual && window.Autolingual.isReady()) {
// 実行したい処理
}

#推奨の使い方

SDKの初期化完了後に処理を実行したい場合は、isReady()をautolingual:ready イベントと合わせて利用してください。

if (window.Autolingual && window.Autolingual.isReady()) {
// 実行したい処理
} else {
window.addEventListener("autolingual:ready", function () {
// 実行したい処理
});
}

#利用シーン

  • SDK の初期化が完了している場合のみ、特定の処理を実行する場合

#注意事項

  • Autolingual SDK の読み込みが始まる前は、window.Autolingual 自体が存在しない場合があります。
  • isReady() は、呼び出した時点での初期化状態を返す API です。初期化完了まで待機する機能はありません。
  • 初期化完了後の処理を確実に実行したい場合は、autolingual:ready イベントと合わせて利用してください。

#getCurrentLanguage()

#概要

window.Autolingual.getCurrentLanguage() は、現在のページに適用されている表示言語を取得するための関数です。

#返り値

window.Autolingual.getCurrentLanguage(): CurrentLanguage | null

CurrentLanguage の形式:

{
languageCode: "en",
customLanguageCode: null,
languageLabel: "English"
}

各項目の説明:

  • languageCode: Autolingualで管理している言語コード
  • customLanguageCode: 言語別URL機能を利用される場合のカスタム言語コード。設定されていない場合は null
  • languageLabel: Autolingualで管理している言語名

SDK の初期化が完了していない場合はnull。

#使い方

const currentLanguage = window.Autolingual.getCurrentLanguage();
console.log(currentLanguage); // { languageCode: "en", customLanguageCode: null, languageLabel: "English" }

#利用シーン

  • 現在の表示言語に合わせて、お客様側の表示や処理を切り替える場合
  • 外部サービスや別ページへ遷移するときに、現在の表示言語を引き継ぎたい場合

#注意事項

  • Autolingual SDK の読み込みが始まる前は、window.Autolingual 自体が存在しない場合があります。
  • SDK の初期化が完了していない場合、getCurrentLanguage() は null を返します。
  • ページ読み込み時に現在の表示言語を取得したい場合は、isReady() とautolingual:ready イベントを合わせて利用してください。
  • getCurrentLanguage() は、呼び出した時点での表示言語を返します。言語切り替えを検知するための関数ではありません。
  • 言語切り替えを検知したい場合は、autolingual:language-changed イベントを利用してください。
  • 除外ページはこの関数の判定対象外です

#autolingual:ready

#概要

autolingual:ready は、Autolingual SDK の初期化が完了したタイミングで発火するイベ ントです。

#基本的な使い方

window.addEventListener("autolingual:ready", function () {
  // 実行したい処理
});

#推奨の使い方

SDKの初期化完了後に処理を実行したい場合は、isReady()をautolingual:ready イベントと合わせて利用してください。

if (window.Autolingual && window.Autolingual.isReady()) {
// 実行したい処理
} else {
window.addEventListener("autolingual:ready", function () {
// 実行したい処理
});
}

#利用シーン

  • ページ読み込み時に、SDK の初期化完了後の処理を実行する場合

#注意事項

  • autolingual:ready は、同じページ内で 1 回のみ発火されます。
  • autolingual:ready がすでに発火されたあとにイベントリスナーを登録した場合には実行されません。
  • ページ読み込み時に SDK 初期化後の処理を確実に実行したい場合は、isReady() と合わ せて利用してください。

#autolingual:language-changed

#概要

autolingual:language-changed は、Autolingual SDK によって表示言語が切り替わったときに発火されるイベントです。

#使い方

window.addEventListener("autolingual:language-changed", function (event) {
console.log(event.detail.newLanguage); // { languageCode: "en", customLanguageCode: null, languageLabel: "English" }
// 実行したい処理
});

newLanguage の形式:

{
languageCode: "en",
customLanguageCode: null,
languageLabel: "English"
}

各項目の説明:

  • languageCode: Autolingualで管理している言語コード
  • customLanguageCode: 言語別URL機能を利用される場合のカスタム言語コード。設定されていない場合は null
  • languageLabel: Autolingualで管理している言語名

#利用シーン

  • 表示言語が切り替わったタイミングで、お客様側の表示や処理を切り替える場合
  • 言語切り替え後に、外部サービスへ変更後の言語情報を送信する場合

#注意事項

  • イベントが発火するのは、ユーザーが意図的に言語を変更した場合のみです。
  • ページ初回表示時の言語判定では、autolingual:language-changed は発火しません。
  • ページを再読み込みした場合、autolingual:language-changed は発火しません。

#isTranslationBlocked()

#概要

window.Autolingual.isTranslationBlocked() は、現在のページで翻訳がブロックされているかどうかを取得するための関数です。

#返り値

window.Autolingual.isTranslationBlocked(): TranslationBlocked | null

TranslationBlocked の形式:

{
  isBlocked: true,
  reason: "excluded"
}

各項目の説明:

  • isBlocked: 翻訳がブロックされているかどうか
  • reason: ブロックの理由。除外ページの場合は "excluded"、言語別URL機能パス形式でパスが翻訳対象除外の場合は "unsupportedPath"、翻訳がブロックされない場合は nullSDK の初期化が完了していない場合は null。

#使い方

const isBlocked = window.Autolingual.isTranslationBlocked();
console.log(isBlocked); // { isBlocked: true, reason: "excluded" }

#利用シーン

  • 翻訳がブロックされているページかどうかによって、お客様側の表示や処理を切り替える場合
  • 除外ページや翻訳不可ページで特定の UI を表示・非表示にしたい場合

#注意事項

  • Autolingual SDK の読み込みが始まる前は、window.Autolingual 自体が存在しない場合があります。
  • SDK の初期化が完了していない場合、isTranslationBlocked() は null を返します。
  • ページ読み込み時に翻訳ブロック状態を取得したい場合は、 autolingual:ready イベントを合わせて利用してください。
  • isTranslationBlocked() は、呼び出した時点での翻訳ブロック状態を返します。状態変化を検知するための関数ではありません。
  • 状態変化を検知したい場合は、autolingual:translation-blocked-changed イベントを利用してください。

#autolingual:translation-blocked-changed

#概要

autolingual:translation-blocked-changed は、ページ遷移に伴って翻訳ブロック状態が変化したときに発火されるイベントです。

#使い方

window.addEventListener("autolingual:translation-blocked-changed", function (event) {
console.log(event.detail.translationBlocked); // { isBlocked: true, reason: "excluded" }
// 実行したい処理
});

event.detail.translationBlocked の形式:

{
  isBlocked: true,
  reason: "excluded"
}

各項目の説明:

  • isBlocked: 翻訳がブロックされているかどうか
  • reason: ブロックの理由。除外ページの場合は "excluded"、言語別URL機能パス形式でパスが翻訳対象除外の場合は "unsupportedPath"、 翻訳がブロックされない場合は null

#利用シーン

  • 翻訳ブロック状態が変化したタイミングで、お客様側の表示や処理を切り替える場合
  • 除外ページへの遷移を検知して、特定の UI を表示・非表示にしたい場合

#注意事項

  • イベントが発火するのは、ページ遷移に伴って翻訳ブロック状態が変化した場合のみです。
  • ページ初回表示時の状態判定では発火しません。
  • ページを再読み込みした場合、発火しません。

#cookieOptIn()

#概要

訪問者がCookieの利用に同意したことを Autolingual SDKに通知するための関数です。

呼び出すと、SDK は訪問者が選択した言語を保存し、次回訪問時にも同じ言語で表示できるようになります。

#返り値

window.Autolingual.cookieOptIn(): void

#使い方

お客様のWebサイトに表示しているCookie同意バナーで、訪問者が「同意する」ボタンを押したタイミングで呼び出してください。

if (window.Autolingual && window.Autolingual.isReady()) {
  window.Autolingual.cookieOptIn();
} else {
  window.addEventListener("autolingual:ready", function () {
    window.Autolingual.cookieOptIn();
  });
}

#利用シーン

  • Cookie同意バナーで訪問者がCookieの利用に同意したとき

#cookieOptOut()

#概要

訪問者がCookieの利用に同意しなかった、または同意を撤回したことをAutolingual SDK に通知するための関数です。

呼び出すと、SDK は訪問者の言語選択を保存しなくなります。すでに保存されていた言語選択は削除されます。

#返り値

window.Autolingual.cookieOptOut(): void

#使い方

お客様のWebサイトに表示しているCookie同意バナーで、訪問者が「拒否する」ボタンや「同意を撤回する」ボタンを押したタイミングで呼び出してください。

if (window.Autolingual && window.Autolingual.isReady()) {
  window.Autolingual.cookieOptOut();
} else {
  window.addEventListener("autolingual:ready", function () {
    window.Autolingual.cookieOptOut();
  });
}

#利用シーン

  • Cookie同意バナーで訪問者がCookieの利用を拒否したとき
  • 一度同意した訪問者が後から同意を撤回したとき