@yamat47/playmaker 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # @yamat47/playmaker
 
-アメリカンフットボールのプレー図を作成・表示する、UI フレームワーク非依存の TypeScript ライブラリ。
-コンテナ要素に図を描き、編集 UI を置き、編集のたびに `PlayData` を渡す。永続化や共有は持たない。
+A UI-framework-agnostic TypeScript library for creating and displaying American football play diagrams.
+It draws the diagram in a container element, places the editing UI, and delivers `PlayData` on every edit. It does not persist or share anything.
 
-- デモ: https://playmaker-demo.yamat47.me/
-- ソースと詳しい使い方: https://github.com/yamat47/playmaker
+- Demo: https://playmaker-demo.yamat47.me/
+- Source and detailed usage: https://github.com/yamat47/playmaker
 
-## インストール
+## Installation
 
 ```sh
 npm install @yamat47/playmaker
@@ -17,14 +17,15 @@ import { Playmaker, type PlayData } from "@yamat47/playmaker";
 import "@yamat47/playmaker/styles.css";
 
 const playmaker = new Playmaker(document.getElementById("play")!, {
-  mode: "edit", // "edit"（既定・編集 UI あり）/ "view"（読み取り専用）
-  initialData: saved, // 永続化しておいた PlayData（省略可）
+  mode: "edit", // "edit" (default, with editing UI) / "view" (read-only)
+  locale: "en", // language of the editing UI: "en" (default) / "ja"
+  initialData: saved, // a persisted PlayData (optional)
   onChange: (data: PlayData) => save(JSON.stringify(data)),
 });
 ```
 
-バンドラを通さず、CDN から読むこともできる。依存は無く、フォントは JS に同梱してある。
-URL の `0.1.0` は使う版に置き換える。
+You can also load it from a CDN without a bundler. It has no dependencies, and the fonts are bundled into the JS.
+Replace `0.1.0` in the URL with the version you use.
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@yamat47/playmaker@0.1.0/dist/playmaker.css" />
@@ -35,18 +36,18 @@ URL の `0.1.0` は使う版に置き換える。
 </script>
 ```
 
-モダンブラウザと PC のマウス操作を想定する。
+It assumes modern browsers and mouse input on a PC.
 
-## できること
+## What it does
 
-- 選手（丸・四角）とラベル、ルート・ブロック・モーションの線を置き、ドラッグで動かす
-- 位置は 0.5 ヤードの格子に揃う
-- 同梱のフォーメーションとプレーのプリセットを読み込む（`FORMATION_PRESETS`、`PLAY_PRESETS`）
-- 編集 UI を含まない PNG を書き出す（`exportToPng`）
-- 色とフォントは CSS 変数（`--playmaker-*`）でホストに合わせる
+- Place players (circles and squares) with labels, and route, block, and motion lines, and move them by dragging
+- Positions snap to a 0.5-yard grid
+- Load the bundled formation and play presets (`FORMATION_PRESETS`, `PLAY_PRESETS`)
+- Export a PNG without the editing UI (`exportToPng`)
+- Match the colors and fonts to the host with CSS variables (`--playmaker-*`)
 
-公開 API の一覧、`PlayData` の形、テーマの変数は、リポジトリの README にある。
+The list of the public API, the shape of `PlayData`, and the theme variables are in the repository README.
 
-## ライセンス
+## License
 
 MIT

package/dist/playmaker.d.ts

@@ -1,41 +1,43 @@
 /**
- * 今の PlayData のスキーマの版。スキーマを変えるときは 1 上げ、`PLAY_DATA_MIGRATIONS` に
- * 1 つ前の版から変換する段を足す。
+ * Current version of the PlayData schema. When the schema changes, raise it by 1 and add a step
+ * to `PLAY_DATA_MIGRATIONS` that converts from the previous version.
  */
 export declare const CURRENT_PLAY_DATA_VERSION: 2;
 
-/** リスナを登録し、購読をやめるための IDisposable を返す。 */
+/** Registers a listener and returns an IDisposable that ends the subscription. */
 declare type Event_2<T> = (listener: (e: T) => void) => IDisposable;
 export { Event_2 as Event }
 
 /**
- * サイドラインの間の幅。規定は 160 フィート（53⅓ ヤード）だが、中央（26.5）が
- * 0.5 ヤードの格子点に乗るように 53 ヤードへ丸める。本物の寸法との差は 1 フィートで、
- * 図の見た目には出ない。
+ * Width between the sidelines. The rule says 160 feet (53⅓ yards), but it is rounded to 53 yards
+ * so that the center (26.5) lands on a 0.5 yard grid point. The difference from the real
+ * dimension is 1 foot, which does not show in the diagram.
  */
 export declare const FIELD_WIDTH_YARDS = 53;
 
+/** English names of the zones. The `en` dictionary uses them; other locales carry their own. */
 export declare const FIELD_ZONE_LABELS: {
-    readonly "own-redzone": "自陣RZ";
-    readonly middle: "中央";
-    readonly redzone: "相手RZ";
+    readonly "own-redzone": "Own red zone";
+    readonly middle: "Midfield";
+    readonly redzone: "Red zone";
 };
 
 /**
- * フィールドのどの範囲を映すか。
- * - `middle`: センター付近
- * - `redzone`: 相手のゴール側
- * - `own-redzone`: 自陣のゴール側
+ * Which part of the field is shown.
+ * - `middle`: around midfield
+ * - `redzone`: the opponent's goal side
+ * - `own-redzone`: the own goal side
  */
 export declare const FIELD_ZONE_VALUES: readonly ["own-redzone", "middle", "redzone"];
 
 /**
- * フィールド上の位置（ヤード）。縦は LOS（`field.losYard`）からの距離で持つので、
- * ゾーンを切り替えて LOS が動いても、図は形を保ったまま一緒に動く。
- * - lateralYard: 0 = 左サイドライン … FIELD_WIDTH_YARDS = 右サイドライン
- * - downfieldYard: 0 = LOS。正が攻撃方向（画面の上）、負がバックフィールド
+ * Position on the field (in yards). The vertical value is the distance from the LOS
+ * (`field.losYard`), so when switching zones moves the LOS, the diagram keeps its shape and
+ * moves along with it.
+ * - lateralYard: 0 = left sideline ... FIELD_WIDTH_YARDS = right sideline
+ * - downfieldYard: 0 = LOS. Positive is the offense direction (screen top), negative the backfield
  *
- * どちらも GRID_STEP_YARDS の倍数で、モデルの中に格子の外の位置は無い。
+ * Both are multiples of GRID_STEP_YARDS; the model holds no position off the grid.
  */
 export declare interface FieldPosition {
     readonly lateralYard: number;
@@ -45,29 +47,33 @@ export declare interface FieldPosition {
 export declare interface FieldState {
     readonly zone: FieldZone;
     /**
-     * LOS の絶対ヤード。今はゾーンから決まり、読み込んだデータの値は使わない。
-     * 保存するデータから選手の絶対位置を復元できるよう、値としては持たせる。
+     * Absolute yard of the LOS. For now it is derived from the zone, and the loaded value is not
+     * used. It is kept as a value so the absolute player positions can be recovered from saved data.
      */
     readonly losYard: number;
 }
 
 export declare type FieldZone = (typeof FIELD_ZONE_VALUES)[number];
 
-/** 読み込むと、players を今の図に足す。プリセットのほかに、利用者が作った隊形も渡せる。 */
+/**
+ * Loading adds players to the current diagram. Besides the presets, a formation built by the
+ * consumer can be passed as well.
+ */
 export declare interface Formation {
     readonly id: string;
     readonly name: string;
-    /** 読み込んだときの選手の配置には影響しない。 */
+    /** Does not affect where the players are placed when loaded. */
     readonly side: TeamSide;
-    /** 1 人以上。 */
+    /** At least one player. */
     readonly players: readonly FormationPlayer[];
 }
 
 export declare const FORMATION_PRESETS: readonly Formation[];
 
 /**
- * 隊形の 1 人。`id` は持たず、読み込むたびに振る。同じ隊形を 2 回読んでも、
- * 図にいる選手とも Undo で戻る選手とも id がぶつからない。
+ * One player of a formation. It has no `id`; one is assigned on every load. Even when the same
+ * formation is loaded twice, ids collide neither with players in the diagram nor with players
+ * that Undo brings back.
  */
 export declare type FormationPlayer = Omit<Player, "id">;
 
@@ -76,8 +82,9 @@ export declare function getFormationPreset(id: string): Formation | undefined;
 export declare function getPlayPreset(id: string): PlayPreset | undefined;
 
 /**
- * 位置を置ける格子の刻み（ヤード）。横はサイドライン、縦は LOS を原点にする。
- * 図の中の位置はすべてこの格子点にあるので、要素同士を揃える操作が無くても縦横が揃う。
+ * Step of the grid (in yards) that positions can be placed on. The origin is the sideline
+ * laterally and the LOS vertically. Every position in the diagram sits on a grid point, so
+ * elements line up vertically and horizontally without an explicit align operation.
  */
 export declare const GRID_STEP_YARDS = 0.5;
 
@@ -87,44 +94,45 @@ export declare interface IDisposable {
 
 export declare interface ImageExportOptions {
     /**
-     * PNG の幅（px）。高さはゾーンの窓の縦横比から決める。
-     * 未指定、有限でない値、1 未満は 1600 にし、4096 を超える幅は 4096 に切り詰める。
+     * The PNG width (px). The height is derived from the aspect ratio of the zone's window.
+     * Unspecified, non-finite, or below 1 becomes 1600; a width above 4096 is clamped to 4096.
      */
     width?: number | undefined;
 }
 
 /**
- * 1 本の線。起点は座標ではなく選手の id で持つので、選手を動かすと線の起点も付いてくる。
- * `color` と `thickness` を省くと、テーマの色と種別ごとの既定の太さで描く。
+ * A single line. The start is held as a player id rather than coordinates, so moving the player
+ * carries the line's start along. Omitting `color` and `thickness` draws with the theme color
+ * and the default width of the kind.
  */
 export declare interface Line {
     readonly id: string;
     readonly kind: LineKind;
-    /** 起点となる選手の id。実在しない参照は復元時に除外される。 */
+    /** Id of the player at the start. A reference to a missing player is dropped on restore. */
     readonly startPlayerId: string;
-    /** 起点と終点の間の中継点（0 個可）。 */
+    /** Intermediate points between the start and the end (may be empty). */
     readonly waypoints: readonly FieldPosition[];
-    /** 終点（ヤード空間）。 */
+    /** End point (in yard space). */
     readonly end: FieldPosition;
     readonly interpolation: LineInterpolation;
-    /** CSS の色の文字列。 */
+    /** A CSS color string. */
     readonly color?: string;
-    /** 種別ごとの既定の太さに対する倍率。省くと DEFAULT_LINE_THICKNESS。 */
+    /** Multiplier on the default width of the kind. DEFAULT_LINE_THICKNESS when omitted. */
     readonly thickness?: number;
 }
 
 /**
- * 線の補間方法。どの種別の線にも効く。
- * - `straight`: 制御点を直線で結ぶ
- * - `bezier`: 制御点をすべて通る滑らかな曲線で結ぶ
+ * Interpolation of a line. Applies to every kind of line.
+ * - `straight`: joins the control points with straight segments
+ * - `bezier`: joins the control points with a smooth curve that passes through all of them
  */
 declare const LINE_INTERPOLATION_VALUES: readonly ["straight", "bezier"];
 
 /**
- * 線の種別。色ではなく終点の記法と線種で見分ける。
- * - `route`: レシーバーやランナーの走路。終点に矢印を描く
- * - `block`: ブロックの割り当て。route と同じ太さで、終点に T 字のバーを描く
- * - `motion`: スナップ前の選手の移動。破線で、終点に矢印を描く
+ * Kind of a line. Kinds are told apart by the end marker and the stroke style, not by color.
+ * - `route`: the path of a receiver or runner. Drawn with an arrow at the end
+ * - `block`: a blocking assignment. Same width as route, with a T bar at the end
+ * - `motion`: a player's movement before the snap. Dashed, with an arrow at the end
  */
 declare const LINE_KIND_VALUES: readonly ["route", "block", "motion"];
 
@@ -133,33 +141,34 @@ export declare type LineInterpolation = (typeof LINE_INTERPOLATION_VALUES)[numbe
 export declare type LineKind = (typeof LINE_KIND_VALUES)[number];
 
 /**
- * どの版で保存したデータでも、今の版の PlayData にする。壊れたデータを渡しても投げない。
- * 返り値は新しいオブジェクトで、入力と参照を共有しない。
- * 選手、線、waypoint は MAX_PLAYERS、MAX_LINES、MAX_WAYPOINTS_PER_LINE の個数までしか読まない。
+ * Turns data saved by any version into a PlayData of the current version. Does not throw on
+ * broken data. The return value is a new object that shares no references with the input.
+ * Players, lines, and waypoints are read only up to MAX_PLAYERS, MAX_LINES, and
+ * MAX_WAYPOINTS_PER_LINE.
  */
 export declare function migratePlayData(raw: unknown): PlayData;
 
 export declare const PLAY_PRESETS: readonly PlayPreset[];
 
-/** プレーの種類。色は持たず、一覧でどう見せるかは使う側が決める。 */
+/** The kind of play. It carries no color; how it appears in a list is up to the consumer. */
 export declare type PlayCategory = "run-zone" | "run-gap" | "pass-quick" | "pass-dropback" | "pass-deep" | "pa" | "rpo" | "coverage" | "pressure";
 
 /**
- * プレー図のデータ。保存したものを `restorePlayData` に渡すと、古い版や版の無いもの、
- * 新しい版のものも今の版に寄せて読む。
+ * Data of a play diagram. Passing saved data to `restorePlayData` loads it coerced to the
+ * current version, whether it is an older version, has no version, or is a newer version.
  */
 export declare interface PlayData {
     readonly version: typeof CURRENT_PLAY_DATA_VERSION;
     readonly field: FieldState;
-    /** 後の要素ほど上に重ねて描く。 */
+    /** Later elements are drawn on top. */
     readonly players: readonly Player[];
-    /** 後の要素ほど上に重ねて描く。 */
+    /** Later elements are drawn on top. */
     readonly lines: readonly Line[];
 }
 
 /**
- * 型付きで組み立てて読み込む図。LOS の位置は読み込むときにゾーンから決め直すので、
- * `field.losYard` は省略できる。
+ * A diagram built with types and loaded. The LOS position is derived again from the zone on
+ * load, so `field.losYard` can be omitted.
  */
 export declare interface PlayDataInput extends Omit<PlayData, "field"> {
     readonly field: Omit<FieldState, "losYard"> & {
@@ -168,8 +177,8 @@ export declare interface PlayDataInput extends Omit<PlayData, "field"> {
 }
 
 /**
- * 1 人の選手。`color` は CSS の色の文字列で、省くとテーマの色で描く。
- * `fill` を省くと DEFAULT_PLAYER_FILL で描く。
+ * A single player. `color` is a CSS color string; when omitted, the theme color is used.
+ * When `fill` is omitted, DEFAULT_PLAYER_FILL is used.
  */
 export declare interface Player {
     readonly id: string;
@@ -181,14 +190,15 @@ export declare interface Player {
 }
 
 /**
- * 選手マーカーの塗り。枠線だけ（`outline`）か、色で塗りつぶす（`solid`）か。
- * 形状とは独立に持ち、攻守や役割の見分けに使う。パネルはこの順にスウォッチを並べる。
+ * Fill of a player marker: outline only (`outline`) or filled with the color (`solid`).
+ * Held independently of the shape, it tells offense and defense or roles apart. The panel lists
+ * its swatches in this order.
  */
 declare const PLAYER_FILL_VALUES: readonly ["outline", "solid"];
 
 /**
- * 選手マーカーの形状。種類が多いと図が散らかるので、丸と四角の 2 種だけにする。
- * どちらも外接円を当たり判定にできるので、hit-test は形状で分けない。
+ * Shape of a player marker. Many shapes would clutter the diagram, so only circle and square.
+ * Both can use the circumscribed circle as the hit area, so the hit test does not branch on shape.
  */
 declare const PLAYER_SHAPE_VALUES: readonly ["circle", "square"];
 
@@ -197,19 +207,19 @@ export declare type PlayerFill = (typeof PLAYER_FILL_VALUES)[number];
 export declare type PlayerShape = (typeof PLAYER_SHAPE_VALUES)[number];
 
 /**
- * container の中にプレー図を描き、edit モードでは編集 UI も置く。
- * dispose すると、置いた要素をすべて取り除く。
- * dispose したあとの変更は例外を投げずに何もせず、開発時だけ console.warn で知らせる。
- * getPlayData と fieldZone は、dispose した時点の図を返す。
+ * Draws the play diagram inside container and, in edit mode, also places the editing UI.
+ * dispose removes every element it placed.
+ * Changes after dispose do nothing instead of throwing; in development, console.warn reports it.
+ * getPlayData and fieldZone return the diagram as it was at dispose.
  */
 export declare class Playmaker implements IDisposable {
     /**
-     * 編集コマンドと Undo / Redo の確定ごとに 1 回、最新の図の深いコピーを渡す。
-     * `version` は常に現行なので、受け取った値をそのまま永続化できる。
-     * 構築時、`setPlayData` と `restorePlayData` での読み込み、PNG の書き出しでは発火しない
-     * （読み込みは編集ではないため）。
-     * コピーはリスナごとに作るので、受け手が書き換えても、この図とほかのリスナには波及しない。
-     * 返り値を dispose すると購読をやめる。
+     * Fires once per committed edit command or Undo / Redo, with a deep copy of the latest diagram.
+     * `version` is always the current one, so the received value can be persisted as is.
+     * Does not fire at construction, on loads through `setPlayData` and `restorePlayData`, or on PNG
+     * export (a load is not an edit).
+     * The copy is made per listener, so mutating it affects neither this diagram nor other listeners.
+     * Disposing the return value ends the subscription.
      */
     readonly onDidChange: Event_2<PlayData>;
     private readonly store;
@@ -217,98 +227,120 @@ export declare class Playmaker implements IDisposable {
     private readonly surface;
     private readonly session;
     private currentMode;
+    private readonly messages;
     private panel;
     private ui;
     constructor(container: HTMLElement, options?: PlaymakerOptions);
     get mode(): PlaymakerMode;
     /**
-     * モードを切り替える。図と Undo の履歴は残し、編集 UI とポインタ、キーの入力だけを付け外しする。
-     * view にすると、ドラッグや作図の途中の操作は取り消し、選択の強調も描かない。
+     * Switches the mode. The diagram and Undo history stay; only the editing UI and the pointer and
+     * key input are attached or detached. View cancels a drag or drawing in progress and draws no
+     * selection highlight.
      */
     setMode(mode: PlaymakerMode): void;
     get fieldZone(): FieldZone;
     /**
-     * LOS をそのゾーンの既定の位置へ移し、選手と線も一緒に動かす。
-     * 編集なので Undo と onDidChange の対象になる。view モードでも呼べる。
+     * Moves the LOS to the default position of that zone, and moves the players and lines with it.
+     * This is an edit, so Undo and onDidChange cover it. Callable in view mode as well.
      */
     setFieldZone(zone: FieldZone): void;
     /**
-     * 隊形の選手を今の図に追記し、置いたら true を返す。攻守の隊形を順に重ねられる。
-     * 選手の位置は LOS からの相対（`lateralYard` と `downfieldYard`）で書く。
-     * 外から渡した隊形は正規化してから読むので、位置の読めない選手は捨てる。
-     * 置ける選手が 1 人もいないときと、置くと選手が 64 人を超えるときは、1 人も置かずに false を返す。
-     * 編集なので Undo と onDidChange の対象になる。view モードでも呼べる。
+     * Appends the formation's players to the current diagram and returns true once placed. Offense
+     * and defense formations can be layered in turn. Player positions are relative to the LOS
+     * (`lateralYard` and `downfieldYard`). A formation passed from outside is normalized before it is
+     * read, so players whose position cannot be read are dropped. When no player can be placed, or
+     * placing them would exceed 64 players, places none and returns false.
+     * This is an edit, so Undo and onDidChange cover it. Callable in view mode as well.
      */
     loadFormation(formation: Formation): boolean;
     /**
-     * 型付きで組み立てた図を読み込み、今の図と置き換える。`getPlayData` の戻り値や、
-     * プリセットの `data` もそのまま渡せる。
-     * 型に合っていても、重複した id と件数の上限を超えた分は `restorePlayData` と同じく正規化する。
-     * 読み込みは編集ではないので、Undo の履歴は消え、onDidChange は発火しない。
+     * Loads a diagram built with the types and replaces the current one. The return value of
+     * `getPlayData` and a preset's `data` can be passed as is.
+     * Even when the input matches the types, duplicate ids and entries past the count limits are
+     * normalized as in `restorePlayData`.
+     * A load is not an edit, so the Undo history is cleared and onDidChange does not fire.
      */
     setPlayData(data: PlayDataInput): void;
     /**
-     * 永続化しておいた値を、形を確かめずに受け取って読み込み、今の図と置き換える。
-     * 旧版、版の無いもの、未来版、壊れたデータも、例外を投げずに今のスキーマへ寄せ、読めない要素だけを捨てる。
-     * 選手 64 人、線 128 本、線 1 本あたり waypoint 32 個を超える分は、先頭から上限までを残して捨てる。
-     * 読み込みは編集ではないので、Undo の履歴は消え、onDidChange は発火しない。
+     * Accepts a persisted value unchecked, loads it, and replaces the current diagram.
+     * Old versions, unversioned values, future versions, and broken data are coerced to the current
+     * schema without throwing; only the elements that cannot be read are dropped.
+     * Anything past 64 players, 128 lines, or 32 waypoints per line is dropped, keeping the first
+     * entries up to the limit.
+     * A load is not an edit, so the Undo history is cleared and onDidChange does not fire.
      */
     restorePlayData(raw: unknown): void;
     /**
-     * 今の図の深いコピー。`version` は常に現行で、そのまま JSON にして永続化できる。
-     * `restorePlayData` か `initialData` に戻すと、同じ図になる。
-     * 編集でも件数の上限は超えられず、上限に達すると選手の追加、フォーメーションの読み込み、作図は何もしない。
+     * A deep copy of the current diagram. `version` is always the current one, so it can be turned
+     * into JSON and persisted as is. Passing it back through `restorePlayData` or `initialData`
+     * yields the same diagram. Edits cannot exceed the count limits either: at a limit, adding a
+     * player, loading a formation, and drawing a line do nothing.
      */
     getPlayData(): PlayData;
     /**
-     * 呼んだ時点で確定しているプレー図を PNG 画像（Blob）として書き出す。
-     * 選択の強調、waypoint のハンドル、ドラッグや作図の途中の形、ツールバーとパネルは入らない。
-     * view と edit のどちらのモードでも使える。
-     * 同梱フォントを読み込み終えてから描くので、構築の直後に呼んでもヤードの数字と選手のラベルは同梱フォントになる。
-     * フォントを読み込めなかったときは代わりのフォントで描く。
-     * canvas を確保できないとき、PNG に変換できないとき、dispose したあとは、例外を投げずに reject する。
+     * Exports the play diagram as committed at the time of the call as a PNG image (Blob).
+     * The selection highlight, waypoint handles, the shape of a drag or drawing in progress, and the
+     * toolbar and panel are not included. Usable in both view and edit mode.
+     * Draws after the bundled font has finished loading, so even a call right after construction
+     * renders the yard numbers and player labels in the bundled font. If the font fails to load,
+     * draws with a fallback font. Rejects without throwing when a canvas cannot be obtained, the
+     * PNG conversion fails, or the Playmaker is disposed.
      */
     exportToPng(options?: ImageExportOptions): Promise<Blob>;
     /**
-     * 図とパネルの色を、テーマの CSS 変数から読み直す。CSS 変数を変えてもブラウザは知らせてこないので、
-     * ホストが祖先の要素で変数を変えたあとに呼ぶ。
+     * Re-reads the colors of the diagram and the panel from the theme CSS variables. The browser does
+     * not report CSS variable changes, so the host calls this after changing them on an ancestor.
      */
     refresh(): void;
     dispose(): void;
-    /** dispose したあとの呼び出しは何もしないので、開発時だけそのことを知らせる。 */
+    /** Calls after dispose do nothing, so report that in development only. */
     private warnIgnoredAfterDispose;
     private replaceUi;
     private createUi;
     private draw;
-    /** view モードでは undefined を返し、格子や選択の強調のような編集中だけの層を描かせない。 */
+    /** Undefined in view mode, so edit-only layers (the grid, selection highlight) are not drawn. */
     private surfaceOverlay;
 }
 
+/** Languages the built-in UI ships. The host picks one at construction. */
+export declare const PLAYMAKER_LOCALE_VALUES: readonly ["en", "ja"];
+
+export declare type PlaymakerLocale = (typeof PLAYMAKER_LOCALE_VALUES)[number];
+
 export declare type PlaymakerMode = "view" | "edit";
 
 export declare interface PlaymakerOptions {
     /**
-     * 最初のモード。既定は "edit"。"view" は編集 UI を置かず、ポインタとキーの操作も受けない。
-     * あとから `setMode` で切り替えられる。
+     * The initial mode. The default is "edit". "view" places no editing UI and accepts no pointer
+     * or keyboard input. `setMode` switches the mode later.
      */
     mode?: PlaymakerMode | undefined;
-    /** 最初に表示する図。`restorePlayData` と同じく、形を確かめずに受け取って今のスキーマへ寄せる。 */
+    /**
+     * The first diagram to show. Like `restorePlayData`, it is accepted without checking its shape
+     * and coerced to the current schema.
+     */
     initialData?: unknown;
-    /** 構築時に `onDidChange` へ登録するリスナ。解除するには Playmaker を dispose する。 */
+    /** A listener added to `onDidChange` at construction. Dispose the Playmaker to remove it. */
     onChange?: ((data: PlayData) => void) | undefined;
+    /**
+     * Language of the built-in UI (the toolbar and the property panel). The default is "en".
+     * Fixed at construction; to switch, construct again with the same data.
+     * Error messages are English regardless of the locale, because they are for developers.
+     */
+    locale?: PlaymakerLocale | undefined;
 }
 
-/** 線まで描き込んだプレー図に、一覧に出すための情報を添えたもの。 */
+/** A play diagram drawn down to the lines, with the information needed to show it in a list. */
 export declare interface PlayPreset {
     readonly id: string;
     readonly name: string;
     readonly side: TeamSide;
     readonly category: PlayCategory;
-    /** パーソネルか隊形の短い注記（例: "11 pers"、"Nickel"）。 */
+    /** A short note on the personnel or formation (for example "11 pers" or "Nickel"). */
     readonly personnel: string;
-    /** コンセプトの 1 行の説明。 */
+    /** A one-line description of the concept. */
     readonly summary: string;
-    /** そのまま setPlayData に渡せる。 */
+    /** Can be passed to setPlayData as is. */
     readonly data: PlayData;
 }