@embeddables/cli 0.7.18 → 0.7.19

package/.prompts/embeddables-cli.md

@@ -360,7 +360,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 +692,140 @@ 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:
+
+```tsx
+import { OptionSelector } from '@embeddables/cli/components'
+import type { OptionSelectorButton } from '@embeddables/cli/types'
+
+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.7.19",
   "type": "module",
   "bin": {
     "embeddables": "./bin/embeddables.mjs"