🔌 言葉蔵 (Kotobagura) 開発者向け API リファレンス
言葉蔵は、Chrome拡張機能のメッセージング（chrome.runtime.sendMessage）を利用して、外部アプリと連携することができます。連携には大きく分けて2つの方向性（役割）があります。
📥 パターンA
【外部 ➔ 言葉蔵】
自作の入力ツールや別の拡張機能から、言葉蔵にリクエストして漢字変換をしてもらう使い方です。言葉蔵が「サーバー」として振る舞います。
👇 仕様を見る
📤 パターンB
【言葉蔵 ➔ 外部】
言葉蔵が、外部の拡張機能（主に「ローカル漢字変換エンジン」）に対して、単語の検索や変換リクエストを行う使い方です。独自の辞書エンジンを自作して言葉蔵に繋ぎたい人向けです。
👇 仕様を見る
📥 パターンA: 外部アプリから「言葉蔵」を呼び出す
自作のWebアプリ（localhost）や他のChrome拡張機能から、言葉蔵をバックエンドの変換エンジンとして利用するためのAPI仕様です。
通信の基本形式
const KOTOBAGURA_ID = "jlalooojpaebmgahmikbgnnomdcmhgap"; // 言葉蔵の拡張機能ID
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "アクション名",
// パラメータ
}, (response) => {
console.log(response);
});
📋 API クイック一覧
※アクション名をクリックすると、詳細な仕様へジャンプします。
PING 接続確認・バージョン取得
起動時にエンジンがインストールされているか確認します。
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "PING" }, (res) => {
if (chrome.runtime.lastError) {
console.log("未インストールです。");
} else if (res && res.success) {
console.log("接続完了！バージョン:", res.version);
}
});
GET_ENGINE_STATUS エンジンのヘルスチェック
現在どのバックエンドや外部APIが正常に稼働し、通信可能な状態にあるかを取得します。
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "GET_ENGINE_STATUS" }, (res) => {
if (res && res.success) console.log("各エンジンの状態:", res.status);
});
【出力データ例】
{
"google": true,
"yahoo": false,
"localEngine": true,
"translation": {
"enabled": true,
"hasApiKey": true,
"isFreePlan": true,
"defaultLang": "EN-US"
},
"timestamp": 1690000000000
}
CONVERT 変換リクエスト
指定したひらがな文字列を変換します。言葉蔵特有のオプションにより、APIの入り口で入力を補正することが可能です。
- text (String): 変換したいひらがな、またはローマ字（必須）
- mode (String): 変換のアルゴリズムとレスポンスのデータ形式を指定します。（省略時は
"segmented"）
"kotobagura" : "segmented" と同じ挙動（後方互換用エイリアス）"segmented" (標準) : 言葉蔵のハイブリッドエンジンによる文節分割と、メタデータを含むリッチな統合データを返します。"auto" : 辞書と前後の文脈から自動的に一括結合した文字列を最優先の候補として返します。"localengine" (互換モード) : 外部の「ローカル漢字変換エンジン」と完全に同じシンプルな配列構造のみを data プロパティに返します。"google" / "yahoo" : 指定した各クラウドAPI単体の生のレスポンス構造をエミュレートして返します。
- useRomaji (Boolean): APIの入り口で自動的にひらがなに変換（例:
nagoya → なごや）
- preferHiraganaShort (Boolean): 2文字以下の入力時にひらがなを優先
- separateParticle (Boolean): 助詞の自動切り離し・オフラインフォールバックを有効化
- skipCache (Boolean): メモリ上のキャッシュを無視して強制的に外部APIへ再リクエストします。
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "CONVERT",
text: "nagoya",
mode: "kotobagura",
useRomaji: true
}, (res) => {
if (res && res.success) console.log("統合変換データ:", res.data);
});
【出力データ例①： mode: "segmented" (または "kotobagura", "auto") の場合】
{
"success": true,
"full_sentence_candidates": [
{
"candidate": "名古屋",
"sources": ["ビタビ(ローカル最適)", "Google", "Yahoo!", "Local"],
"yomi": "なごや"
}
],
"raw_data": {
"google": [ ... ],
"yahoo": { ... },
"local": [ ... ],
"builtin": [ ... ]
}
}
【出力データ例②： mode: "localengine" (または "google") の場合】
[
[ "なごや", [ "名古屋", "名護や", "なごや" ] ]
]
CONVERT_WITH_TRANSLATION 翻訳付き変換リクエスト
漢字変換を実行し、上位の変換候補に対して自動的にDeepLの翻訳（多言語対応）を取得して合体させます。
- mode (String):
CONVERT と同様ですが、安全に翻訳メタデータを付与するため "localengine" を指定しても強制的に "segmented"(標準) として処理されます。
- text, useRomaji 等:
CONVERT と全く同じオプションが適用されます。
- targetLang (String): 翻訳先の言語コード（例:
"EN-US", "ZH", "KO"）。省略時は言葉蔵のオプション画面で設定されたデフォルト言語が使用されます。
- transLimit (Number): 翻訳を取得する上位候補の件数（デフォルト: 5）。この数値を抑えることでAPIの無料枠消費を節約できます。
💡 スマートキャッシュ機能: 一度翻訳された単語は「言語コード:単語」の複合キーを用いて自動的にローカル（最大2,000件、LRU方式）に学習・キャッシュされます。同じ単語・同じ言語の組み合わせは次回以降API通信なし（消費文字数0）で即座に返されます。
🛡️ フェイルセーフ設計: 翻訳機能がOFFの場合や、APIキー未設定、あるいはDeepLの通信上限に達してエラーが起きた場合でも、漢字の変換結果自体は正常に返るため、ユーザーの入力を妨げることはありません。
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "CONVERT_WITH_TRANSLATION",
text: "きしゃ",
targetLang: "ZH", // 中国語への翻訳を強制指定
transLimit: 3
}, (res) => {
if (res && res.success) {
// 各候補のオブジェクトに `translation` プロパティが追加されます
console.log("最上位候補:", res.full_sentence_candidates[0]);
}
});
【出力データ例】
{
"success": true,
"full_sentence_candidates": [
{
"candidate": "貴社",
"sources": ["Google"],
"yomi": "きしゃ",
"translation": "贵公司",
"translationSource": "DeepL (ZH)"
}
]
}
BULK_CONVERT 一括変換リクエスト
複数のテキストを配列として渡し、並列処理で一気に変換します。外部アプリから大量の文章を処理する際、通信オーバーヘッドを抑えるために強く推奨されます。
- texts (Array): 変換したいひらがな/ローマ字の文字列が格納された配列（必須）
- mode (String):
CONVERT と同様の変換モード指定
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "BULK_CONVERT",
texts: ["きょうは", "いい", "てんきです"],
mode: "segmented"
}, (res) => {
if (res && res.success) console.log("一括変換結果:", res.results);
});
【出力データ例】
[
{ "success": true, "data": [ ... ] }, // 「きょうは」の変換結果
{ "success": true, "data": [ ... ] }, // 「いい」の変換結果
{ "success": true, "data": [ ... ] } // 「てんきです」の変換結果
]
SUGGEST 予測変換
入力中の文字（前方一致）から、予測候補を返します。
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "SUGGEST",
text: "かかみ",
limit: 5
}, (res) => {
if (res && res.success) console.log("予測候補:", res.suggestions);
});
【出力データ例】
[
{ "yomi": "かかみがはら", "word": "各務原", "source": "user" },
{ "yomi": "かかみ", "word": "各務", "source": "skk" }
]
LEARN / UNLEARN 学習・履歴管理
確定した変換を記録して優先度を上げる、または誤って確定してしまった単語をピンポイントで削除します。
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "LEARN", // 誤学習を消す場合は "UNLEARN" に変更
yomi: "かかみがはら",
kanji: "各務原"
}, (res) => {
if (res && res.success) console.log("処理が完了しました");
});
SEARCH_DICT 辞書・履歴検索
「よみ」または「漢字」をキーワードとして横断検索します。
- keyword (String): 検索したいキーワード
- exactMatch (Boolean):
true にすると完全一致検索、false または省略時は部分一致検索になります。
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "SEARCH_DICT",
keyword: "各務原",
exactMatch: true
}, (res) => {
if (res && res.success) console.log("検索結果:", res.results);
});
【出力データ例】
[
{ "yomi": "かかみがはら", "word": "各務原", "source": "skk" },
{ "yomi": "かかみがはらし", "word": "各務原市", "source": "user" }
]
TEST_DEEPL / TEST_YAHOO 各API接続テスト
対象のAPIへ軽量なテストリクエストを送信し、APIキーの有効性を判定します。
// DeepL API のテスト (Freeプランかどうかも判定)
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "TEST_DEEPL",
apiKey: "your-api-key:fx"
}, (res) => {
if (res && res.success) console.log("DeepL接続成功！Freeプランか？:", res.isFree);
});
// Yahoo! クラウド変換API のテスト
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "TEST_YAHOO",
apiKey: "your-yahoo-client-id"
}, (res) => {
if (res && res.success) console.log("Yahoo! 接続成功！");
});
OPEN_API_SETUP_PANEL API登録パネルの呼び出し
アクティブなタブの画面上に、言葉蔵の「APIキー設定パネル」を直接オーバーレイ表示させます。
外部の拡張機能が言葉蔵の翻訳機能等を使いたい時、ユーザーをわざわざ言葉蔵のオプション画面へ飛ばすことなく、その場でシームレスにキー登録と通信テストを促すことができます。
- target (String): 表示する入力欄を指定します。
"deepl" : DeepL翻訳のAPIキー入力欄のみを表示します。"yahoo" : Yahoo!クラウド変換のClient ID入力欄のみを表示します。"all" : 両方の入力欄を表示します。（省略時のデフォルト）
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "OPEN_API_SETUP_PANEL",
target: "deepl"
});
💡 スマート仕様: パネル内で「テストして保存」を実行し接続に成功すると、対象のAPIキーが保存されると同時に、言葉蔵本体の機能設定（翻訳機能やクラウド変換のON/OFF）も自動的に「有効化(ON)」されます。
GET_STATS 統計取得
現在の各辞書の登録単語数や学習履歴の統計データを返します。
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "GET_STATS" }, (res) => {
if (res && res.success) console.log("統計データ:", res.stats);
});
【出力データ例】
{
"skk": 285400,
"user": 15,
"learned": 42,
"additional": 10500
}
GET_SETTINGS / UPDATE_SETTINGS 設定の取得・更新
エンジンの各種設定（クラウドAPIのON/OFF、ローマ字入力の有無など）を一括で取得・更新します。自作のキーボードアプリ内に設定画面を作る場合に便利です。
// 実働サンプル：設定を取得して、クラウド変換（Google/Yahoo等）をオフに書き換える
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "GET_SETTINGS" }, (res) => {
console.log("現在の設定:", res.settings);
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "UPDATE_SETTINGS",
config: { useCloudApi: false }
}, () => {
console.log("設定を更新しました");
});
});
SET_TEMP_DICT 一時辞書の登録
アプリ起動中のみ有効なカスタム辞書をメモリ上にセットします。ゲーム固有の専門用語などに最適です。
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "SET_TEMP_DICT",
dict: {
"あるす": ["勇者アルス"],
"まほう": ["メラゾーマ", "ホイミ"]
}
}, (res) => {
if (res && res.success) console.log(`${res.count}件の一時単語を登録しました`);
});
OPEN_HISTORY_PANEL 履歴パネルを開く
ユーザーの現在アクティブなタブに、履歴管理パネルを直接注入して表示させます。
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "OPEN_HISTORY_PANEL" });
GET_MEMO_PAD_STATUS / TOGGLE_MEMO_PAD メモ帳の表示制御
アクティブなタブ上での簡易メモ帳の表示状態の取得、および開閉を行います。
// 状態の取得
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "GET_MEMO_PAD_STATUS" }, (res) => {
if (res && res.success) console.log("メモ帳は開いているか？:", res.isOpen);
});
// メモ帳の開閉（トグル）
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "TOGGLE_MEMO_PAD" });
GET_MEMO_TEXT / SET_MEMO_TEXT / CLEAR_MEMO メモ帳のテキスト操作
メモ帳に入力されているテキストを取得、または外部から流し込みます。
💡 メモ帳の画面が開いていなくてもバックグラウンドで操作可能なため、他の拡張機能から画面を邪魔せずにテキストをストックさせる連携などに便利です。
// テキストの取得
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "GET_MEMO_TEXT" }, (res) => {
if (res && res.success) console.log("メモの内容:", res.text);
});
// テキストの設定（上書き or 追記）
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "SET_MEMO_TEXT",
text: "追加したいテキスト\n",
mode: "append" // "overwrite": 上書き, "append": 追記
});
// メモ帳のクリア
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "CLEAR_MEMO" });
GET_KEYBOARD_STATUS / SET_KEYBOARD_ENABLED キーボード機能の制御
設定画面を開かずに、API経由で「言葉蔵 Keyboard」機能の有効/無効を切り替えます。
// 状態の取得
chrome.runtime.sendMessage(KOTOBAGURA_ID, { action: "GET_KEYBOARD_STATUS" }, (res) => {
if (res && res.success) console.log("キーボード有効状態:", res.enabled);
});
// 有効/無効の切り替え
chrome.runtime.sendMessage(KOTOBAGURA_ID, {
action: "SET_KEYBOARD_ENABLED",
enabled: true // true で有効、false で無効
}, (res) => {
if (res && res.success) console.log("変更後の状態:", res.enabled);
});
💻 実践的な呼び出しコード例（安全な組み込み方）
実際の拡張機能やWebアプリに言葉蔵（パターンA）を組み込む際は、言葉蔵の未インストールや、スリープ復帰時の遅延に備え、タイムアウト処理を実装することを強く推奨します。
const KOTOBAGURA_ID = "jlalooojpaebmgahmikbgnnomdcmhgap"; // 本拡張機能のID（chrome://extensions/ で確認できます）
async function fetchKotobagura(text) {
return new Promise((resolve, reject) => {
// 外部APIの通信遅延やスリープ復帰を考慮し、タイムアウトを 1500ms に設定して無限待機を防ぐ
const timeout = setTimeout(() => reject(new Error("Kotobagura timeout")), 1500);
chrome.runtime.sendMessage(
KOTOBAGURA_ID,
{ action: "CONVERT", text: text, mode: "kotobagura" },
(response) => {
// 返事があった時点でタイマーを止める
clearTimeout(timeout);
// 拡張機能が未インストールの場合はここで弾かれる
if (chrome.runtime.lastError) {
return reject(new Error("Kotobagura not found: " + chrome.runtime.lastError.message));
}
// エンジン側の処理エラー
if (!response || !response.success) return reject(new Error("Kotobagura error"));
// 成功：変換結果の配列を返す
resolve(response.data);
}
);
});
}
💡 応用例：エンジン応答エラー時の再読み込み（リトライ）実装
ユーザーがブラウザを起動した直後や、拡張機能がスリープ（サスペンド）している状態だと、初回の通信がタイムアウトすることがあります。その場合に備えて、「再読み込み（リトライ）ボタン」を画面に表示するUIの実装サンプルです。
// --- JavaScriptの実装 ---
async function convertWithRetry(text) {
const errorBox = document.getElementById("error-box");
const retryBtn = document.getElementById("retry-btn");
try {
errorBox.style.display = "none";
// さきほど定義した安全なラッパー関数を呼び出す
const data = await fetchKotobagura(text);
console.log("変換結果:", data);
} catch (error) {
console.warn("変換リクエスト失敗:", error.message);
errorBox.style.display = "block";
retryBtn.onclick = () => convertWithRetry(text);
}
}
📤 パターンB: 言葉蔵から「外部エンジン」を呼び出す
言葉蔵は、外部API（Google/Yahoo）とは別に、オフラインで動作する「ローカル漢字変換エンジン」へ変換リクエストを投げる機能を持っています。
言葉蔵の設定画面で「カスタムエンジンID」を指定することで、ご自身で開発した独自の拡張機能を「ローカルエンジン」として言葉蔵のバックエンドに接続することができます。
リクエスト (言葉蔵 ➔ あなたの自作エンジン)
あなたの拡張機能の background.js にて、言葉蔵からの CONVERT 要求を待ち受けます。
chrome.runtime.onMessageExternal.addListener((request, sender, sendResponse) => {
if (request.action === "CONVERT") {
const hiragana = request.text; // 例: "かかみがはら"
// --- ここで独自の辞書検索やAI変換処理を行う ---
// 処理が終わったら sendResponse で言葉蔵に返す
sendResponse({
success: true,
data: ["各務原", "各務ヶ原"] // ← 簡単な文字列配列でOK
});
return true; // 非同期で返す場合は必須
}
});
レスポンス仕様 (あなたの自作エンジン ➔ 言葉蔵)
言葉蔵は非常に柔軟なパーサーを搭載しているため、sendResponse の data プロパティに以下のいずれかの形式を渡せば、自動的に解析して候補として取り込みます。
- シンプル配列 (推奨):
["漢字1", "漢字2", ...] のように変換候補の文字列だけを配列で返す形式。
- Google API互換:
[["かかみがはら", ["各務原", "各務ヶ原"]]] のような多重配列形式。
- Yahoo API互換:
{ result: { segment: [{ candidate: ["各務原", "各務ヶ原"] }] } } のようなJSON形式。
【🛡️ 必須ルール：無限ループの防止について】
言葉蔵から CONVERT のリクエストを受け取った際、独自の処理の中で言葉蔵に対してさらに CONVERT をリクエストして返す（聞き返す）ことは絶対に避けてください。通信が無限ループに陥り、ブラウザがフリーズします。
ただし、処理の過程で言葉蔵の SEARCH_DICT（履歴の検索）等を呼び出して「データを読み取るだけ」の通信は安全に行えます。
💡 設定画面の「接続テスト」への対応 (PING応答)
言葉蔵の設定画面にある「テスト」ボタンは、まず外部エンジンに対して PING リクエストを送り、応答がなければダミーテキストで CONVERT リクエストを送る「2段構え」で生存確認を行います。
そのため、CONVERT のみを実装している特化型エンジンであってもテストは正常に「成功」と判定されますが、以下のように PING に対する応答を実装しておくと、言葉蔵の設定画面にエンジンのバージョン番号を表示させることができ、よりスマートな連携が可能になります。
chrome.runtime.onMessageExternal.addListener((request, sender, sendResponse) => {
// PINGリクエストへの応答（推奨）
if (request.action === "PING") {
sendResponse({
success: true,
version: chrome.runtime.getManifest().version // オプション：言葉蔵の設定画面にバージョンが表示されます
});
return true;
}
// CONVERTリクエストへの応答
if (request.action === "CONVERT") {
// ...
}
});
⚡ 制限事項とパフォーマンス（API制限について）
- スマートキャッシュによる通信削減と爆速化:
言葉蔵は一度取得した変換結果（およびDeepL翻訳結果）をメモリ上に保持するため、同じ言葉を連続で変換する際は、外部通信を一切行わずに0.001秒で即時生成されます。
- クラウドAPI利用時の制限 (パターンA利用時):
「クラウド変換(Google/Yahoo)」が有効な場合、自作アプリ等から未知の単語で数千件単位の大量リクエストを行うと、GoogleやYahoo!から一時的な利用制限（429 Too Many Requests）を受ける可能性があります。大量処理時は非同期でゆっくり回すか、クラウド変換をOFFにしてください。
- 完全ローカル動作時の「無制限」:
クラウド変換を無効化し、「ローカル漢字変換エンジン」「内蔵辞書」のみで動作させる場合、ネットワーク通信が発生しないため、APIの利用制限は一切ありません。