国際化

formulon-cell は en と ja の辞書を同梱しています。ロケールはランタイムで切替可能で、ラベルは remount なしに置き換わります。ホストは同梱辞書を上書きしたり、新規ロケールを登録できます。

用語: i18n コントローラ

SpreadsheetInstance.i18n で公開される実行時コントローラです。アクティブロケール、辞書レジストリ、変更時のストア通知を担当し、組み込み UI の再描画を促します。

ロケール切替

const instance = await Spreadsheet.mount(host, { workbook, locale: 'en' })

instance.i18n.setLocale('ja')

切替後に localeChange イベントが発火するため、ステータスバーや永続化レイヤを同期できます。

fork せず上書きする

i18n.extend(locale, partialDictionary) で既存辞書の上にマージします。

instance.i18n.extend('ja', {
  contextMenu: {
    copy: 'コピーする'
  }
})

上書きは実行中インスタンスのみに効きます。パッケージ同梱の辞書本体は変わりません。

宣言的な代替手段: strings プロパティ

React / Vue アダプタは <Spreadsheet> に strings プロパティを受け取ります（vanilla パッケージでは MountOptions.strings）。これはマウント直後に適用され、自分で i18n.extend(locale, strings) を呼ぶのと等価です。コントローラを命令的に呼ぶより、他のマウントプロパティと並べて宣言的に上書きを書きたい場合に使ってください。

新規ロケールを登録する

import fr from './locales/fr.js'

instance.i18n.register('fr', fr)
instance.i18n.setLocale('fr')

ロケールは plain な JS 値です。同梱辞書と同じ形に揃えてください。例（抜粋）:

export default {
  contextMenu: {
    copy: 'Copier',
    paste: 'Coller',
    pasteSpecial: 'Collage spécial…',
    cut: 'Couper'
  },
  toolbar: {
    bold: 'Gras',
    italic: 'Italique',
    underline: 'Souligner'
  },
  // ...
}

辞書は静的 JSON、非同期ロード、翻訳パイプラインからの生成、どの形でも構いません。

辞書を読む

ホスト UI や拡張は、コントローラの strings プロパティ経由でアクティブな辞書を読めます ─ t(key) のようなアクセサはありません。

const label = instance.i18n.strings.contextMenu.copy

組み込み UI も同じように strings ツリーから直接ラベルを読んでいます。strings は常にアクティブなロケール（と extend() による上書き）を反映します。登録した辞書でキーが欠けている場合は同梱の英語辞書にフォールバックするため、UI に生のキーが出ることはありません。

UI ロケールとエンジンの互換性プロファイルは別

エンジン側のロケール挙動（日付パース・通貨・リスト区切り）は Excel の 互換性プロファイル で決まり、UI の i18n.setLocale とは独立です。UI をフランス語にしても数式評価結果は変わりません。エンジン側はロケールプロファイルを参照。

関数メタデータのローカライズ

上記の辞書は組み込み UI のラベルを対象とし、自動補完や数式ツールチップの裏にある関数カタログは含みません。これらはエンジンの構造的な関数カタログから来ます。関数のシグネチャ・説明・表示名をローカライズするには、ワークブックにプロバイダを登録します。

wb.setFunctionMetadataProvider({
  SUM: {
    aliases: { 'ja-JP': '合計' },
    localized: {
      'ja-JP': {
        signature: 'SUM(数値1, [数値2], …)',
        description: '範囲内の数値を合計します。'
      }
    }
  }
})

キーは正規化した大文字の関数名です。null を渡すとプロバイダを解除します。各フィールドは locale-override → entry-default → engine-value の優先順でフォールバックするため、変更したい項目だけを与え、引数個数などその他はエンジンに任せられます。プロバイダのメタデータは表示専用で、数式のパースや評価には影響しません。

ライブなワークブックの外でカタログをマージする用途に、純粋なヘルパー mergeFunctionMetadata（LOCALE_TAGS と localeTag も同様）を export しています。

ユーザー選択の永続化

localeChange を購読してホスト側で永続化します。パッケージは自動で localStorage に書きません。

instance.on('localeChange', ({ locale }) => {
  localStorage.setItem('cell.locale', locale)
})

次回マウント時:

const saved = localStorage.getItem('cell.locale') ?? 'ja'
const instance = await Spreadsheet.mount(host, { workbook, locale: saved })

次に読むもの

埋め込みガイド ─ プリセットと拡張の組み合わせ
API 一覧 ─ イベント / ストア / コマンドヘルパー

国際化 ​

ロケール切替 ​

fork せず上書きする ​

新規ロケールを登録する ​

辞書を読む ​

関数メタデータのローカライズ ​

ユーザー選択の永続化 ​

次に読むもの ​

国際化