オンデバイス辞書

アプリケーションに組み込む辞書。パッケージのインストール、同期、オフラインでの検索、インストールの状態の読み方。

できること

immit の日本語・英語辞書を、ユーザーのデバイス上で使えます。ファイル、検索エンジン、更新フィードは、immit 自身のアプリケーションが使っているものと同じです。検索は数ミリ秒で応答し、ウェブページでもブラウザ拡張機能でもオフラインで動作し、API 残高は消費しません。

コンソールでオンデバイス辞書を追加すると、すぐにライセンスキーが発行されます。ライセンスの支払いが済むまでは、各言語の頻出 2,000 語のサンプルがインストールされ、開発とテストにはこれで足ります。支払いが済むと、ライセンスの対象言語の完全な辞書がインストールされます。

インストール

npm
npm install @immit/dictionary

ライセンスキーは、アプリケーションに組み込んで配布するためのものです。API キーはそうではなく、決して配布しないでください。

開いて同期する

JavaScript
import { openDictionary } from '@immit/dictionary'

const dictionary = await openDictionary({ licenseKey: 'il_...' })

await dictionary.sync()

const { entries, matched } = await dictionary.lookup('時間がない。', 'jpn')
// matched is '時間', the word the text starts with

openDictionary は何もダウンロードしません。sync() は immit にチェックインし、デバイスに辞書ファイルがない場合やライセンスの対象が変わった場合にファイルをインストールし、完全な辞書であれば前回の同期以降に変更されたエントリーを反映します。サンプルは更新されません。オンラインでアプリケーションを起動するたびに sync() を呼び出してください。

最初の同期ではファイル全体をダウンロードするため、進捗を表示してください。

JavaScript
dictionary.subscribe((status) => {
  if (status.phase === 'downloading' && status.download) {
    const { receivedMb, totalMb } = status.download
    console.log(`${receivedMb} of ${totalMb} MB`)
  }
})
ファイルダウンロードデバイス上
サンプル11 MB18 MB
英語132 MB182 MB
日本語295 MB526 MB
日本語と英語427 MB707 MB

サイズは目安で、辞書の拡充とともに大きくなります。インストール中は、ファイルを配置するためにサイズの約 2 倍の空き容量が必要です。容量が足りなくなった同期は failed で終わります。

呼び出すもの

  • lookup(text, lang) は text の先頭にある単語を探します。日本語では、ホバーした文字以降のテキストを渡してください。先頭から始まる最も長い単語が見つかり、活用形は見出し語として返され、matched はテキストのうち単語だった部分です。英語では 1 語を渡してください。最大 20 件のエントリーを、適合度の高い順に返します。
  • search(query, lang, options) は、見出し語が query で始まるエントリー、または読みや活用形が query であるエントリーを 1 ページ分返します。options には page と perPage を指定します。
  • entry(id) は、lookup や search が返した id のエントリーを 1 件、または null を返します。
  • sync() は、実行が終わった時点の状態で解決します。ネットワークやライセンスが原因で止まっても reject しません。status.lastSync.error を確認してください。
  • status() はインストールの状態を返します。subscribe(listener) は変更のたびに通知を受け取り、購読を止める関数を返します。
  • close() は辞書のファイルを手放し、別のタブが引き継げるようにします。

lang は "eng" または "jpn" です。エントリーには、語義とその訳・例文、発音、活用、表記、関連語が含まれます。すべてのフィールドはパッケージの型定義に記載されています。エントリーに音声は含まれません。各発音には、immit のサーバー上の音声へのリンクが含まれます。

インストールの状態

status.state は次の 3 つのいずれかです。

状態意味
empty辞書ファイルがインストールされていません。sync() でインストールされます。
ready検索に応答します。
expiredsync() でチェックインするまで、検索は拒否されます。

90 日間チェックインしていないインストールは、再びチェックインするまで応答を停止します。同期はチェックインを兼ねています。status.lease.daysLeft は、インストールに残された日数です。長くオフラインだったユーザーに表示してください。ユーザーへの通知は開発者側で行います。

デバイスの空き容量が少なくなると、ブラウザがサイトのストレージを消去することがあります。その場合、インストールは empty の状態で開き、次回の同期でファイルが再びインストールされます。navigator.storage.persist() で、ブラウザに保持を求めることができます。

エラー

失敗した呼び出しは DictionaryError で reject されます。code で分岐してください。

コード意味と対処
not_installed辞書ファイルがインストールされていません。sync() を呼び出してください。
lease_expiredインストールが 90 日間チェックインしていません。オンラインで sync() を呼び出してください。
invalid_request引数が、その呼び出しで受け付けられないものです。メッセージに該当の引数が示されます。
unsupportedこのコンテキストでは辞書を保持できません。メッセージに不足しているものが示されます。
storage_unavailableブラウザが辞書のファイルへのアクセスを拒否しました。
closedこの辞書に対して close() が呼び出されました。
failed上記以外。メッセージに内容が示されます。

同期が途中で終わったとき

途中で終わった同期は、その理由を status.lastSync.error に code と message で示します。この表にないコードは、API のエラーコードのいずれか、または応答にコードがなかった場合の http_ とステータスです。

コード意味と対処
networkimmit に接続できませんでした。次回の同期で再試行されます。
license_key_invalidimmit が発行したキーではありません。ビルドに含まれているキーを確認してください。
license_lapsedライセンスが未払いです。インストールは残りの日数のあいだ応答を続けます。コンソールで支払うと、次回の同期から再び提供されます。
not_licensedインストール済みのファイルに含まれる言語が、ライセンスの対象外です。次回の同期で修正されます。
rate_limitedimmit へのリクエストが多すぎます。次回の同期で再試行されます。
artifact_unavailable辞書ファイルの準備がまだできていません。次回の同期で再試行されます。
schema_unsupportedこのバージョンのパッケージは提供を終了しました。パッケージを更新してください。
lease_unverifiedチェックインに応答したのが immit ではありませんでした。
failed上記以外。インストール中の容量不足も含まれます。メッセージに内容が示されます。

同期のエラーが、応答中のインストールを止めることはありません。残りの日数のあいだ、応答を続けます。

動作環境

辞書は専用のワーカーで動作し、ファイルをオリジンプライベートファイルシステムに保存するため、ページまたは拡張機能のページから開けます。サービスワーカーとコンテンツスクリプトからは開けません。

  • Chromium 系ブラウザ。ページと Manifest V3 拡張機能を対象に、パッケージを構築・テストしています。
  • Safari。同じテストが Playwright の WebKit ビルドで通っています。Safari 本体では実行していません。
  • Firefox。未テストです。

同じオリジンのすべてのタブが、1 つのコピーを共有します。最初に辞書を開いたタブがファイルを保持して他のタブに応答し、そのタブが閉じると別のタブが引き継ぎます。ウェブアプリと拡張機能はオリジンが異なるため、それぞれが自分のコピーを保持します。

Manifest V3 の拡張機能では、オフスクリーンドキュメントまたは拡張機能のページで辞書を開き、サービスワーカーやコンテンツスクリプトからメッセージを送ってください。オフスクリーンドキュメントには offscreen 権限が必要で、WORKERS を理由として作成します。辞書のためのホスト権限は不要です。

コンテンツセキュリティポリシーで WebAssembly を許可する必要があります:script-src 'self' 'wasm-unsafe-eval'。拡張機能では content_security_policy.extension_pages に設定します。connect-src を設定している場合は、https://api.immit.co と、辞書ファイルの配信元である https://t3.storage.dev も許可してください。許可がないと、すべての同期が network で終わります。

インストール数と請求

インストールとは、1 台のデバイス上の辞書のコピー 1 つです。1 人が複数持つこともあります。デバイスごと、ブラウザのプロファイルごと、同じデバイス上のアプリケーションや拡張機能ごとに、それぞれコピーを保持します。immit は、1 か月のあいだにあなたのキーでチェックインしたインストールを、それぞれ 1 回ずつ数えます。

初月は $12 です。翌月以降は、前月に数えたインストール数に応じて、1,000 インストールごと(端数は切り上げ)に $12 が登録済みのカードに請求されます。コンソールには、今月のインストール数、それに応じた請求額、ライセンスの支払い済みの最終日が表示されます。50,000 インストールを超える場合は、ボリューム価格についてお問い合わせください。

請求に失敗した場合、immit はメールでお知らせし、7 日間にわたってカードへの請求を再試行します。それでも未払いの場合、ライセンスは失効します。インストールは更新されなくなり、それぞれ 90 日以内に応答を停止します。コンソールで支払うと、ライセンスは再開されます。解約はコンソールからいつでも行え、ライセンスは支払い済みの月の終わりまで有効です。

デバイスの外に送られるもの

同期では、ライセンスキーとデバイス上で生成されたランダムな ID が immit に送信され、ファイルとその更新がダウンロードされます。ユーザーを特定する情報や、ユーザーが読んだり調べたりした内容は、デバイスの外に送られません。チェックインについては、あなたのプライバシー通知でユーザーに伝えてください。ライセンスに、そのまま使える文面があります。

ライセンス

パッケージはオンデバイス辞書ライセンスのもとで提供され、オンデバイス辞書をアカウントに追加した時点で同意したことになります。NOTICES.md には、辞書が利用しているオープンデータが、それぞれのライセンスとともに記載されています。このファイルは、あなたのプロダクトの通知と一緒に保持してください。辞書データを表示するプロダクトには、immit.co へのリンクを付けた「Dictionary data by immit」の一文を表示します。

immit は、公開したパッケージの各バージョンを、後継バージョンの公開から 12 か月間提供します。その後、そのバージョンのインストールは応答を続けますが更新を受け取らなくなり、新規のインストールは schema_unsupported を報告します。