@hypit/hypit 0.1.5 → 0.1.7

package/packages/studio/LOCALIZATION.md

@@ -0,0 +1,98 @@
+# Localizing Studio
+
+Studio owns its interface messages; a language pack supplies their wording. The
+English catalog in [locales/en.json](locales/en.json) is the complete list of
+message IDs. [Simplified Chinese](locales/zh-CN.json) uses exactly the same format
+as any additional language. A pack is JSON data, not executable code.
+
+## Add a language
+
+Copy `locales/en.json`, change `locale` (a BCP 47 tag such as `ja` or `pt-BR`),
+`name` (the language's native name), and translate the message values. Keep the
+message IDs. `direction` is `ltr` or `rtl` and controls translated text; it does
+not reverse the physical video timeline or canvas coordinates.
+
+A small, valid starting point is:
+
+```json
+{
+  "locale": "ja",
+  "name": "日本語",
+  "direction": "ltr",
+  "messages": {
+    "app.studio": "スタジオ",
+    "app.comments": "コメント",
+    "app.language": "言語"
+  }
+}
+```
+
+Missing messages use English, so a partial translation is useful immediately.
+Text is displayed as text, never interpreted as HTML. Preserve named variables
+such as `{name}` and `{count}`; their order may change to suit the language.
+Messages with `{count}` can be strings or plural forms:
+
+```json
+{ "one": "{count} item", "other": "{count} items" }
+```
+
+Use the language's `Intl.PluralRules` categories (`zero`, `one`, `two`, `few`,
+`many`, `other`); `other` is required. Numbers and interface dates use the chosen
+locale. Choose natural full sentences instead of assembling translated fragments.
+
+Check and load your file:
+
+```sh
+hypit studio --check-locale ./ja.json
+hypit studio --run ./render.svrun --locale-pack ./ja.json
+```
+
+The check lists missing translations and unknown IDs and reports malformed
+messages or renamed variables. It does not open a Run or require a Runtime.
+Relative file paths start at the command's working directory; prefix them with
+`./` or `../`. Repeat `--locale-pack` to load multiple languages. Packs are read
+at server startup; restart Studio after editing a pack. An explicitly loaded
+pack with an existing locale replaces that locale's pack, with English fallback
+for any omitted messages.
+
+## Share a language pack
+
+A local file is sufficient. For reuse, publish it through an ordinary package
+under your own scope; there is no Hypit language registry or separate approval
+step. Export the JSON file in the package's `package.json`, for example:
+
+```json
+{
+  "name": "@your-scope/studio-ja",
+  "version": "1.0.0",
+  "files": ["ja.json"],
+  "exports": { "./locale.json": "./ja.json" }
+}
+```
+
+Install it using the project's package manager, then load it explicitly:
+
+```sh
+hypit studio --run ./render.svrun --locale-pack @your-scope/studio-ja/locale.json
+```
+
+Package exports resolve from the project, or `--package-root` when specified.
+Studio reads the resolved JSON without importing package code. It neither scans
+for language packs nor installs missing packages.
+
+## Interface behavior and ownership
+
+The globe menu to the left of **Studio / Comments** lists loaded languages by
+their native names. The first visit follows the browser's language preferences;
+subsequent visits retain the choice saved in that browser. Switching updates
+marked labels in place, preserving the playhead, selection and comment draft.
+
+Only Studio-owned interface text belongs in this catalog. Component names,
+Companion-supplied labels, Source code, user comments and raw service diagnostics
+retain their original text. Language packs do not change the Companion ABI,
+Core, compilation, or rendering. A component remains the owner of its labels.
+
+When adding Studio UI, give each message a stable ID in the English catalog and
+use the helpers in `src/ui/i18n.ts` for text and attributes. Do not use English
+wording as IDs, inspect DOM text to guess what needs translation, or put language
+branches into components. Keep interpolation values separate from message text.

package/packages/studio/README.md

@@ -258,3 +258,16 @@ audibility regions and target-relative fades. Web Audio gain nodes schedule the
 on the same clock, including silence and amplification above unity. Visual video elements stay muted;
 the Film's selected AudioTracks own composition sound. Seeking is silent. This path is independent of
 which component emitted a clip.
+
+### Interface language
+
+The globe menu to the left of **Studio / Comments** selects a language. English
+and Simplified Chinese are included; additional JSON language packs can be loaded
+with `--locale-pack`, from local files or installed package exports. The first
+visit follows browser preferences, and later visits remember the user's choice.
+Switching preserves the playhead, selection and comment draft.
+
+[Localizing Studio](LOCALIZATION.md) explains the message catalog, plural forms,
+translation checks and language-pack distribution. Only Studio-owned interface
+text is translated; Companion labels, project content and raw diagnostics retain
+their original text. The Companion ABI is unchanged.

package/packages/studio/locales/en.json

@@ -0,0 +1,197 @@
+{
+  "locale": "en",
+  "name": "English",
+  "direction": "ltr",
+  "messages": {
+    "app.comments": "Comments",
+    "app.language": "Language",
+    "app.studio": "Studio",
+    "app.studio-view": "Studio view",
+    "comments.all": "All",
+    "comments.caught-up": "All caught up",
+    "comments.delete-comment": "Delete comment",
+    "comments.done": "Done",
+    "comments.draw-soon": "Draw — coming later",
+    "comments.edit-comment": "Edit comment",
+    "comments.edit-comment-text": "Edit comment text",
+    "comments.emoji-soon": "Emoji — coming later",
+    "comments.empty": "A note starts here",
+    "comments.empty-hint": "Pause on a frame and describe what you would like to change.",
+    "comments.filter-comments": "Filter comments",
+    "comments.filter-hint": "Switch filters to see the other comments.",
+    "comments.go-to-this-frame": "Go to this frame",
+    "comments.loading-comments": "Loading comments…",
+    "comments.mark-complete": "Mark complete",
+    "comments.no-completed-comments": "No completed comments",
+    "comments.open": "Open",
+    "comments.placeholder": "What would you like to change?",
+    "comments.read-failed": "Could not read comments.",
+    "comments.refresh-comments": "Refresh comments",
+    "comments.reopen-comment": "Reopen comment",
+    "comments.save-failed": "Could not save comment.",
+    "comments.send-comment": "Send comment",
+    "comments.send-shortcut": "Send comment (Enter)",
+    "comments.use-current-frame": "Use current frame",
+    "comments.write-a-comment": "Write a comment",
+    "common.cancel": "Cancel",
+    "common.cancelled": "Cancelled",
+    "common.compile-failed": "Compile failed",
+    "common.completed": "Completed",
+    "common.copied": "Copied",
+    "common.failed": "Failed",
+    "common.invalid-value": "Invalid value",
+    "common.needs-attention": "Needs attention",
+    "common.queued": "Queued",
+    "common.refresh": "Refresh",
+    "common.running": "Running",
+    "common.save": "Save",
+    "common.save-failed": "Save failed",
+    "common.saved": "Saved",
+    "common.saving": "Saving",
+    "common.waiting": "Waiting",
+    "inspector.add-color": "Add color",
+    "inspector.add-item": "Add item",
+    "inspector.anchor.program-end": "Timeline end{detail}",
+    "inspector.anchor.program-start": "Timeline start{detail}",
+    "inspector.anchor.segment-end": "Segment end{detail}",
+    "inspector.anchor.segment-start": "Segment start{detail}",
+    "inspector.anchor.token-end": "Word end{detail}",
+    "inspector.anchor.token-start": "Word start{detail}",
+    "inspector.aspect-ratio": "Aspect ratio",
+    "inspector.author": "Author",
+    "inspector.build": "Build",
+    "inspector.candidates": "Candidates",
+    "inspector.canvas": "Canvas",
+    "inspector.duration": "Duration",
+    "inspector.empty": "No details for this selection",
+    "inspector.end": "End",
+    "inspector.end-anchor": "End semantic anchor",
+    "inspector.frame-rate": "Frame rate",
+    "inspector.frames": "Frames",
+    "inspector.how": "How",
+    "inspector.invalid-fields": "Complete the required fields with valid values to save.",
+    "inspector.item-count": {
+      "one": "{count} item",
+      "other": "{count} items"
+    },
+    "inspector.moment": "Moment",
+    "inspector.moment-anchor": "Moment semantic anchor",
+    "inspector.move-down": "Move down",
+    "inspector.move-up": "Move up",
+    "inspector.project": "Project",
+    "inspector.properties": "Properties",
+    "inspector.remove-item": "Remove item",
+    "inspector.resolution": "Resolution",
+    "inspector.run": "Run",
+    "inspector.semantic-anchors": "Semantic anchors",
+    "inspector.sources": "Sources",
+    "inspector.start": "Start",
+    "inspector.start-anchor": "Start semantic anchor",
+    "inspector.structured-value": "Structured value",
+    "inspector.targets": "Targets",
+    "inspector.timeline": "Timeline",
+    "inspector.timing": "Timing",
+    "inspector.tracks": "Tracks",
+    "inspector.use-color": "Use {color}",
+    "inspector.when": "When",
+    "inspector.where": "Where",
+    "library.all-media": "All media",
+    "library.all-tasks": "All tasks",
+    "library.artifacts": "Artifacts",
+    "library.audio": "Audio",
+    "library.clear-task-filter": "Clear task filter",
+    "library.data": "Data",
+    "library.display-name": "Display name",
+    "library.enter-name": "Enter a name.",
+    "library.finished": "Finished",
+    "library.image": "Image",
+    "library.images": "Images",
+    "library.in-progress": "In progress",
+    "library.loading-media": "Loading media…",
+    "library.loading-more": "Loading more…",
+    "library.loading-tasks": "Loading tasks…",
+    "library.media-categories": "Media categories",
+    "library.media-category": "Media category",
+    "library.media-hint": "Images, videos and audio published as file Outputs appear here, including those from ongoing Builds.",
+    "library.name-failed": "Could not save the name",
+    "library.name-pending": "{name}\nNaming is available when this Build finishes",
+    "library.no-files-in-this-category": "No files in this category",
+    "library.no-media": "No media",
+    "library.no-tasks-here": "No tasks here",
+    "library.no-tasks-in-progress": "No tasks in progress",
+    "library.preview-name": "Preview {name}",
+    "library.preview-unavailable": "Preview unavailable",
+    "library.referenced-source-files": "Referenced source files",
+    "library.refresh-failed": "Refresh failed: {detail}",
+    "library.refresh-failed-retained": "Refresh failed: {detail} · Previous view retained",
+    "library.refresh-interrupted": "Refresh interrupted",
+    "library.refresh-media": "Refresh media",
+    "library.refresh-tasks": "Refresh tasks",
+    "library.refreshing": "Refreshing…",
+    "library.rename-hint": "{name}\nDouble-click or press F2 to rename",
+    "library.return-to-task": "Return to task",
+    "library.source": "Source",
+    "library.studio-library": "Studio library",
+    "library.task-categories": "Task categories",
+    "library.task-return": "{name} · Return to task",
+    "library.tasks": "Tasks",
+    "library.unavailable": "Library unavailable",
+    "library.updated": "Updated {time}",
+    "library.video": "Video",
+    "library.video-loading-preview": "Video · Loading preview",
+    "library.videos": "Videos",
+    "library.view-media": "View media",
+    "library.view-task-media": "View task media",
+    "player.audio-waveform": "Audio waveform",
+    "player.back-5-seconds": "Back 5 seconds",
+    "player.back-to-composition": "Back to composition",
+    "player.composition-time": "Composition time",
+    "player.elements-at-this-point": "Elements at this point",
+    "player.forward-5-seconds": "Forward 5 seconds",
+    "player.frame-loading": "Loading frame…",
+    "player.frame-unavailable": "Frame unavailable",
+    "player.hovered-frame": "Hovered frame",
+    "player.media-failed": "This media could not be opened in the browser.",
+    "player.media-time": "Media time",
+    "player.mute": "Mute",
+    "player.next-frame": "Next frame",
+    "player.pause": "Pause",
+    "player.play": "Play",
+    "player.preview": "Preview",
+    "player.previous-frame": "Previous frame",
+    "player.unmute": "Unmute",
+    "source.changed-outside-studio": "Changed outside Studio",
+    "source.edit-source": "Edit source",
+    "source.keep-lines-unwrapped": "Keep lines unwrapped",
+    "source.read-source": "Read source",
+    "source.save-failed-status": "Save failed ({status})",
+    "source.saving-before-switch": "Saving before switch",
+    "source.svml-source": "SVML source",
+    "source.unsaved": "Unsaved",
+    "source.wrap-lines": "Wrap lines",
+    "tasks.copy-error": "Copy error",
+    "tasks.copy-manually": "Select the text to copy",
+    "tasks.no-runtime": "No Runtime is selected. Saved tasks are available under Finished.",
+    "tasks.progress": "{completed}/{total} steps complete",
+    "tasks.refresh-hint": "Refresh to read the latest task status.",
+    "tasks.saved-only": "Saved project Results · no Runtime selected",
+    "timeline.fit-timeline": "Fit timeline",
+    "timeline.moment-name": "Moment {name}",
+    "timeline.overlapping-timeline-objects": "Overlapping timeline objects",
+    "timeline.resize-timeline-track-labels": "Resize timeline track labels",
+    "timeline.resize-track-labels": "Resize track labels",
+    "timeline.segment-name": "Segment {name}",
+    "timeline.segments": "Segments",
+    "timeline.select": "Select",
+    "timeline.selection-name": "Selection {name}",
+    "timeline.selections-and-moments": "Selections and Moments",
+    "timeline.words": "Words",
+    "timeline.zoom-in": "Zoom in",
+    "timeline.zoom-out": "Zoom out",
+    "inspector.color-picker": "{label} picker",
+    "timeline.segment-count": {
+      "one": "{count} segment",
+      "other": "{count} segments"
+    }
+  }
+}

package/packages/studio/locales/zh-CN.json

@@ -0,0 +1,191 @@
+{
+  "locale": "zh-CN",
+  "name": "简体中文",
+  "direction": "ltr",
+  "messages": {
+    "app.comments": "评论",
+    "app.language": "语言",
+    "app.studio": "工作台",
+    "app.studio-view": "工作区视图",
+    "comments.all": "全部",
+    "comments.caught-up": "评论都已处理",
+    "comments.delete-comment": "删除评论",
+    "comments.done": "已完成",
+    "comments.draw-soon": "批注 · 即将支持",
+    "comments.edit-comment": "编辑评论",
+    "comments.edit-comment-text": "编辑评论内容",
+    "comments.emoji-soon": "表情 · 即将支持",
+    "comments.empty": "留下第一条评论",
+    "comments.empty-hint": "暂停在想调整的画面，说说你的想法。",
+    "comments.filter-comments": "筛选评论",
+    "comments.filter-hint": "切换筛选，查看其他评论。",
+    "comments.go-to-this-frame": "跳转到这一帧",
+    "comments.loading-comments": "加载评论中…",
+    "comments.mark-complete": "标为已完成",
+    "comments.no-completed-comments": "暂无已完成评论",
+    "comments.open": "待处理",
+    "comments.placeholder": "想调整哪里？",
+    "comments.read-failed": "无法读取评论。",
+    "comments.refresh-comments": "刷新评论",
+    "comments.reopen-comment": "标为待处理",
+    "comments.save-failed": "无法保存评论。",
+    "comments.send-comment": "发送评论",
+    "comments.send-shortcut": "发送评论（Enter）",
+    "comments.use-current-frame": "使用当前帧",
+    "comments.write-a-comment": "写评论",
+    "common.cancel": "取消",
+    "common.cancelled": "已取消",
+    "common.compile-failed": "编译失败",
+    "common.completed": "已完成",
+    "common.copied": "已复制",
+    "common.failed": "失败",
+    "common.invalid-value": "无效的值",
+    "common.needs-attention": "需要处理",
+    "common.queued": "排队中",
+    "common.refresh": "刷新",
+    "common.running": "运行中",
+    "common.save": "保存",
+    "common.save-failed": "保存失败",
+    "common.saved": "已保存",
+    "common.saving": "保存中",
+    "common.waiting": "等待中",
+    "inspector.add-color": "添加颜色",
+    "inspector.add-item": "添加条目",
+    "inspector.anchor.program-end": "时间线终点{detail}",
+    "inspector.anchor.program-start": "时间线起点{detail}",
+    "inspector.anchor.segment-end": "段尾{detail}",
+    "inspector.anchor.segment-start": "段头{detail}",
+    "inspector.anchor.token-end": "词尾{detail}",
+    "inspector.anchor.token-start": "词头{detail}",
+    "inspector.aspect-ratio": "画幅比例",
+    "inspector.author": "源文件",
+    "inspector.build": "构建",
+    "inspector.candidates": "候选实现",
+    "inspector.canvas": "画布",
+    "inspector.duration": "时长",
+    "inspector.empty": "当前选中项没有详细信息",
+    "inspector.end": "终点",
+    "inspector.end-anchor": "终点语义锚点",
+    "inspector.frame-rate": "帧率",
+    "inspector.frames": "帧数",
+    "inspector.how": "样式",
+    "inspector.invalid-fields": "请正确填写必填项后保存。",
+    "inspector.item-count": "{count} 项",
+    "inspector.moment": "时刻",
+    "inspector.moment-anchor": "时刻语义锚点",
+    "inspector.move-down": "下移",
+    "inspector.move-up": "上移",
+    "inspector.project": "项目",
+    "inspector.properties": "属性",
+    "inspector.remove-item": "移除条目",
+    "inspector.resolution": "分辨率",
+    "inspector.run": "运行方案",
+    "inspector.semantic-anchors": "语义锚点",
+    "inspector.sources": "引用文件",
+    "inspector.start": "起点",
+    "inspector.start-anchor": "起点语义锚点",
+    "inspector.structured-value": "结构化值",
+    "inspector.targets": "目标产物",
+    "inspector.timeline": "时间线",
+    "inspector.timing": "时间",
+    "inspector.tracks": "轨道",
+    "inspector.use-color": "使用 {color}",
+    "inspector.when": "时间",
+    "inspector.where": "位置",
+    "library.all-media": "全部素材",
+    "library.all-tasks": "全部任务",
+    "library.artifacts": "产物",
+    "library.audio": "音频",
+    "library.clear-task-filter": "清除任务筛选",
+    "library.data": "数据",
+    "library.display-name": "显示名称",
+    "library.enter-name": "请输入名称。",
+    "library.finished": "已结束",
+    "library.image": "图片",
+    "library.images": "图片",
+    "library.in-progress": "进行中",
+    "library.loading-media": "加载素材中…",
+    "library.loading-more": "加载更多…",
+    "library.loading-tasks": "加载任务中…",
+    "library.media-categories": "素材分类",
+    "library.media-category": "素材分类",
+    "library.media-hint": "这里展示已产出的图片、视频和音频，也包括正在构建的任务产物。",
+    "library.name-failed": "无法保存名称",
+    "library.name-pending": "{name}\n构建完成后可以重命名",
+    "library.no-files-in-this-category": "此分类暂无素材",
+    "library.no-media": "暂无素材",
+    "library.no-tasks-here": "暂无任务",
+    "library.no-tasks-in-progress": "没有进行中的任务",
+    "library.preview-name": "预览 {name}",
+    "library.preview-unavailable": "暂时无法预览",
+    "library.referenced-source-files": "引用的源文件",
+    "library.refresh-failed": "刷新失败：{detail}",
+    "library.refresh-failed-retained": "刷新失败：{detail} · 已保留上次视图",
+    "library.refresh-interrupted": "刷新已中断",
+    "library.refresh-media": "刷新素材",
+    "library.refresh-tasks": "刷新任务",
+    "library.refreshing": "刷新中…",
+    "library.rename-hint": "{name}\n双击或按 F2 重命名",
+    "library.return-to-task": "返回任务",
+    "library.source": "源文件",
+    "library.studio-library": "项目资源",
+    "library.task-categories": "任务分类",
+    "library.task-return": "{name} · 返回任务",
+    "library.tasks": "任务",
+    "library.unavailable": "资源暂时不可用",
+    "library.updated": "更新于 {time}",
+    "library.video": "视频",
+    "library.video-loading-preview": "视频 · 加载预览中",
+    "library.videos": "视频",
+    "library.view-media": "查看产物",
+    "library.view-task-media": "查看任务产物",
+    "player.audio-waveform": "音频波形",
+    "player.back-5-seconds": "后退 5 秒",
+    "player.back-to-composition": "返回作品",
+    "player.composition-time": "作品播放进度",
+    "player.elements-at-this-point": "此处的元素",
+    "player.forward-5-seconds": "前进 5 秒",
+    "player.frame-loading": "加载画面中…",
+    "player.frame-unavailable": "画面暂时不可用",
+    "player.hovered-frame": "悬停画面",
+    "player.media-failed": "浏览器无法打开此素材。",
+    "player.media-time": "素材播放进度",
+    "player.mute": "静音",
+    "player.next-frame": "下一帧",
+    "player.pause": "暂停",
+    "player.play": "播放",
+    "player.preview": "预览",
+    "player.previous-frame": "上一帧",
+    "player.unmute": "取消静音",
+    "source.changed-outside-studio": "文件已在外部更改",
+    "source.edit-source": "编辑源文件",
+    "source.keep-lines-unwrapped": "不自动换行",
+    "source.read-source": "查看源文件",
+    "source.save-failed-status": "保存失败（{status}）",
+    "source.saving-before-switch": "切换前保存中",
+    "source.svml-source": "SVML 源文件",
+    "source.unsaved": "未保存",
+    "source.wrap-lines": "自动换行",
+    "tasks.copy-error": "复制错误信息",
+    "tasks.copy-manually": "请选择文字复制",
+    "tasks.no-runtime": "尚未选择运行环境，可在「已结束」中查看保存的任务。",
+    "tasks.progress": "已完成 {completed}/{total} 步",
+    "tasks.refresh-hint": "点击刷新，查看最新任务状态。",
+    "tasks.saved-only": "项目中保存的结果 · 未选择运行环境",
+    "timeline.fit-timeline": "适配时间线",
+    "timeline.moment-name": "时刻 {name}",
+    "timeline.overlapping-timeline-objects": "重叠的时间线对象",
+    "timeline.resize-timeline-track-labels": "调整轨道名称区宽度",
+    "timeline.resize-track-labels": "调整轨道名称区宽度",
+    "timeline.segment-name": "片段 {name}",
+    "timeline.segments": "片段",
+    "timeline.select": "选择",
+    "timeline.selection-name": "区间 {name}",
+    "timeline.selections-and-moments": "区间与时刻",
+    "timeline.words": "词语",
+    "timeline.zoom-in": "放大",
+    "timeline.zoom-out": "缩小",
+    "inspector.color-picker": "{label}取色器",
+    "timeline.segment-count": "{count} 个片段"
+  }
+}

package/packages/studio/src/localization-node.ts

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { isAbsolute, resolve } from "node:path";
+import type { Plugin } from "vite";
+import { builtinLanguages, languageCoverage, readLanguagePack } from "./localization.js";
+import type { LanguagePack } from "./localization.js";
+
+export async function loadLanguagePack(specifier: string, cwd: string, packageRoot: string): Promise<LanguagePack> {
+  const path = isAbsolute(specifier) || specifier.startsWith(".")
+    ? resolve(cwd, specifier)
+    : createRequire(resolve(packageRoot, "package.json")).resolve(specifier);
+  try { return readLanguagePack(JSON.parse(await readFile(path, "utf8"))); }
+  catch (error) { throw new Error(`Language pack ${specifier}: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+export function describeLanguagePack(pack: LanguagePack): string {
+  const { missing, unknown } = languageCoverage(pack);
+  return [`${pack.name} (${pack.locale})`,
+    `Missing translations (${missing.length}; English is used): ${missing.join(", ") || "none"}`,
+    `Unknown message IDs (${unknown.length}): ${unknown.join(", ") || "none"}`,
+  ].join("\n");
+}
+
+export async function studioLanguages(specifiers: readonly string[], cwd: string, packageRoot: string): Promise<readonly LanguagePack[]> {
+  const packs = new Map(builtinLanguages.map(pack => [pack.locale, pack]));
+  for (const specifier of specifiers) {
+    const pack = await loadLanguagePack(specifier, cwd, packageRoot);
+    packs.set(pack.locale, pack);
+  }
+  return [...packs.values()];
+}
+
+export function studioLocalizationPlugin(packs: readonly LanguagePack[]): Plugin {
+  return {
+    name: "hypit-studio-localization",
+    configureServer(server) {
+      server.middlewares.use((request, response, next) => {
+        if (new URL(request.url ?? "/", "http://localhost").pathname !== "/__studio/locales") return next();
+        if (request.method !== "GET") { response.statusCode = 405; response.end(); return; }
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        response.end(JSON.stringify(packs));
+      });
+    },
+  };
+}

package/packages/studio/src/localization.ts

@@ -0,0 +1,85 @@
+import english from "../locales/en.json" with { type: "json" };
+import chinese from "../locales/zh-CN.json" with { type: "json" };
+
+export type Message = keyof typeof english.messages;
+export type MessageValue = string | ({ readonly other: string } & Partial<Record<Intl.LDMLPluralRule, string>>);
+export type LanguagePack = {
+  readonly locale: string;
+  /** Native language name, displayed without translation. */
+  readonly name: string;
+  readonly direction: "ltr" | "rtl";
+  readonly messages: Readonly<Record<string, MessageValue>>;
+};
+export const defaultLanguage: LanguagePack = english as LanguagePack;
+export const builtinLanguages: readonly LanguagePack[] = [defaultLanguage, chinese as LanguagePack];
+export type MessageValues = Readonly<Record<string, string | number>>;
+const plurals = new Set(["zero", "one", "two", "few", "many", "other"]);
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const variants = (message: MessageValue): readonly string[] => typeof message === "string" ? [message] : Object.values(message);
+const variables = (text: string): string[] => [...new Set([...text.matchAll(/\{(\w+)\}/gu)].map(match => match[1]!))].sort();
+
+/** Read data, never executable translation code. Partial translations remain useful. */
+export function readLanguagePack(value: unknown): LanguagePack {
+  if (!record(value) || typeof value.locale !== "string" || typeof value.name !== "string" || !value.name.trim()
+    || (value.direction !== "ltr" && value.direction !== "rtl") || !record(value.messages)) {
+    throw new Error("A Studio language pack needs locale, name, direction (ltr/rtl) and messages.");
+  }
+  const locale = Intl.getCanonicalLocales(value.locale)[0];
+  if (!locale) throw new Error("A Studio language pack needs a BCP 47 locale.");
+  const messages: Record<string, MessageValue> = {};
+  for (const [id, message] of Object.entries(value.messages)) {
+    if (typeof message !== "string" && (!record(message) || typeof message.other !== "string"
+      || Object.entries(message).some(([form, text]) => !plurals.has(form) || typeof text !== "string"))) {
+      throw new Error(`${id}: expected text or plural forms with an 'other' form.`);
+    }
+    const translated = message as MessageValue;
+    const original = Object.hasOwn(defaultLanguage.messages, id) ? defaultLanguage.messages[id] : undefined;
+    if (original !== undefined) {
+      const expected = variables(variants(original)[0]!).join(",");
+      for (const text of variants(translated)) {
+        if (variables(text).join(",") !== expected) throw new Error(`${id}: preserve the named variables {${expected.split(",").join("}, {")}}.`);
+      }
+      if (typeof translated !== "string" && !variables(variants(original)[0]!).includes("count")) {
+        throw new Error(`${id}: plural forms require a count variable.`);
+      }
+    }
+    messages[id] = translated;
+  }
+  return { locale, name: value.name, direction: value.direction, messages };
+}
+
+export function languageCoverage(pack: LanguagePack): { missing: string[]; unknown: string[] } {
+  return {
+    missing: Object.keys(defaultLanguage.messages).filter(id => !Object.hasOwn(pack.messages, id)),
+    unknown: Object.keys(pack.messages).filter(id => !Object.hasOwn(defaultLanguage.messages, id)),
+  };
+}
+
+export function chooseLanguage(packs: readonly LanguagePack[], preferences: readonly string[]): LanguagePack {
+  for (const preference of preferences) {
+    let locale: string;
+    try { locale = Intl.getCanonicalLocales(preference)[0]!; } catch { continue; }
+    const exact = packs.find(pack => pack.locale === locale);
+    if (exact) return exact;
+    // Match regional/script variants without a list of special language cases.
+    const requested = new Intl.Locale(locale).maximize();
+    const related = packs.find(pack => {
+      const candidate = new Intl.Locale(pack.locale).maximize();
+      return candidate.language === requested.language && candidate.script === requested.script;
+    });
+    if (related) return related;
+  }
+  return packs.find(pack => pack.locale === defaultLanguage.locale) ?? defaultLanguage;
+}
+
+export function formatMessage(pack: LanguagePack, id: Message, values: MessageValues = {}): string {
+  const translated = pack.messages[id];
+  const message = translated ?? defaultLanguage.messages[id]!;
+  const locale = translated === undefined ? defaultLanguage.locale : pack.locale;
+  const template = typeof message === "string" ? message
+    : message[new Intl.PluralRules(locale).select(Number(values.count))] ?? message.other;
+  return template.replace(/\{(\w+)\}/gu, (match, key: string) => {
+    const value = values[key];
+    return typeof value === "number" ? new Intl.NumberFormat(pack.locale).format(value) : value ?? match;
+  });
+}