@sudajs/cli 0.9.4 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -30,10 +30,11 @@
     "esbuild": "^0.25.12",
     "lucide-react": "^1.17.0",
     "open": "^10.1.0",
+    "picocolors": "^1.1.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "2.4.1"
+    "@sudajs/theme-engine": "2.5.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -14,6 +14,53 @@ Your job in a theme project is to create a complete, publishable theme with them
 - React, React DOM, Puck, and `@sudajs/theme-engine` are host-provided peers. Do not bundle private copies into the theme runtime.
 - Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
 
+## Editor i18n and locales
+
+Theme editor labels are localized by the host editor. Use the template's
+`src/i18n.ts` helper for every component label, field label, option label, and
+other editor-facing configuration string.
+
+- Import `t` from `./i18n.js` in files that define `pageConfig`, `layoutConfig`,
+  fields, options, or local blocks.
+- Write labels as stable dot-path keys, for example
+  `label: t("sections.hero.fields.title")`, not hardcoded strings.
+- Add every key used with `t(...)` to `src/locales/en.json`. This file is the
+  required reference locale for theme validation.
+- Keep locale values as nested JSON objects whose leaves are strings. Arrays,
+  numbers, booleans, and null are invalid locale values.
+- When adding another locale such as `src/locales/zh-CN.json`, keep its leaf key
+  set exactly aligned with `src/locales/en.json`; missing or extra keys fail
+  `suda theme validate`, `suda theme check`, `pnpm build`, and publish.
+- The CLI copies `src/locales/*.json` into `dist/locales/` during build. Do not
+  edit `dist/locales/` directly.
+- If an installed legacy theme is missing locale files, the editor falls back to
+  showing translation keys instead of crashing. New themes must still pass
+  locale validation before publishing.
+- Do not put actual page content, starter page copy, default prop values, or
+  public-site text through `t(...)`. Those belong in component props and starter
+  page data so users can edit them.
+
+Example:
+
+```tsx
+import { t } from "./i18n.js";
+
+export const Hero: SudaComponentConfig<HeroProps> = {
+  label: t("sections.hero.label"),
+  fields: {
+    title: { type: "text", label: t("sections.hero.fields.title") },
+    tone: {
+      type: "radio",
+      label: t("sections.hero.fields.tone"),
+      options: [
+        { label: t("sections.hero.fields.toneWarm"), value: "warm" },
+        { label: t("sections.hero.fields.toneSharp"), value: "sharp" },
+      ],
+    },
+  },
+};
+```
+
 ## Component strategy
 
 - Create theme-specific components and sections first. Every page component should express this theme's brand, industry, visual rhythm, and content model.
@@ -51,6 +98,9 @@ Use the most specific field type available. A generic `text` field may pass type
 - Use `select` or `radio` for fixed choices. Keep option values stable, short, and serializable.
 - Use `array` for repeatable items and `object` for grouped settings. Keep nested field names aligned with the prop shape and `defaultProps`.
 - Use `textarea` for multi-sentence copy. Use `text` only for short labels, headings, slugs, names, or plain strings that are not URLs, media, colors, icons, fonts, or menus.
+- Use `t(...)` for every editor-facing `label` in components, fields, nested
+  `arrayFields` / `object.fields`, local blocks, and option lists. Add matching
+  keys to `src/locales/en.json` at the same time.
 - For card grids, feature lists, pricing tables, logo walls, gallery grids, and any multi-column component, expose a `columns` prop with a `range` or `select` field and a sensible default.
 - Use `visibleIf: ({ props }, { fields }) => boolean` for synchronous field visibility that depends on sibling props or resolved fields. Keep it pure and fast.
 - Use Puck `resolveFields` only for heavier dynamic field changes that cannot be expressed with `visibleIf`.
@@ -68,17 +118,9 @@ Good component instructions explain:
 - Frequency: whether it should appear once, multiple times, or only near another section.
 - Composition: required neighboring content or local blocks, when relevant.
 
-- Prefer Suda field helpers over generic text fields: use `url` for links and routes, `image` for images, `video` for videos, `media` for mixed media, `color` for colors, `icon` for icon names, `font` for font selections, `range` for bounded numbers, `spacing` for spacing tokens, and `menu` for navigation items.
 - For icons, expose props with `{ type: "icon" }`, type values as `SudaLucideIconName`, render them with `SudaLucideIcon` from `@sudajs/theme-engine/runtime`, and store canonical Lucide names such as `"rocket"` or `"mouse-pointer-click"` (not `"lucide-rocket"`). Do not keep theme-local icon maps, emoji/icon switch statements, or custom SVG icon registries unless the theme truly needs a bespoke non-Lucide graphic.
-- Use `select` or `radio` when authors must choose from a fixed set of values. Keep option values stable and serializable.
-- Use `array` for repeatable items and `object` for grouped settings. Keep nested field names aligned with the prop shape and `defaultProps`.
-- For card grids, feature lists, pricing tables, logo walls, gallery grids, and any multi-column component, expose a `columns` prop with a `range` or `select` field and a sensible default.
-- Use `textarea` for multi-sentence copy and `text` only for short labels, headings, slugs, or plain strings that are not URLs/media/color/icon/font values.
-- Keep `fields`, `defaultProps`, and `render` in sync: every editor field should have a sensible default and render should tolerate omitted optional values.
-- Put editor-only controls in props when they change rendering, for example `showLogo`; pair dependent controls with `visibleIf` rather than hiding logic only in JSX.
-- Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
 - Add optional field-level `ai.instructions`, `ai.required`, or `ai.exclude` when a prop needs generation guidance beyond its label and type.
-Use `ai.exclude: true` only for structural or editor-only components, and still provide instructions explaining why AI must not generate them. `PageOutlet` is the standard example.
+- Use `ai.exclude: true` only for structural or editor-only components, and still provide instructions explaining why AI must not generate them. `PageOutlet` is the standard example.
 
 ## Block slot authoring rules
 

package/templates/theme/README.md

@@ -23,6 +23,8 @@ pnpm validate
 
 Theme-local assets live in top-level `assets/`. The starter hero exposes a Logo field that defaults to `assets/brand/suda-logo.svg`, so you can replace it with your own brand image or choose a different image in the editor.
 
+Editor labels are localized through `src/i18n.ts` and `src/locales/*.json`. Use `t("...")` for component labels, field labels, and option labels, then add matching string leaves to `src/locales/en.json`. `en.json` is required, and any additional locale file must have the same leaf key set. `pnpm validate`, `suda theme check`, and `pnpm build` verify the locale contract.
+
 Preview screenshots are required before publishing:
 
 ```bash

package/templates/theme/src/i18n.ts

@@ -0,0 +1,13 @@
+import { createThemeTranslate } from "@sudajs/theme-engine/runtime";
+
+import type en from "./locales/en.json" with { type: "json" };
+
+type DotPath<T, Prefix extends string = ""> = T extends string
+  ? Prefix
+  : {
+      [Key in keyof T & string]: DotPath<T[Key], Prefix extends "" ? Key : `${Prefix}.${Key}`>;
+    }[keyof T & string];
+
+export type MessageKeys = DotPath<typeof en>;
+
+export const t = createThemeTranslate<MessageKeys>();

package/templates/theme/src/layout.tsx

@@ -2,6 +2,8 @@ import type { SudaComponentConfig, SudaRootConfig } from "@sudajs/theme-engine";
 import { getIcpRecord, getPageSlot, getWhiteLabel } from "@sudajs/theme-engine/runtime";
 import type { ReactElement, ReactNode } from "react";
 
+import { t } from "./i18n.js";
+
 type PuckExtras = { puck?: { metadata?: Record<string, unknown> } };
 type RootProps = { children?: ReactNode; title?: string };
 type HeaderProps = { siteName?: string };
@@ -10,7 +12,7 @@ type FooterProps = { text?: string } & PuckExtras;
 
 export const rootConfig: SudaRootConfig<RootProps> = {
   fields: {
-    title: { type: "text", label: "Site title" },
+    title: { type: "text", label: t("layout.root.fields.title") },
   },
   defaultProps: { title: "__SUDA_THEME_KEY__" },
   render: ({ children, title }) => (
@@ -21,20 +23,20 @@ export const rootConfig: SudaRootConfig<RootProps> = {
 };
 
 export const Header: SudaComponentConfig<HeaderProps> = {
-  label: "Header",
+  label: t("layout.header.label"),
   ai: {
     instructions:
       "Site-wide header rendered at the top of every page. " +
       "Place once at the top of the layout (not inside page content). " +
       "Used for branding and primary navigation, not for promotional content.",
   },
-  fields: { siteName: { type: "text", label: "Site name" } },
+  fields: { siteName: { type: "text", label: t("layout.header.fields.siteName") } },
   defaultProps: { siteName: "__SUDA_THEME_KEY__" },
   render: ({ siteName }) => <header className="__SUDA_THEME_KEY__-header">{siteName}</header>,
 };
 
 export const PageOutlet: SudaComponentConfig<PageOutletProps> = {
-  label: "Page outlet",
+  label: t("layout.pageOutlet.label"),
   ai: {
     exclude: true,
     instructions:
@@ -47,14 +49,14 @@ export const PageOutlet: SudaComponentConfig<PageOutletProps> = {
 };
 
 export const Footer: SudaComponentConfig<FooterProps> = {
-  label: "Footer",
+  label: t("layout.footer.label"),
   ai: {
     instructions:
       "Site-wide footer rendered at the bottom of every page. " +
       "Place once at the end of the layout. " +
       "Used for legal text, copyright, and secondary links — not for primary CTAs.",
   },
-  fields: { text: { type: "text", label: "Text" } },
+  fields: { text: { type: "text", label: t("layout.footer.fields.text") } },
   defaultProps: { text: "© __SUDA_THEME_KEY__" },
   render: ({ text, puck }) => {
     const whiteLabel = getWhiteLabel(puck?.metadata);

package/templates/theme/src/locales/en.json

@@ -0,0 +1,69 @@
+{
+  "layout": {
+    "root": {
+      "fields": {
+        "title": "Site title"
+      }
+    },
+    "header": {
+      "label": "Header",
+      "fields": {
+        "siteName": "Site name"
+      }
+    },
+    "pageOutlet": {
+      "label": "Page outlet"
+    },
+    "footer": {
+      "label": "Footer",
+      "fields": {
+        "text": "Text"
+      }
+    }
+  },
+  "sections": {
+    "hero": {
+      "label": "Hero",
+      "fields": {
+        "showLogo": "Show logo",
+        "show": "Show",
+        "hide": "Hide",
+        "logo": "Logo",
+        "eyebrow": "Eyebrow",
+        "title": "Title",
+        "description": "Description",
+        "primaryLabel": "Primary button label",
+        "primaryHref": "Primary button link"
+      }
+    },
+    "featureGrid": {
+      "label": "Feature grid",
+      "fields": {
+        "title": "Title",
+        "description": "Description",
+        "columns": "Columns",
+        "features": "Features",
+        "featureTitle": "Title",
+        "featureIcon": "Icon",
+        "featureDescription": "Description"
+      }
+    },
+    "testimonial": {
+      "label": "Testimonial",
+      "fields": {
+        "quote": "Quote",
+        "author": "Author",
+        "role": "Role"
+      }
+    },
+    "callToAction": {
+      "label": "Call to action",
+      "fields": {
+        "title": "Title",
+        "description": "Description",
+        "buttonLabel": "Button label",
+        "buttonHref": "Button link"
+      }
+    }
+  }
+}

package/templates/theme/src/sections.tsx

@@ -1,6 +1,7 @@
 import type { SudaComponentConfig, SudaLucideIconName } from "@sudajs/theme-engine";
 import { resolveAsset, SudaLucideIcon, type ThemeRenderMetadata } from "@sudajs/theme-engine/runtime";
 
+import { t } from "./i18n.js";
 import { themeAsset } from "./theme-asset.js";
 
 type FeatureItem = { icon?: SudaLucideIconName; title?: string; description?: string };
@@ -33,7 +34,7 @@ type CallToActionProps = {
 };
 
 export const Hero: SudaComponentConfig<HeroProps> = {
-  label: "Hero",
+  label: t("sections.hero.label"),
   ai: {
     instructions:
       "Primary page introduction used to communicate the main value proposition. " +
@@ -44,22 +45,22 @@ export const Hero: SudaComponentConfig<HeroProps> = {
   fields: {
     showLogo: {
       type: "radio",
-      label: "Show logo",
+      label: t("sections.hero.fields.showLogo"),
       options: [
-        { label: "Show", value: true },
-        { label: "Hide", value: false },
+        { label: t("sections.hero.fields.show"), value: true },
+        { label: t("sections.hero.fields.hide"), value: false },
       ],
     },
     logo: {
       type: "image",
-      label: "Logo",
+      label: t("sections.hero.fields.logo"),
       visibleIf: ({ props }) => props.showLogo !== false,
     },
-    eyebrow: { type: "text", label: "Eyebrow" },
-    title: { type: "text", label: "Title" },
-    description: { type: "textarea", label: "Description" },
-    primaryLabel: { type: "text", label: "Primary button label" },
-    primaryHref: { type: "url", label: "Primary button link" },
+    eyebrow: { type: "text", label: t("sections.hero.fields.eyebrow") },
+    title: { type: "text", label: t("sections.hero.fields.title") },
+    description: { type: "textarea", label: t("sections.hero.fields.description") },
+    primaryLabel: { type: "text", label: t("sections.hero.fields.primaryLabel") },
+    primaryHref: { type: "url", label: t("sections.hero.fields.primaryHref") },
   },
   defaultProps: {
     showLogo: true,
@@ -98,7 +99,7 @@ export const Hero: SudaComponentConfig<HeroProps> = {
 };
 
 export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
-  label: "Feature grid",
+  label: t("sections.featureGrid.label"),
   ai: {
     instructions:
       "Section that lists 3–6 short feature or benefit cards explaining what the product or service offers. " +
@@ -106,16 +107,16 @@ export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
       "Use when the page needs to communicate multiple distinct value points; do not use for testimonials, FAQs, or step-by-step processes.",
   },
   fields: {
-    title: { type: "text", label: "Title" },
-    description: { type: "textarea", label: "Description" },
-    columns: { type: "range", label: "Columns", min: 2, max: 4, step: 1 },
+    title: { type: "text", label: t("sections.featureGrid.fields.title") },
+    description: { type: "textarea", label: t("sections.featureGrid.fields.description") },
+    columns: { type: "range", label: t("sections.featureGrid.fields.columns"), min: 2, max: 4, step: 1 },
     features: {
       type: "array",
-      label: "Features",
+      label: t("sections.featureGrid.fields.features"),
       arrayFields: {
-        title: { type: "text", label: "Title" },
-        icon: { type: "icon", label: "Icon" },
-        description: { type: "textarea", label: "Description" },
+        title: { type: "text", label: t("sections.featureGrid.fields.featureTitle") },
+        icon: { type: "icon", label: t("sections.featureGrid.fields.featureIcon") },
+        description: { type: "textarea", label: t("sections.featureGrid.fields.featureDescription") },
       },
     },
   },
@@ -150,7 +151,7 @@ export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
 };
 
 export const Testimonial: SudaComponentConfig<TestimonialProps> = {
-  label: "Testimonial",
+  label: t("sections.testimonial.label"),
   ai: {
     instructions:
       "Section that quotes a single customer or expert as social proof. " +
@@ -158,9 +159,9 @@ export const Testimonial: SudaComponentConfig<TestimonialProps> = {
       "Do not invent quotes, names, or roles; only use content the user provides.",
   },
   fields: {
-    quote: { type: "textarea", label: "Quote" },
-    author: { type: "text", label: "Author" },
-    role: { type: "text", label: "Role" },
+    quote: { type: "textarea", label: t("sections.testimonial.fields.quote") },
+    author: { type: "text", label: t("sections.testimonial.fields.author") },
+    role: { type: "text", label: t("sections.testimonial.fields.role") },
   },
   defaultProps: {
     quote: "SudaCloud gives our team a practical editing workflow without giving up theme control.",
@@ -178,7 +179,7 @@ export const Testimonial: SudaComponentConfig<TestimonialProps> = {
 };
 
 export const CallToAction: SudaComponentConfig<CallToActionProps> = {
-  label: "Call to action",
+  label: t("sections.callToAction.label"),
   ai: {
     instructions:
       "Closing conversion section that invites the visitor to take a specific action (sign up, contact, buy, etc.). " +
@@ -186,10 +187,10 @@ export const CallToAction: SudaComponentConfig<CallToActionProps> = {
       "Use at most once per page. Do not use as the page's first introduction — the Hero component fills that role.",
   },
   fields: {
-    title: { type: "text", label: "Title" },
-    description: { type: "textarea", label: "Description" },
-    buttonLabel: { type: "text", label: "Button label" },
-    buttonHref: { type: "url", label: "Button link" },
+    title: { type: "text", label: t("sections.callToAction.fields.title") },
+    description: { type: "textarea", label: t("sections.callToAction.fields.description") },
+    buttonLabel: { type: "text", label: t("sections.callToAction.fields.buttonLabel") },
+    buttonHref: { type: "url", label: t("sections.callToAction.fields.buttonHref") },
   },
   defaultProps: {
     title: "Ready to build your next page?",