EmDash管理画面を日本語化するプラグインを作った(現在はプラグイン不要で日本語対応)

追記：2026/04/14 emdash@0.4.0 で日本語のサポートがされたのでこれは不要になりました😅

EmDash の管理画面は英語UIですが、運用メンバーによっては日本語表示のほうが扱いやすいケースがあります。
そこで、管理画面の文言を日本語化するプラグイン @mammosu/emdash-plugin-admin-ja を作成しました。

できること

• EmDash 管理画面の主要文言を日本語化
• 動的に追加されるUI（非同期描画）にも追従
• placeholder / title / aria-label の属性文言も変換
• 開発時に「未翻訳候補」を収集してコンソール出力

インストール

npm からインストール

npm i @mammosu/emdash-plugin-admin-ja

src/plugins に clone / pull してローカル参照で使う

git clone https://github.com/mammosu/emdash-plugin-admin-ja.git
cd emdash-plugin-admin-ja
git pull

astro.config.mjs などでプラグインを追加します。

import { adminJapanesePlugin } from "@mammosu/emdash-plugin-admin-ja";

emdash({
  plugins: [
    adminJapanesePlugin(),
  ],
});

仕組み

このプラグインは、管理画面のDOMに対してクライアント側で翻訳を適用します。流れは次の通りです。

1. ページ初期化時に document.body を走査
2. テキストノードを辞書（TEXT_MAP）で日本語化
3. placeholder / title / aria-label を辞書（ATTR_MAP）で日本語化
4. 取りこぼしを減らすため、部分一致ルール（SUBSTRING_MAP）で補完
5. MutationObserver でDOM更新を監視し、後から描画された要素にも同じ処理を再適用

安全性のための除外ルール

誤変換を防ぐため、以下は翻訳対象から除外しています。

• フォーム入力系: input, textarea, select, option
• 編集領域: contenteditable="true"、.ProseMirror
• 非表示/スクリプト系: script, style, noscript

開発時の改善フロー

PUBLIC_EMDASH_ADMIN_JA_DEBUG=1 を有効にすると、未翻訳候補を収集してコンソール出力します。
この候補を辞書へ追加していくことで、翻訳カバレッジを継続的に高められます。

実装のポイント

1. 完全一致辞書（TEXT_MAP）で代表的なUI文言を変換
2. 属性辞書（ATTR_MAP）で placeholder / title / aria-label を変換
3. 部分一致置換（SUBSTRING_MAP）で Edit xxx → 編集 xxx のようなパターンに対応

さらに MutationObserver で DOM 変化を監視し、後から追加された要素にも翻訳を適用しています。

開発時デバッグ（未翻訳候補の収集）

.env に以下を設定すると、開発時のみ未翻訳候補をコンソール出力します。

PUBLIC_EMDASH_ADMIN_JA_DEBUG=1

現時点の懸念点

導入前に把握しておきたいポイントもあります。

1. npm 公開パッケージとしての互換性
   現状は exports が src/*.ts を直接参照しているため、利用環境によっては .ts を解決できず動作しない可能性があります。配布時はビルド済みJS（dist）を公開対象にする構成が安全です。

2. パフォーマンスへの影響
   MutationObserver で subtree と characterData を広く監視しているため、管理画面の更新頻度が高いケースでは処理コストが増える可能性があります。

3. 置換ベース翻訳の誤変換リスク
   辞書の完全一致と部分一致ルールで翻訳しているため、文脈依存の文言では不自然な訳や意図しない置換が起きる可能性があります。

4. 辞書メンテナンスの負荷
   EmDash本体のUI変更に追従するため、辞書の継続更新が必要です。バージョン更新時に未翻訳候補を確認する運用が前提になります。

5. テスト不足による退行リスク
   翻訳品質やパフォーマンス劣化を自動検知する仕組みがないと、更新時の退行を見逃す可能性があります。スモークテストやE2Eの追加が有効です。

まとめ

• EmDash 管理画面の日本語化を、プラグインとして低コストに導入可能
• 動的UIにも追従し、実運用で使いやすい構成
• 未翻訳候補の収集機能で継続的に精度改善しやすい

結論

もっといい方法があるはず！

このプラグインは公開リポジトリですのでぜひ導入・活用してください。Issue / PR も歓迎です。