国際化

UI には en、ja、de、fr、zh、ko、th の 7 つの組み込み辞書があります。初期ロケールは locale、ホスト側からマウント後に切り替えるときは instance.setLocale()、ラベルの上書きは strings または extend() で設定します。辞書の変更はスプレッドシートを作り直さずに UI へ反映されます。言語とワークブックプロファイルをまとめて切り替える流れは 言語を切り替える にまとめています。

初期ロケールを設定する

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

ロケールを省略すると、コントローラは ja の辞書で開始します。ホストが言語を選択する場合は、周囲のアプリケーションと同じロケールを渡します。マウント後にホストから切り替えるときは instance.setLocale() を使い、プロファイル、数式、失敗時の動作は 言語を切り替える を参照してください。instance.i18n.setLocale() は辞書や拡張のコードで使う低レベルの辞書通知です。

テーマとロケールの実行時切り替え

マウント済みのシートのテーマと言語を切り替えます。言語を変えると UI 辞書と計算プロファイルが一緒に切り替わり、関数名、引数区切り、小数点の表記が変わります。保存される数式は変わりません。

本物の Formulon エンジン (WASM) がこのページ内で動作します。データは送信されません。

ラベルを上書きする

マウント時のラベル上書きには strings、マウント後の変更には i18n.extend() を使います。Strings のネストした項目も、変更する箇所だけ指定できます。

const instance = await Spreadsheet.mount(host, {
  locale: 'ja',
  strings: {
    contextMenu: {
      copy: 'コピー',
      paste: '貼り付け',
    },
  },
})

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

extend() の上書きは指定したロケールに属します。別のロケールへ移動して戻っても、そのインスタンス内では上書きが保たれます。パッケージの辞書自体は変更されません。

React と Vue では同じ strings オブジェクトをコンポーネントのプロパティに渡せます。useI18n() は、ホスト側のコントロールとラベルを合わせるための現在のロケールと解決済み辞書を返します。

ホストのロケールを登録する

register() はホストが用意した完全な辞書を、指定したロケール id で追加します。公開型 Strings を使うと、パッケージの型宣言と辞書の形を合わせられます。

import { Spreadsheet, type Strings } from '@libraz/formulon-cell'

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

instance.i18n.register('sv', sv)
if (!instance.setLocale('sv')) {
  showLanguageError()
}

製品固有の少数の語だけを変える場合は、完全な辞書を管理せず en または ja を extend() する方法が簡単です。完全な辞書は JSON や翻訳データから読み込み、setLocale() の前に登録できます。同梱の辞書を元に翻訳を始める場合は、@libraz/formulon-cell/i18n/en（ja、de、fr、zh、ko、th も同様）から読み込みます。各モジュールの default エクスポートは完全な Strings オブジェクトです。

ロケール ID は組み込み辞書を解決するときに言語部分を使うため、de-DE と de_brand はドイツ語ラベルへフォールバックできます。カスタム ID に独自辞書を登録しても、ワークブックのプロファイルは選択されません。数式の意味論も変える場合は組み込み言語または地域 ID を使います。zh 辞書は簡体字です。zh-TW、zh-HK、zh-MO のロケールはラベルにこの辞書を使いつつ、ワークブックのプロファイルは繁体字中国語を選びます。繁体字のラベルは register('zh-TW', dictionary) で用意できます。地域、script、variant の扱いは 言語を切り替える にまとめています。

ロケールの変更を購読する

拡張やホスト側コントロールでは i18n.subscribe() が使えます。永続化にはインスタンスの localeChange イベントが便利です。

const off = instance.on('localeChange', ({ locale }) => {
  localStorage.setItem('spreadsheet-locale', locale)
})

const saved = localStorage.getItem('spreadsheet-locale') ?? 'ja'
if (!instance.setLocale(saved)) {
  showLanguageError()
}

ホスト側コントロールを削除するときは、返された関数を呼びます。フレームワークアダプターの useI18n() と useSpreadsheetEvent() はコンポーネントの寿命に合わせて購読を解除します。

UI ロケールと数式表示

コントローラが提供するのは、グリッドの周辺 UI、ダイアログ、メニュー、拡張のラベルです。数式補助に表示する関数名や説明をローカライズする場合は、WorkbookHandle.setFunctionMetadataProvider() でホスト側のカタログを渡せます。完全な数式文字列の変換、ローカライズ入力、UI 編集と WorkbookHandle の直接書き込みの境界は 言語を切り替える を参照してください。

次に読むページ

• フックとコンポーザブル — 選択状態、変更通知、言語設定を利用する具体例です。
• 言語を切り替える — セレクター、ホスト API、ワークブックプロファイル、数式文字列、切り戻しを説明します。
• API 一覧 ─ コントローラとイベントの入口
• React / Vue アダプター ─ プロパティ、イベント、フック、コンポーザブル
• テーマ ─ ロケールに合わせたホスト周辺 UI の調整