@embeddables/cli 0.7.18 → 0.8.0

package/.prompts/embeddables-cli.md

@@ -154,13 +154,13 @@ export function PageName() {
 }
 ```
 
-**OptionSelector buttons pattern**: When writing TSX files with `OptionSelector` components, define the buttons as constants before the JSX, then reference them in the `buttons` prop:
+**OptionSelector buttons pattern**: When writing TSX files with `OptionSelector` components, define the buttons as constants before the JSX, then reference them in the `buttons` prop. Use `OptionSelectorButtonWithLanguages` as the type (imported from `@embeddables/cli/components`) — this type extends `OptionSelectorButton` with an optional `languages` property, so it works for buttons both with and without translations:
 
 ```tsx
 'use client'
 
 import { OptionSelector } from '@embeddables/cli/components'
-import type { OptionSelectorButton } from '@embeddables/cli/types'
+import type { OptionSelectorButtonWithLanguages as OptionSelectorButton } from '@embeddables/cli/components'
 
 const planButtons: OptionSelectorButton[] = [
   { id: 'button_plan_basic', key: 'basic', text: 'Basic Plan', description: '$9/month' },
@@ -187,6 +187,8 @@ export default function PlanPage() {
 
 This pattern improves readability and makes the buttons array easier to maintain compared to defining it inline within the JSX.
 
+**Important**: Always use `OptionSelectorButtonWithLanguages` (not `OptionSelectorButton` from `@embeddables/cli/types`) when declaring button constants. The alias `as OptionSelectorButton` keeps the code readable while ensuring the type supports the `languages` property for translations. This matches what the CLI generates when reverse-compiling.
+
 ## Styles Structure (CSS)
 
 Styles are stored in `Flow.styles` as a map of CSS selectors to style objects. The `FlowStyles` type is defined in `src/types-builder.ts`.
@@ -360,7 +362,7 @@ Note: button icons and checkboxes are before text in the button, unless you set
 | `ButtonText`        | `<div>`          | `text` set                |                                                                                                   |
 | `ButtonDescription` | `<div>`          | `description` set         |                                                                                                   |
 | `ButtonIcon`        | `<svg>`/`<span>` | `icon` or `emojiIcon` set | If `icon`, must be font-awesome icon name; if `emojiIcon` must be an emoji in text format like 😀 |
-| `ButtonIconImage`   | `<span>`         | `imageUrl` set            | Use **`imageUrl`** only (not `imgSrc`). SVG URLs are valid.                                        |
+| `ButtonIconImage`   | `<span>`         | `imageUrl` set            | Use **`imageUrl`** only (not `imgSrc`). SVG URLs are valid.                                       |
 
 ### InputBox
 
@@ -692,6 +694,141 @@ The `config.json` file contains the reduced Embeddable JSON with:
 1. Update React file: `global-components/{locationKey}.location.tsx`
 2. Update styles if needed
 
+## Multi-Lingual / Translations
+
+Embeddables support translating component text into multiple languages. The default language is English (`en`), which uses the standard component properties (e.g. `text`, `label`, `placeholder`). Translations for other languages are stored alongside these properties.
+
+### How Translations are Stored
+
+**In JSON** (the underlying format): Translations use flat properties with the pattern `lang--{languageCode}--{attributeKey}`. For example, a Spanish translation of a button's text would be `"lang--es--text": "Enviar"`. The default language (`en`) value is always the base property itself (e.g. `"text": "Submit"`).
+
+**In React/TSX** (the local file format): Translations are represented as a `languages` prop — a nested object grouping translations by language code, then by attribute key. The CLI automatically converts between the two formats during compile and reverse-compile.
+
+### Adding Translations to Components
+
+Add a `languages` prop to any component in your `.page.tsx` or `.location.tsx` files. The prop is an object where each key is a language code (e.g. `es`, `fr`, `de`, `ja`) and each value is an object mapping attribute keys to translated strings.
+
+**Example — PlainText with translations:**
+
+```tsx
+<PlainText
+  id="comp_0000000001"
+  key="welcome_heading"
+  text="Welcome to our platform"
+  languages={{
+    es: { text: 'Bienvenido a nuestra plataforma' },
+    fr: { text: 'Bienvenue sur notre plateforme' },
+  }}
+/>
+```
+
+**Example — CustomButton with multiple translated attributes:**
+
+```tsx
+<CustomButton
+  id="comp_0000000002"
+  key="next_button"
+  text="Next Page >"
+  description="Head to the next step"
+  languages={{
+    es: {
+      text: 'Página siguiente >',
+      description: 'Pasar al siguiente paso',
+    },
+    fr: {
+      text: 'Page suivante >',
+      description: "Passez à l'étape suivante",
+    },
+  }}
+/>
+```
+
+**Example — InputBox with translated label, placeholder, and validation message:**
+
+```tsx
+<InputBox
+  id="comp_0000000003"
+  key="email"
+  input_type="email"
+  label="Email Address"
+  placeholder="Enter your email"
+  empty_invalid_message="Email is required"
+  languages={{
+    es: {
+      label: 'Correo electrónico',
+      placeholder: 'Ingrese su correo',
+      empty_invalid_message: 'El correo es requerido',
+    },
+    fr: {
+      label: 'Adresse e-mail',
+      placeholder: 'Entrez votre e-mail',
+      empty_invalid_message: "L'e-mail est requis",
+    },
+  }}
+/>
+```
+
+### Adding Translations to OptionSelector Buttons
+
+For OptionSelector components, translations are added on each **button** object (not on the component itself). Add a `languages` property inside each button definition. The `OptionSelectorButtonWithLanguages` type (not plain `OptionSelectorButton`) is required here since it includes the `languages` property:
+
+```tsx
+import { OptionSelector } from '@embeddables/cli/components'
+
+import type { OptionSelectorButtonWithLanguages as OptionSelectorButton } from '@embeddables/cli/components'
+
+const planButtons: OptionSelectorButton[] = [
+  {
+    id: 'button_plan_basic',
+    key: 'basic',
+    text: 'Basic Plan',
+    languages: {
+      es: { text: 'Plan Básico' },
+      fr: { text: 'Plan de base' },
+    },
+  },
+  {
+    id: 'button_plan_pro',
+    key: 'pro',
+    text: 'Pro Plan',
+    languages: {
+      es: { text: 'Plan Profesional' },
+      fr: { text: 'Plan Professionnel' },
+    },
+  },
+]
+
+export default function PlanPage() {
+  return <OptionSelector id="comp_0000000004" key="plan_selector" buttons={planButtons} />
+}
+```
+
+### Translatable Attributes
+
+Any text-based attribute on a component can be translated. Common translatable attributes include:
+
+| Component Type     | Translatable Attributes                                            |
+| ------------------ | ------------------------------------------------------------------ |
+| `PlainText`        | `text`                                                             |
+| `RichTextMarkdown` | `text`                                                             |
+| `CustomButton`     | `text`, `description`                                              |
+| `InputBox`         | `label`, `placeholder`, `empty_invalid_message`                    |
+| `OptionSelector`   | `label` (on the component); `text`, `description` (on each button) |
+| `MediaImage`       | `caption`, `alt_text`                                              |
+| `FileUpload`       | `label`                                                            |
+
+### Language Codes
+
+Use standard ISO 639-1 two-letter language codes: `es` (Spanish), `fr` (French), `de` (German), `pt` (Portuguese), `ja` (Japanese), `zh` (Chinese), `ko` (Korean), `ar` (Arabic), `it` (Italian), `nl` (Dutch), etc.
+
+### Key Rules
+
+1. **Default language is always `en`** — English text goes in the base property (e.g. `text="Submit"`), never in the `languages` prop.
+2. **Only translate non-default languages** — The `languages` prop should only contain entries for non-English languages.
+3. **Attribute keys must match** — The keys inside each language object (e.g. `text`, `label`) must match the actual component prop names exactly.
+4. **The `languages` prop is optional** — Components without translations simply omit it.
+5. **Translations round-trip cleanly** — The CLI converts `languages` → flat `lang--` properties when compiling to JSON, and flat `lang--` properties → `languages` when reverse-compiling to React. No manual conversion is needed.
+
 ## Important Notes
 
 - **IDs**: All components, pages, computed fields, actions, conditions, and buttons inside OptionSelectors have unique `id` properties. These are preserved in config.json and used for internal references, except for component and button ids which should always be written in React. **ID format**: Use a prefix plus 10 digits so generated IDs don't collide with real ones: pages → `page_` + 10 digits (e.g. `page_1234567890`); components → `comp_` + 10 digits; conditions → `cond_` + 10 digits (e.g. `cond_1234567890`); option buttons → `button_` prefix (e.g. `button_plan_basic`). Must be unique across the flow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embeddables/cli",
-  "version": "0.7.18",
+  "version": "0.8.0",
   "type": "module",
   "bin": {
     "embeddables": "./bin/embeddables.mjs"
@@ -55,6 +55,7 @@
     "@supabase/supabase-js": "^2.39.0",
     "@tailwindcss/postcss": "^4.1.18",
     "autoprefixer": "^10.4.23",
+    "boxen": "^8.0.1",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "cssjson": "^2.1.3",
@@ -62,6 +63,8 @@
     "express": "^4.19.2",
     "fast-glob": "^3.3.2",
     "http-proxy-middleware": "^3.0.3",
+    "log-symbols": "^7.0.1",
+    "ora": "^9.3.0",
     "picocolors": "^1.1.0",
     "postcss": "^8.5.6",
     "prompts": "^2.4.2",