@helpai/elements 0.30.1 → 0.31.0

package/schema.json

@@ -628,7 +628,7 @@
               "properties": {
                 "text": {
                   "default": "👋 Hi! Need any help?",
-                  "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →' or 'Try our new feature!').",
+                  "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is.",
                   "type": "string",
                   "minLength": 1,
                   "maxLength": 500
@@ -1590,6 +1590,104 @@
                 "default": true,
                 "description": "Submitted marker expands in place to a read-only list of the visitor's answers. Set `false` for sensitive answers that shouldn't linger on screen.",
                 "type": "boolean"
+              },
+              "defaultLocale": {
+                "description": "BCP-47 locale the top-level strings (title / fields copy) are authored in.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 35
+              },
+              "translations": {
+                "description": "Per-locale string overrides — the data module trims to the bootstrap `?locale=` (≤1); the widget overlays it onto the default copy.",
+                "maxItems": 50,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "locale": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 35,
+                      "description": "BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`)."
+                    },
+                    "title": {
+                      "type": "string",
+                      "maxLength": 120
+                    },
+                    "description": {
+                      "type": "string",
+                      "maxLength": 500
+                    },
+                    "submitLabel": {
+                      "type": "string",
+                      "maxLength": 60
+                    },
+                    "fields": {
+                      "maxItems": 50,
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "name": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 80,
+                            "description": "The canonical field `name` this localizes."
+                          },
+                          "label": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 200
+                          },
+                          "placeholder": {
+                            "type": "string",
+                            "maxLength": 200
+                          },
+                          "validationHint": {
+                            "type": "string",
+                            "maxLength": 280
+                          },
+                          "options": {
+                            "maxItems": 50,
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "value": {
+                                  "type": "string",
+                                  "minLength": 1,
+                                  "maxLength": 200,
+                                  "description": "The canonical option `value` this localizes."
+                                },
+                                "label": {
+                                  "type": "string",
+                                  "minLength": 1,
+                                  "maxLength": 200
+                                },
+                                "description": {
+                                  "type": "string",
+                                  "maxLength": 280
+                                }
+                              },
+                              "required": [
+                                "value"
+                              ],
+                              "additionalProperties": {}
+                            }
+                          }
+                        },
+                        "required": [
+                          "name"
+                        ],
+                        "additionalProperties": {}
+                      }
+                    }
+                  },
+                  "required": [
+                    "locale"
+                  ],
+                  "additionalProperties": {}
+                }
               }
             },
             "required": [
@@ -2395,7 +2493,7 @@
                   "properties": {
                     "text": {
                       "default": "👋 Hi! Need any help?",
-                      "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →' or 'Try our new feature!').",
+                      "description": "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here →'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is.",
                       "type": "string",
                       "minLength": 1,
                       "maxLength": 500

package/schema.mjs

@@ -171,7 +171,7 @@ var calloutShapeSchema = z6.enum(["pill", "bubble", "callout"]);
 var calloutPositionSchema = z6.enum(["auto", "horizontal", "vertical"]);
 var launcherCalloutSchema = z6.object({
   text: z6.string().min(1).max(500).default("\u{1F44B} Hi! Need any help?").describe(
-    "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here \u2192' or 'Try our new feature!')."
+    "The message to show in the bubble. Defaults to a friendly greeting; replace with your own copy (e.g. 'Click here \u2192'). May also be an i18n key (e.g. `launcherCallout`) resolved against `i18n.strings` for per-locale copy; a non-key literal renders as-is."
   ),
   shape: calloutShapeSchema.default("pill").describe("Visual shape \u2014 `pill` (slim label + arrow), `bubble` (speech-bubble tail), `callout` (loud variant)."),
   position: calloutPositionSchema.default("auto").describe(
@@ -417,6 +417,25 @@ var formConditionSchema = z12.object({
   minMessages: z12.number().int().min(0).max(1e3).optional(),
   maxMessages: z12.number().int().min(0).max(1e3).optional()
 }).loose();
+var fieldOptionTranslationSchema = z12.object({
+  value: z12.string().min(1).max(200).describe("The canonical option `value` this localizes."),
+  label: z12.string().min(1).max(200).optional(),
+  description: z12.string().max(280).optional()
+}).loose();
+var formFieldTranslationSchema = z12.object({
+  name: z12.string().min(1).max(80).describe("The canonical field `name` this localizes."),
+  label: z12.string().min(1).max(200).optional(),
+  placeholder: z12.string().max(200).optional(),
+  validationHint: z12.string().max(280).optional(),
+  options: z12.array(fieldOptionTranslationSchema).max(50).optional()
+}).loose();
+var formTranslationSchema = z12.object({
+  locale: localeSchema,
+  title: z12.string().max(120).optional(),
+  description: z12.string().max(500).optional(),
+  submitLabel: z12.string().max(60).optional(),
+  fields: z12.array(formFieldTranslationSchema).max(50).optional()
+}).loose();
 var formDefSchema = z12.object({
   id: z12.string().min(1).max(80).describe("Stable id \u2014 persistence dedupe + `manual` openForm(id)."),
   on: z12.union([formTriggerSchema, z12.array(formTriggerSchema).min(1).max(8)]).describe("Trigger(s) that surface this form."),
@@ -435,6 +454,10 @@ var formDefSchema = z12.object({
   ),
   reviewable: z12.boolean().default(true).describe(
     "Submitted marker expands in place to a read-only list of the visitor's answers. Set `false` for sensitive answers that shouldn't linger on screen."
+  ),
+  defaultLocale: localeSchema.optional().describe("BCP-47 locale the top-level strings (title / fields copy) are authored in."),
+  translations: z12.array(formTranslationSchema).max(50).optional().describe(
+    "Per-locale string overrides \u2014 the data module trims to the bootstrap `?locale=` (\u22641); the widget overlays it onto the default copy."
   )
 }).loose();
 var formsSchema = z12.array(formDefSchema).max(20).describe(
@@ -871,12 +894,15 @@ export {
   feedbackEventSchema,
   feedbackSchema,
   fieldOptionSchema,
+  fieldOptionTranslationSchema,
   fieldTypeSchema,
   fieldValidationSchema,
   footerSchema,
   formConditionSchema,
   formDefSchema,
   formFieldSchema,
+  formFieldTranslationSchema,
+  formTranslationSchema,
   formTriggerSchema,
   formsSchema,
   handshakeResponseSchema,

package/web-component.mjs

@@ -275,8 +275,8 @@ function resolveStrings(locale, override) {
 function primaryTag(locale) {
   return (locale.split("-")[0] ?? "en").toLowerCase();
 }
-function moduleLabel(strings, label) {
-  return strings[label] ?? label;
+function localizeText(strings, value) {
+  return strings[value] ?? value;
 }
 function isNestedShape(override) {
   if (!override) return false;
@@ -286,6 +286,51 @@ function isNestedShape(override) {
   return false;
 }
 
+// src/i18n/overlay.ts
+function pickTranslation(translations, locale) {
+  if (!translations?.length || !locale) return void 0;
+  return translations.find((t) => t.locale === locale);
+}
+function overlayContent(item, locale) {
+  const { translations, defaultLocale: _defaultLocale, ...base } = item;
+  const tr = pickTranslation(translations, locale);
+  if (!tr) return base;
+  return {
+    ...base,
+    title: tr.title ?? base.title,
+    description: tr.description ?? base.description,
+    content: tr.content ?? base.content
+  };
+}
+function overlayFormDef(def, locale) {
+  const { translations, defaultLocale: _defaultLocale, ...base } = def;
+  const tr = pickTranslation(translations, locale);
+  if (!tr) return base;
+  const fieldTrByName = new Map((tr.fields ?? []).map((f) => [f.name, f]));
+  const fields = base.fields.map((field) => {
+    const ftr = fieldTrByName.get(field.name);
+    if (!ftr) return field;
+    const optionTrByValue = new Map((ftr.options ?? []).map((o) => [o.value, o]));
+    return {
+      ...field,
+      label: ftr.label ?? field.label,
+      placeholder: ftr.placeholder ?? field.placeholder,
+      validationHint: ftr.validationHint ?? field.validationHint,
+      options: field.options?.map((option) => {
+        const otr = optionTrByValue.get(option.value);
+        return otr ? { ...option, label: otr.label ?? option.label, description: otr.description ?? option.description } : option;
+      })
+    };
+  });
+  return {
+    ...base,
+    title: tr.title ?? base.title,
+    description: tr.description ?? base.description,
+    submitLabel: tr.submitLabel ?? base.submitLabel,
+    fields
+  };
+}
+
 // src/core/storage.ts
 var LocalStorageAdapter = class {
   get(key) {
@@ -537,7 +582,7 @@ function resolveOptions(rawOpts) {
       humanInLoop: opts.features?.humanInLoop ?? DEFAULT_FEATURES.humanInLoop,
       tools: opts.features?.tools
     },
-    forms: resolveForms(opts.forms),
+    forms: resolveForms(opts.forms, locale),
     endpoints: {
       upload: opts.endpoints?.upload ?? DEFAULT_ENDPOINTS.upload,
       transcribe: opts.endpoints?.transcribe ?? DEFAULT_ENDPOINTS.transcribe,
@@ -660,13 +705,14 @@ function resolveModules(overrides) {
   const byId = Object.fromEntries(list.map((m) => [m.id, m]));
   return { list, byId };
 }
-function resolveForms(overrides) {
+function resolveForms(overrides, locale) {
   var _a;
   if (!overrides?.length) return DEFAULT_FORMS;
   const list = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const def of overrides) {
-    if (!def?.id || seen.has(def.id)) continue;
+  for (const raw of overrides) {
+    if (!raw?.id || seen.has(raw.id)) continue;
+    const def = overlayFormDef(raw, locale);
     const fields = (def.fields ?? []).filter((f) => Boolean(f && f.name && f.label && f.type));
     const triggers = (Array.isArray(def.on) ? def.on : [def.on]).map(parseTrigger).filter((t) => t !== null);
     if (fields.length === 0 || triggers.length === 0) continue;
@@ -1803,7 +1849,7 @@ var AgentTransport = class {
   }
   /** Fetch content rows by filter. `GET /pai/content` (data-API), TTL-cached. */
   listContent(query = {}) {
-    const key = JSON.stringify(query, Object.keys(query).toSorted());
+    const key = `${this.locale ?? ""}|${JSON.stringify(query, Object.keys(query).toSorted())}`;
     const cached = this.contentCache.get(key);
     if (cached && Date.now() - cached.at < CONTENT_CACHE_TTL_MS) {
       log5.debug("listContent \u2192 cache", query);
@@ -1824,7 +1870,7 @@ var AgentTransport = class {
     }
     log5.debug("listContent \u2192", query);
     const res = await this.getJson(url.toString(), "listContent");
-    const items = res.items ?? [];
+    const items = (res.items ?? []).map((item) => overlayContent(item, this.locale));
     log5.debug("listContent \u2190", { count: items.length, total: res.pagination?.total });
     return { ...res, items };
   }
@@ -3084,7 +3130,7 @@ function mountRawSvg(host, source) {
   } catch {
   }
 }
-function LauncherCallout({ callout, launcherPosition, closeLabel, onDismiss }) {
+function LauncherCallout({ callout, launcherPosition, strings, closeLabel, onDismiss }) {
   const [visible, setVisible] = useState(false);
   useEffect(() => {
     const id = setTimeout(() => setVisible(true), callout.delayMs);
@@ -3106,7 +3152,7 @@ function LauncherCallout({ callout, launcherPosition, closeLabel, onDismiss }) {
       "data-animated": callout.animated ? "true" : void 0,
       "data-testid": TID.callout,
       children: [
-        /* @__PURE__ */ jsx2("span", { children: callout.text }),
+        /* @__PURE__ */ jsx2("span", { children: localizeText(strings, callout.text) }),
         /* @__PURE__ */ jsx2(
           "button",
           {
@@ -5666,9 +5712,16 @@ function createController(depsRef) {
     else if (form.frequency !== "always") depsRef.current.persistence.saveFormDone(form.id);
     depsRef.current.onComplete(form, trigger, values, skipped);
   };
+  const refresh = () => {
+    const active = activeForm.value;
+    if (!active) return;
+    const next = depsRef.current.forms.list.find((f) => f.id === active.form.id);
+    if (next && next !== active.form) activeForm.value = { form: next, trigger: active.trigger };
+  };
   return {
     activeForm,
     fire,
+    refresh,
     complete: (values) => finish(values, false),
     skip: () => finish({}, true)
   };
@@ -6080,7 +6133,7 @@ function HomeRoot(props2) {
   const greeting = resolveGreeting(props2);
   const avatars = config.userAvatars ?? [];
   const status = config.status;
-  const contentTitle = config.contentBlockTitle ? moduleLabel(strings, config.contentBlockTitle) : strings.homeContentTitle;
+  const contentTitle = config.contentBlockTitle ? localizeText(strings, config.contentBlockTitle) : strings.homeContentTitle;
   return /* @__PURE__ */ jsx29("div", { class: `${p25}-module ${p25}-home`, "data-testid": TID.homeView, children: /* @__PURE__ */ jsxs24("div", { class: `${p25}-home-scroll`, children: [
     /* @__PURE__ */ jsxs24("div", { class: `${p25}-home-hero`, children: [
       /* @__PURE__ */ jsxs24("div", { class: `${p25}-home-hero-top`, children: [
@@ -6235,7 +6288,7 @@ function HomeTabBar({ modules, activeTab, strings, unreadCount, onSelect }) {
             /* @__PURE__ */ jsx31(Icon, {}),
             badge ? /* @__PURE__ */ jsx31("span", { class: `${p27}-tab-badge`, "data-testid": TID.tabBadge, children: badge }) : null
           ] }),
-          /* @__PURE__ */ jsx31("span", { class: `${p27}-tab-label`, children: moduleLabel(strings, m.label) })
+          /* @__PURE__ */ jsx31("span", { class: `${p27}-tab-label`, children: localizeText(strings, m.label) })
         ]
       },
       m.id
@@ -6906,7 +6959,7 @@ function App({ options, hostElement, bus }) {
     void (async () => {
       try {
         const res = await dataBootRef.current;
-        setRemoteForms(resolveForms((res ?? { forms: [] }).forms));
+        setRemoteForms(resolveForms((res ?? { forms: [] }).forms, effectiveLocale));
       } catch (err) {
         log16.debug("bootstrap failed \u2014 treating as no forms", { err });
       } finally {
@@ -6924,6 +6977,23 @@ function App({ options, hostElement, bus }) {
       void runResume(handle);
     }
   }, [activated]);
+  const formsLocaleRef = useRef9(null);
+  useEffect17(() => {
+    if (!activated) return;
+    if (formsLocaleRef.current === null) {
+      formsLocaleRef.current = effectiveLocale;
+      return;
+    }
+    if (formsLocaleRef.current === effectiveLocale) return;
+    formsLocaleRef.current = effectiveLocale;
+    let cancelled = false;
+    void transport.bootstrap().then((res) => {
+      if (!cancelled) setRemoteForms(resolveForms((res ?? { forms: [] }).forms, effectiveLocale));
+    }).catch((err) => log16.debug("forms re-localize failed \u2014 keeping current copy", { err }));
+    return () => {
+      cancelled = true;
+    };
+  }, [activated, effectiveLocale, transport]);
   const lastUserSig = useRef9(userSig);
   useEffect17(() => {
     if (!conversationReady || lastUserSig.current === userSig) return;
@@ -7080,6 +7150,9 @@ function App({ options, hostElement, bus }) {
     }
   });
   const activeForm = useComputed7(() => forms.activeForm.value);
+  useEffect17(() => {
+    forms.refresh();
+  }, [effectiveForms, forms]);
   const pageArea = options.pageContext?.area ? String(options.pageContext.area) : void 0;
   const msgCount = useComputed7(() => messagesSig.value.length);
   useEffect17(() => {
@@ -7466,6 +7539,7 @@ function App({ options, hostElement, bus }) {
       {
         callout: calloutToRender,
         launcherPosition: effectiveOptions.position,
+        strings: effectiveOptions.strings,
         closeLabel: effectiveOptions.strings.close,
         onDismiss: dismissCallout
       }