@form-engine-ts/core 4.7.0 → 4.8.0

package/README.md

@@ -52,6 +52,9 @@ Required locales cover every source text that exists on the form, its fields, op
 safe maximum-length corrections while purging unregistered locale content. Pass
 `{ policy: { allowedLocales, maxLocales } }` to `populateSchemaTranslations` to reject inadmissible targets before the
 translation adapter runs.
+`normalizeLocale(locale)` returns the canonical BCP 47 tag, accepts underscore-separated compatibility input such as
+`ja_JP`, and returns `null` for invalid tags. Schema validation, sanitization, locale policy checks, and translation
+slot lookup use this same normalization so equivalent locale spellings cannot bypass constraints.
 
 Fields can use a `displayRule` with nested `all`/`any` condition groups and `show` or `hide` actions. Supported
 operators include equality, containment, emptiness, and numeric comparisons; the legacy `displayCondition` and

package/dist/index.cjs

@@ -57,6 +57,7 @@ __export(index_exports, {
   matchesSubmissionFilter: () => matchesSubmissionFilter,
   matchesSubmissionPageFilters: () => matchesSubmissionPageFilters,
   migrateSchemaTranslationMetadata: () => migrateSchemaTranslationMetadata,
+  normalizeLocale: () => normalizeLocale,
   normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
   pipeResponsesToCsvStream: () => pipeResponsesToCsvStream,
   populateSchemaTranslations: () => populateSchemaTranslations,
@@ -74,11 +75,27 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/locale.ts
+var normalizeLocale = (rawLocale) => {
+  if (!rawLocale || typeof rawLocale !== "string") return null;
+  const trimmed = rawLocale.trim().replace(/_/gu, "-");
+  if (trimmed.length === 0) return null;
+  try {
+    return Intl.getCanonicalLocales(trimmed)[0] ?? null;
+  } catch {
+    return null;
+  }
+};
+function canonicalLocaleOrRaw(rawLocale) {
+  return normalizeLocale(rawLocale) ?? rawLocale;
+}
+
 // src/policy.ts
 function collectRecordKeys(value, path, pathsByLocale) {
-  for (const locale of Object.keys(value ?? {})) {
+  for (const rawLocale of Object.keys(value ?? {})) {
+    const locale = canonicalLocaleOrRaw(rawLocale);
     const paths = pathsByLocale.get(locale) ?? [];
-    paths.push(`${path}.${locale}`);
+    paths.push(`${path}.${rawLocale}`);
     pathsByLocale.set(locale, paths);
   }
 }
@@ -109,13 +126,15 @@ function collectSchemaLocales(schema) {
   });
   const translationLocales = new Set(pathsByLocale.keys());
   const allUniqueLocales = /* @__PURE__ */ new Set([
-    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-    ...schema.supportedLocales ?? [],
+    ...schema.defaultLocale === void 0 ? [] : [canonicalLocaleOrRaw(schema.defaultLocale)],
+    ...(schema.supportedLocales ?? []).map(canonicalLocaleOrRaw),
     ...translationLocales
   ]);
+  const defaultLocale = schema.defaultLocale === void 0 ? void 0 : canonicalLocaleOrRaw(schema.defaultLocale);
+  const supportedLocales = (schema.supportedLocales ?? []).map(canonicalLocaleOrRaw);
   return {
-    ...schema.defaultLocale === void 0 ? {} : { defaultLocale: schema.defaultLocale },
-    supportedLocales: schema.supportedLocales ?? [],
+    ...defaultLocale === void 0 ? {} : { defaultLocale },
+    supportedLocales,
     translationLocales,
     allUniqueLocales,
     translationLocalePaths: pathsByLocale
@@ -138,7 +157,12 @@ function displayRuleSourceIds(field) {
 }
 function registeredEntries(value, registeredLocales) {
   if (value === void 0) return void 0;
-  const entries = Object.entries(value).filter(([locale]) => registeredLocales.has(locale));
+  const entries = [];
+  for (const [rawLocale, entry] of Object.entries(value)) {
+    const locale = normalizeLocale(rawLocale);
+    if (locale === null || !registeredLocales.has(locale)) continue;
+    entries.push([locale, entry]);
+  }
   return entries.length === 0 ? void 0 : Object.fromEntries(entries);
 }
 function sanitizeNodeLocales(node, registeredLocales) {
@@ -176,6 +200,16 @@ function sanitizePageLocales(page, registeredLocales) {
   const translations = registeredEntries(page.translations, registeredLocales);
   return { ...base, ...translations === void 0 ? {} : { translations } };
 }
+function normalizedLocaleList(locales) {
+  return [
+    ...new Set(
+      locales.flatMap((locale) => {
+        const normalized = normalizeLocale(locale);
+        return normalized === null ? [] : [normalized];
+      })
+    )
+  ];
+}
 function sanitizeFieldConstraints(field, policy) {
   const constraint = policy?.fieldConstraints?.[field.type];
   if (constraint === void 0) return field;
@@ -290,10 +324,9 @@ function validateSchemaStructure(schema) {
 }
 function sanitizeSchema(schema, options = {}) {
   const existingQuestionIds = new Set(schema.fields.map((field) => field.id));
-  const registeredLocales = /* @__PURE__ */ new Set([
-    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-    ...schema.supportedLocales ?? []
-  ]);
+  const defaultLocale = schema.defaultLocale === void 0 ? null : normalizeLocale(schema.defaultLocale);
+  const supportedLocales = schema.supportedLocales === void 0 ? void 0 : normalizedLocaleList(schema.supportedLocales);
+  const registeredLocales = /* @__PURE__ */ new Set([...defaultLocale === null ? [] : [defaultLocale], ...supportedLocales ?? []]);
   const cyclic = cyclicQuestionIds(schema.fields);
   const sanitizedFields = schema.fields.map((sourceField) => {
     const field = sanitizeFieldConstraints(sanitizeFieldLocales(sourceField, registeredLocales), options.policy);
@@ -311,10 +344,17 @@ function sanitizeSchema(schema, options = {}) {
     return sanitized;
   });
   const localizedSchema = sanitizeNodeLocales(schema, registeredLocales);
-  const { translations: _translations, ...schemaWithoutLocaleContent } = localizedSchema;
+  const {
+    defaultLocale: _defaultLocale,
+    supportedLocales: _supportedLocales,
+    translations: _translations,
+    ...schemaWithoutLocaleContent
+  } = localizedSchema;
   const translations = registeredEntries(schema.translations, registeredLocales);
   const base = {
     ...schemaWithoutLocaleContent,
+    ...defaultLocale === null ? {} : { defaultLocale },
+    ...supportedLocales === void 0 ? {} : { supportedLocales },
     ...translations === void 0 ? {} : { translations },
     fields: sanitizedFields
   };
@@ -367,6 +407,12 @@ function isRecord(value) {
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
+function localeRecordEntry(record, locale) {
+  for (const [candidate, value] of Object.entries(record ?? {})) {
+    if (canonicalLocaleOrRaw(candidate) === locale) return value;
+  }
+  return void 0;
+}
 function issue(issues, path, code, message) {
   issues.push({ path, code, message });
 }
@@ -729,51 +775,55 @@ function collectSchemaText(schema) {
   return entries;
 }
 function addRequiredTranslationIssues(schema, locale, issues) {
-  if (!(schema.supportedLocales ?? []).includes(locale)) {
+  if (!(schema.supportedLocales ?? []).some((candidate) => canonicalLocaleOrRaw(candidate) === locale)) {
     issue(issues, "supportedLocales", "required_locale_missing", `Required locale ${locale} is missing.`);
   }
-  if (locale === schema.defaultLocale) return;
+  if (schema.defaultLocale !== void 0 && canonicalLocaleOrRaw(schema.defaultLocale) === locale) return;
+  const formTranslation = localeRecordEntry(schema.translations, locale);
   const required = [
-    { path: `translations.${locale}.title`, value: schema.translations?.[locale]?.title }
+    { path: `translations.${locale}.title`, value: formTranslation?.title }
   ];
   if (schema.description !== void 0)
-    required.push({ path: `translations.${locale}.description`, value: schema.translations?.[locale]?.description });
+    required.push({ path: `translations.${locale}.description`, value: formTranslation?.description });
   if (schema.completionMessage !== void 0) {
     required.push({
       path: `translations.${locale}.completionMessage`,
-      value: schema.translations?.[locale]?.completionMessage
+      value: formTranslation?.completionMessage
     });
   }
   schema.fields.forEach((field, fieldIndex) => {
+    const fieldTranslation = localeRecordEntry(field.translations, locale);
     required.push({
       path: `fields[${fieldIndex}].translations.${locale}.title`,
-      value: field.translations?.[locale]?.title
+      value: fieldTranslation?.title
     });
     if (field.description !== void 0) {
       required.push({
         path: `fields[${fieldIndex}].translations.${locale}.description`,
-        value: field.translations?.[locale]?.description
+        value: fieldTranslation?.description
       });
     }
     if (!("options" in field)) return;
     field.options.forEach((option, optionIndex) => {
+      const optionTranslation = localeRecordEntry(option.translations, locale);
       required.push({
         path: `fields[${fieldIndex}].options[${optionIndex}].translations.${locale}`,
-        value: option.translations?.[locale]
+        value: optionTranslation
       });
     });
   });
   schema.pages?.forEach((page, pageIndex) => {
+    const pageTranslation = localeRecordEntry(page.translations, locale);
     if (page.title !== void 0) {
       required.push({
         path: `pages[${pageIndex}].translations.${locale}.title`,
-        value: page.translations?.[locale]?.title
+        value: pageTranslation?.title
       });
     }
     if (page.description !== void 0) {
       required.push({
         path: `pages[${pageIndex}].translations.${locale}.description`,
-        value: page.translations?.[locale]?.description
+        value: pageTranslation?.description
       });
     }
   });
@@ -906,8 +956,8 @@ function validatePolicy(schema, policy, issues) {
   }
   const collectedLocales = collectSchemaLocales(schema);
   const registeredLocales = /* @__PURE__ */ new Set([
-    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-    ...schema.supportedLocales ?? []
+    ...collectedLocales.defaultLocale === void 0 ? [] : [collectedLocales.defaultLocale],
+    ...collectedLocales.supportedLocales
   ]);
   for (const locale of collectedLocales.translationLocales) {
     if (registeredLocales.has(locale)) continue;
@@ -921,23 +971,27 @@ function validatePolicy(schema, policy, issues) {
     }
   }
   if (policy.allowedLocales !== void 0) {
+    const allowedLocales = new Set(policy.allowedLocales.map(canonicalLocaleOrRaw));
     const pathsByLocale = /* @__PURE__ */ new Map();
-    if (schema.defaultLocale !== void 0) pathsByLocale.set(schema.defaultLocale, ["defaultLocale"]);
+    if (collectedLocales.defaultLocale !== void 0)
+      pathsByLocale.set(collectedLocales.defaultLocale, ["defaultLocale"]);
     schema.supportedLocales?.forEach((locale, index) => {
-      pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], `supportedLocales[${index}]`]);
+      const canonical = canonicalLocaleOrRaw(locale);
+      pathsByLocale.set(canonical, [...pathsByLocale.get(canonical) ?? [], `supportedLocales[${index}]`]);
     });
     for (const [locale, paths] of collectedLocales.translationLocalePaths) {
       pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], ...paths]);
     }
     for (const [locale, paths] of pathsByLocale) {
-      if (!policy.allowedLocales.includes(locale)) {
+      if (!allowedLocales.has(locale)) {
         for (const path of paths) {
           issue(issues, path, "disallowed_locale", `Locale ${locale} is not allowed by the form policy.`);
         }
       }
     }
-    for (const locale of policy.requiredLocales ?? []) {
-      if (!policy.allowedLocales.includes(locale)) {
+    for (const rawLocale of policy.requiredLocales ?? []) {
+      const locale = canonicalLocaleOrRaw(rawLocale);
+      if (!allowedLocales.has(locale)) {
         issue(
           issues,
           "policy.requiredLocales",
@@ -950,7 +1004,8 @@ function validatePolicy(schema, policy, issues) {
   if (policy.maxLocales !== void 0 && collectedLocales.allUniqueLocales.size > policy.maxLocales) {
     issue(issues, "supportedLocales", "max_locales_exceeded", `At most ${policy.maxLocales} locales are allowed.`);
   }
-  for (const locale of policy.requiredLocales ?? []) addRequiredTranslationIssues(schema, locale, issues);
+  for (const locale of policy.requiredLocales ?? [])
+    addRequiredTranslationIssues(schema, canonicalLocaleOrRaw(locale), issues);
   if (policy.maxSchemaBytes !== void 0) {
     try {
       const byteLength = new TextEncoder().encode(JSON.stringify(schema)).byteLength;
@@ -985,8 +1040,12 @@ function validateFormSchema(input, options = {}) {
       );
     }
   }
-  if (input.defaultLocale !== void 0 && !isNonEmptyString(input.defaultLocale)) {
-    issue(issues, "defaultLocale", "invalid_locale", "Expected a non-empty default locale.");
+  if (input.defaultLocale !== void 0) {
+    if (!isNonEmptyString(input.defaultLocale)) {
+      issue(issues, "defaultLocale", "invalid_locale", "Expected a non-empty default locale.");
+    } else if (normalizeLocale(input.defaultLocale) === null) {
+      issue(issues, "defaultLocale", "invalid_locale", "Expected a valid BCP 47 locale.");
+    }
   }
   if (input.supportedLocales !== void 0) {
     if (!Array.isArray(input.supportedLocales) || input.supportedLocales.length === 0) {
@@ -996,10 +1055,15 @@ function validateFormSchema(input, options = {}) {
       input.supportedLocales.forEach((locale, index) => {
         if (!isNonEmptyString(locale)) {
           issue(issues, `supportedLocales[${index}]`, "invalid_locale", "Expected a non-empty locale.");
-        } else if (locales.has(locale)) {
-          issue(issues, `supportedLocales[${index}]`, "duplicate_locale", "Locales must be unique.");
         } else {
-          locales.add(locale);
+          const normalized = normalizeLocale(locale);
+          if (normalized === null) {
+            issue(issues, `supportedLocales[${index}]`, "invalid_locale", "Expected a valid BCP 47 locale.");
+          } else if (locales.has(normalized)) {
+            issue(issues, `supportedLocales[${index}]`, "duplicate_locale", "Locales must be unique.");
+          } else {
+            locales.add(normalized);
+          }
         }
       });
     }
@@ -2268,8 +2332,15 @@ function withTranslationMetadata(node, locale, property, metadata) {
     }
   };
 }
-function createSlot(kind, nodeId, property, locale, sourceText, existingText, nodeMetadata, existingTranslationMetadata, options = {}) {
-  const path = `${kind}.${nodeId}.${property}`;
+function localeRecordEntry2(record, locale) {
+  const normalizedLocale = normalizeLocale(locale) ?? locale;
+  for (const [candidate, value] of Object.entries(record ?? {})) {
+    if ((normalizeLocale(candidate) ?? candidate) === normalizedLocale) return value;
+  }
+  return void 0;
+}
+function createSlot(kind, nodeId, property, locale, sourceText, existingText, nodeMetadata, existingTranslationMetadata, options = {}, parentId) {
+  const path = kind === "form" ? `form.${property}` : kind === "option" ? `fields.${parentId ?? ""}.options.${nodeId}.${property}` : `${kind}s.${nodeId}.${property}`;
   const manual = options.isManualTranslation?.(existingTranslationMetadata, { path, locale }) ?? isManualTranslationMetadata(existingTranslationMetadata);
   const normalizedMetadata = existingTranslationMetadata === void 0 ? void 0 : options.normalizeMetadata === void 0 ? existingTranslationMetadata : { ...options.normalizeMetadata(existingTranslationMetadata, sourceText) };
   const status = getTranslationStatusWithManualOverride(sourceText, existingText, normalizedMetadata, manual);
@@ -2289,7 +2360,10 @@ function createSlot(kind, nodeId, property, locale, sourceText, existingText, no
   };
 }
 function translationSlots(schema, locale, options = {}) {
+  locale = normalizeLocale(locale) ?? locale;
   const descriptors = [];
+  const schemaTranslation = localeRecordEntry2(schema.translations, locale);
+  const schemaTranslationMetadata = localeRecordEntry2(schema.translationMetadata, locale);
   const addFormSlot = (property, sourceText) => {
     const slot = createSlot(
       "form",
@@ -2297,17 +2371,17 @@ function translationSlots(schema, locale, options = {}) {
       property,
       locale,
       sourceText,
-      schema.translations?.[locale]?.[property],
+      schemaTranslation?.[property],
       schema.metadata,
-      schema.translationMetadata?.[locale]?.[property],
+      schemaTranslationMetadata?.[property],
       options
     );
     descriptors.push({
       slot,
-      manual: options.isManualTranslation?.(schema.translationMetadata?.[locale]?.[property], {
+      manual: options.isManualTranslation?.(schemaTranslationMetadata?.[property], {
         path: slot.path ?? "",
         locale
-      }) ?? isManualTranslationMetadata(schema.translationMetadata?.[locale]?.[property]),
+      }) ?? isManualTranslationMetadata(schemaTranslationMetadata?.[property]),
       apply: (current, value, metadata) => withTranslationMetadata(
         { ...current, translations: mergeLocalizedText(current.translations, locale, property, value) },
         locale,
@@ -2320,6 +2394,8 @@ function translationSlots(schema, locale, options = {}) {
   if (schema.description !== void 0) addFormSlot("description", schema.description);
   if (schema.completionMessage !== void 0) addFormSlot("completionMessage", schema.completionMessage);
   schema.fields.forEach((field, fieldIndex) => {
+    const fieldTranslation = localeRecordEntry2(field.translations, locale);
+    const fieldTranslationMetadata = localeRecordEntry2(field.translationMetadata, locale);
     const addFieldSlot = (property, sourceText) => {
       const slot = createSlot(
         "field",
@@ -2327,17 +2403,17 @@ function translationSlots(schema, locale, options = {}) {
         property,
         locale,
         sourceText,
-        field.translations?.[locale]?.[property],
+        fieldTranslation?.[property],
         field.metadata,
-        field.translationMetadata?.[locale]?.[property],
+        fieldTranslationMetadata?.[property],
         options
       );
       descriptors.push({
         slot,
-        manual: options.isManualTranslation?.(field.translationMetadata?.[locale]?.[property], {
+        manual: options.isManualTranslation?.(fieldTranslationMetadata?.[property], {
           path: slot.path ?? "",
           locale
-        }) ?? isManualTranslationMetadata(field.translationMetadata?.[locale]?.[property]),
+        }) ?? isManualTranslationMetadata(fieldTranslationMetadata?.[property]),
         apply: (current, value, metadata) => ({
           ...current,
           fields: current.fields.map(
@@ -2358,23 +2434,26 @@ function translationSlots(schema, locale, options = {}) {
     if (field.description !== void 0) addFieldSlot("description", field.description);
     if ("options" in field) {
       field.options.forEach((option, optionIndex) => {
+        const optionTranslation = localeRecordEntry2(option.translations, locale);
+        const optionTranslationMetadata = localeRecordEntry2(option.translationMetadata, locale);
         const slot = createSlot(
           "option",
           option.id,
           "label",
           locale,
           option.label,
-          option.translations?.[locale],
+          optionTranslation,
           option.metadata,
-          option.translationMetadata?.[locale]?.label,
-          options
+          optionTranslationMetadata?.label,
+          options,
+          field.id
         );
         descriptors.push({
           slot,
-          manual: options.isManualTranslation?.(option.translationMetadata?.[locale]?.label, {
+          manual: options.isManualTranslation?.(optionTranslationMetadata?.label, {
             path: slot.path ?? "",
             locale
-          }) ?? isManualTranslationMetadata(option.translationMetadata?.[locale]?.label),
+          }) ?? isManualTranslationMetadata(optionTranslationMetadata?.label),
           apply: (current, value, metadata) => ({
             ...current,
             fields: current.fields.map((candidate, candidateIndex) => {
@@ -2400,6 +2479,8 @@ function translationSlots(schema, locale, options = {}) {
     }
   });
   schema.pages?.forEach((page, pageIndex) => {
+    const pageTranslation = localeRecordEntry2(page.translations, locale);
+    const pageTranslationMetadata = localeRecordEntry2(page.translationMetadata, locale);
     const addPageSlot = (property, sourceText) => {
       const slot = createSlot(
         "page",
@@ -2407,17 +2488,17 @@ function translationSlots(schema, locale, options = {}) {
         property,
         locale,
         sourceText,
-        page.translations?.[locale]?.[property],
+        pageTranslation?.[property],
         page.metadata,
-        page.translationMetadata?.[locale]?.[property],
+        pageTranslationMetadata?.[property],
         options
       );
       descriptors.push({
         slot,
-        manual: options.isManualTranslation?.(page.translationMetadata?.[locale]?.[property], {
+        manual: options.isManualTranslation?.(pageTranslationMetadata?.[property], {
           path: slot.path ?? "",
           locale
-        }) ?? isManualTranslationMetadata(page.translationMetadata?.[locale]?.[property]),
+        }) ?? isManualTranslationMetadata(pageTranslationMetadata?.[property]),
         apply: (current, value, metadata) => ({
           ...current,
           ...current.pages === void 0 ? {} : {
@@ -2505,7 +2586,7 @@ var migrateSchemaTranslationMetadata = (schema, migratorOrOptions) => {
     (locale, property) => ({
       locale,
       defaultLocale,
-      path: property,
+      path: `form.${property}`,
       property,
       nodeKind: "form"
     }),
@@ -2604,8 +2685,11 @@ function collectTranslationSlots(schema, locale) {
   return translationSlots(schema, locale).map((descriptor) => descriptor.slot);
 }
 function resolveLocalizedSchema(schema, targetLocale) {
-  if (targetLocale === void 0 || targetLocale.length === 0 || targetLocale === schema.defaultLocale) return schema;
-  const formTranslation = schema.translations?.[targetLocale];
+  if (targetLocale === void 0 || targetLocale.length === 0) return schema;
+  const normalizedTargetLocale = normalizeLocale(targetLocale) ?? targetLocale;
+  const defaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale);
+  if (normalizedTargetLocale === defaultLocale || targetLocale === schema.defaultLocale) return schema;
+  const formTranslation = localeRecordEntry2(schema.translations, normalizedTargetLocale);
   const completionMessage = formTranslation?.completionMessage ?? schema.completionMessage;
   return {
     ...schema,
@@ -2613,7 +2697,7 @@ function resolveLocalizedSchema(schema, targetLocale) {
     ...(formTranslation?.description ?? schema.description) === void 0 ? {} : { description: formTranslation?.description ?? schema.description },
     ...completionMessage === void 0 ? {} : { completionMessage },
     fields: schema.fields.map((field) => {
-      const translation = field.translations?.[targetLocale];
+      const translation = localeRecordEntry2(field.translations, normalizedTargetLocale);
       const localized = {
         ...field,
         title: translation?.title ?? field.title,
@@ -2624,13 +2708,13 @@ function resolveLocalizedSchema(schema, targetLocale) {
         ...localized,
         options: field.options.map((option) => ({
           ...option,
-          label: option.translations?.[targetLocale] ?? option.label
+          label: localeRecordEntry2(option.translations, normalizedTargetLocale) ?? option.label
         }))
       };
     }),
     ...schema.pages === void 0 ? {} : {
       pages: schema.pages.map((page) => {
-        const translation = page.translations?.[targetLocale];
+        const translation = localeRecordEntry2(page.translations, normalizedTargetLocale);
         const title = translation?.title ?? page.title;
         const description = translation?.description ?? page.description;
         return {
@@ -2644,8 +2728,13 @@ function resolveLocalizedSchema(schema, targetLocale) {
 }
 async function populateSchemaTranslations(schema, targetLocales, adapter, options = {}) {
   assertValidFormSchema(schema);
-  const locales = [...new Set(targetLocales.filter((locale) => locale.length > 0 && locale !== schema.defaultLocale))];
-  const allowedLocales = options.policy?.allowedLocales;
+  const defaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale) ?? schema.defaultLocale;
+  const locales = [
+    ...new Set(
+      targetLocales.map((locale) => normalizeLocale(locale) ?? locale.trim()).filter((locale) => locale.length > 0 && locale !== defaultLocale)
+    )
+  ];
+  const allowedLocales = options.policy?.allowedLocales?.map((locale) => normalizeLocale(locale) ?? locale);
   const collectedLocales = collectSchemaLocales(schema);
   const disallowedLocale = [...collectedLocales.allUniqueLocales, ...locales].find(
     (locale) => allowedLocales !== void 0 && !allowedLocales.includes(locale)
@@ -2687,7 +2776,7 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
       adapter,
       selected.map((descriptor) => descriptor.slot.sourceText),
       locale,
-      schema.defaultLocale
+      defaultLocale
     );
     if (translated.length !== selected.length) {
       throw new Error(`Translation adapter returned ${translated.length} texts for ${selected.length} inputs.`);
@@ -2696,7 +2785,7 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
       const translatedText = translated[index];
       if (translatedText === void 0) throw new Error("Translation adapter returned an unexpected result.");
       const metadata = options.createMetadata?.(descriptor.slot, translatedText) ?? {
-        sourceLocale: schema.defaultLocale ?? "",
+        sourceLocale: defaultLocale ?? "",
         sourceTextHash: computeSourceTextHash(descriptor.slot.sourceText),
         translationSource: "automatic",
         translatedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -2707,8 +2796,8 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
   }
   const supportedLocales = [
     .../* @__PURE__ */ new Set([
-      ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-      ...schema.supportedLocales ?? [],
+      ...defaultLocale === void 0 ? [] : [defaultLocale],
+      ...(schema.supportedLocales ?? []).map((locale) => normalizeLocale(locale) ?? locale),
       ...locales
     ])
   ];
@@ -3044,6 +3133,7 @@ function assertVersionMutable(status) {
   matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   migrateSchemaTranslationMetadata,
+  normalizeLocale,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,
   populateSchemaTranslations,

package/dist/index.d.cts

@@ -657,6 +657,14 @@ interface CreateSubmissionOptions extends ExtensibleNode {
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+/**
+ * Normalizes a locale string to its BCP 47 canonical form.
+ *
+ * Underscore-separated locale tags are accepted for compatibility with common
+ * platform and user-input conventions. Invalid tags return null.
+ */
+declare const normalizeLocale: (rawLocale: string) => string | null;
+
 interface TranslationSlot {
     readonly kind: "form" | "page" | "field" | "option";
     readonly nodeId: string;
@@ -768,4 +776,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormSubmissionSettings, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LegacyTranslationMetadata, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationReport, type TranslationSlot, type TranslationStatus, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormSubmissionSettings, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LegacyTranslationMetadata, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationReport, type TranslationSlot, type TranslationStatus, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -657,6 +657,14 @@ interface CreateSubmissionOptions extends ExtensibleNode {
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+/**
+ * Normalizes a locale string to its BCP 47 canonical form.
+ *
+ * Underscore-separated locale tags are accepted for compatibility with common
+ * platform and user-input conventions. Invalid tags return null.
+ */
+declare const normalizeLocale: (rawLocale: string) => string | null;
+
 interface TranslationSlot {
     readonly kind: "form" | "page" | "field" | "option";
     readonly nodeId: string;
@@ -768,4 +776,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormSubmissionSettings, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LegacyTranslationMetadata, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationReport, type TranslationSlot, type TranslationStatus, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormSubmissionSettings, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LegacyTranslationMetadata, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationReport, type TranslationSlot, type TranslationStatus, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -1,8 +1,24 @@
+// src/locale.ts
+var normalizeLocale = (rawLocale) => {
+  if (!rawLocale || typeof rawLocale !== "string") return null;
+  const trimmed = rawLocale.trim().replace(/_/gu, "-");
+  if (trimmed.length === 0) return null;
+  try {
+    return Intl.getCanonicalLocales(trimmed)[0] ?? null;
+  } catch {
+    return null;
+  }
+};
+function canonicalLocaleOrRaw(rawLocale) {
+  return normalizeLocale(rawLocale) ?? rawLocale;
+}
+
 // src/policy.ts
 function collectRecordKeys(value, path, pathsByLocale) {
-  for (const locale of Object.keys(value ?? {})) {
+  for (const rawLocale of Object.keys(value ?? {})) {
+    const locale = canonicalLocaleOrRaw(rawLocale);
     const paths = pathsByLocale.get(locale) ?? [];
-    paths.push(`${path}.${locale}`);
+    paths.push(`${path}.${rawLocale}`);
     pathsByLocale.set(locale, paths);
   }
 }
@@ -33,13 +49,15 @@ function collectSchemaLocales(schema) {
   });
   const translationLocales = new Set(pathsByLocale.keys());
   const allUniqueLocales = /* @__PURE__ */ new Set([
-    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-    ...schema.supportedLocales ?? [],
+    ...schema.defaultLocale === void 0 ? [] : [canonicalLocaleOrRaw(schema.defaultLocale)],
+    ...(schema.supportedLocales ?? []).map(canonicalLocaleOrRaw),
     ...translationLocales
   ]);
+  const defaultLocale = schema.defaultLocale === void 0 ? void 0 : canonicalLocaleOrRaw(schema.defaultLocale);
+  const supportedLocales = (schema.supportedLocales ?? []).map(canonicalLocaleOrRaw);
   return {
-    ...schema.defaultLocale === void 0 ? {} : { defaultLocale: schema.defaultLocale },
-    supportedLocales: schema.supportedLocales ?? [],
+    ...defaultLocale === void 0 ? {} : { defaultLocale },
+    supportedLocales,
     translationLocales,
     allUniqueLocales,
     translationLocalePaths: pathsByLocale
@@ -62,7 +80,12 @@ function displayRuleSourceIds(field) {
 }
 function registeredEntries(value, registeredLocales) {
   if (value === void 0) return void 0;
-  const entries = Object.entries(value).filter(([locale]) => registeredLocales.has(locale));
+  const entries = [];
+  for (const [rawLocale, entry] of Object.entries(value)) {
+    const locale = normalizeLocale(rawLocale);
+    if (locale === null || !registeredLocales.has(locale)) continue;
+    entries.push([locale, entry]);
+  }
   return entries.length === 0 ? void 0 : Object.fromEntries(entries);
 }
 function sanitizeNodeLocales(node, registeredLocales) {
@@ -100,6 +123,16 @@ function sanitizePageLocales(page, registeredLocales) {
   const translations = registeredEntries(page.translations, registeredLocales);
   return { ...base, ...translations === void 0 ? {} : { translations } };
 }
+function normalizedLocaleList(locales) {
+  return [
+    ...new Set(
+      locales.flatMap((locale) => {
+        const normalized = normalizeLocale(locale);
+        return normalized === null ? [] : [normalized];
+      })
+    )
+  ];
+}
 function sanitizeFieldConstraints(field, policy) {
   const constraint = policy?.fieldConstraints?.[field.type];
   if (constraint === void 0) return field;
@@ -214,10 +247,9 @@ function validateSchemaStructure(schema) {
 }
 function sanitizeSchema(schema, options = {}) {
   const existingQuestionIds = new Set(schema.fields.map((field) => field.id));
-  const registeredLocales = /* @__PURE__ */ new Set([
-    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-    ...schema.supportedLocales ?? []
-  ]);
+  const defaultLocale = schema.defaultLocale === void 0 ? null : normalizeLocale(schema.defaultLocale);
+  const supportedLocales = schema.supportedLocales === void 0 ? void 0 : normalizedLocaleList(schema.supportedLocales);
+  const registeredLocales = /* @__PURE__ */ new Set([...defaultLocale === null ? [] : [defaultLocale], ...supportedLocales ?? []]);
   const cyclic = cyclicQuestionIds(schema.fields);
   const sanitizedFields = schema.fields.map((sourceField) => {
     const field = sanitizeFieldConstraints(sanitizeFieldLocales(sourceField, registeredLocales), options.policy);
@@ -235,10 +267,17 @@ function sanitizeSchema(schema, options = {}) {
     return sanitized;
   });
   const localizedSchema = sanitizeNodeLocales(schema, registeredLocales);
-  const { translations: _translations, ...schemaWithoutLocaleContent } = localizedSchema;
+  const {
+    defaultLocale: _defaultLocale,
+    supportedLocales: _supportedLocales,
+    translations: _translations,
+    ...schemaWithoutLocaleContent
+  } = localizedSchema;
   const translations = registeredEntries(schema.translations, registeredLocales);
   const base = {
     ...schemaWithoutLocaleContent,
+    ...defaultLocale === null ? {} : { defaultLocale },
+    ...supportedLocales === void 0 ? {} : { supportedLocales },
     ...translations === void 0 ? {} : { translations },
     fields: sanitizedFields
   };
@@ -291,6 +330,12 @@ function isRecord(value) {
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
+function localeRecordEntry(record, locale) {
+  for (const [candidate, value] of Object.entries(record ?? {})) {
+    if (canonicalLocaleOrRaw(candidate) === locale) return value;
+  }
+  return void 0;
+}
 function issue(issues, path, code, message) {
   issues.push({ path, code, message });
 }
@@ -653,51 +698,55 @@ function collectSchemaText(schema) {
   return entries;
 }
 function addRequiredTranslationIssues(schema, locale, issues) {
-  if (!(schema.supportedLocales ?? []).includes(locale)) {
+  if (!(schema.supportedLocales ?? []).some((candidate) => canonicalLocaleOrRaw(candidate) === locale)) {
     issue(issues, "supportedLocales", "required_locale_missing", `Required locale ${locale} is missing.`);
   }
-  if (locale === schema.defaultLocale) return;
+  if (schema.defaultLocale !== void 0 && canonicalLocaleOrRaw(schema.defaultLocale) === locale) return;
+  const formTranslation = localeRecordEntry(schema.translations, locale);
   const required = [
-    { path: `translations.${locale}.title`, value: schema.translations?.[locale]?.title }
+    { path: `translations.${locale}.title`, value: formTranslation?.title }
   ];
   if (schema.description !== void 0)
-    required.push({ path: `translations.${locale}.description`, value: schema.translations?.[locale]?.description });
+    required.push({ path: `translations.${locale}.description`, value: formTranslation?.description });
   if (schema.completionMessage !== void 0) {
     required.push({
       path: `translations.${locale}.completionMessage`,
-      value: schema.translations?.[locale]?.completionMessage
+      value: formTranslation?.completionMessage
     });
   }
   schema.fields.forEach((field, fieldIndex) => {
+    const fieldTranslation = localeRecordEntry(field.translations, locale);
     required.push({
       path: `fields[${fieldIndex}].translations.${locale}.title`,
-      value: field.translations?.[locale]?.title
+      value: fieldTranslation?.title
     });
     if (field.description !== void 0) {
       required.push({
         path: `fields[${fieldIndex}].translations.${locale}.description`,
-        value: field.translations?.[locale]?.description
+        value: fieldTranslation?.description
       });
     }
     if (!("options" in field)) return;
     field.options.forEach((option, optionIndex) => {
+      const optionTranslation = localeRecordEntry(option.translations, locale);
       required.push({
         path: `fields[${fieldIndex}].options[${optionIndex}].translations.${locale}`,
-        value: option.translations?.[locale]
+        value: optionTranslation
       });
     });
   });
   schema.pages?.forEach((page, pageIndex) => {
+    const pageTranslation = localeRecordEntry(page.translations, locale);
     if (page.title !== void 0) {
       required.push({
         path: `pages[${pageIndex}].translations.${locale}.title`,
-        value: page.translations?.[locale]?.title
+        value: pageTranslation?.title
       });
     }
     if (page.description !== void 0) {
       required.push({
         path: `pages[${pageIndex}].translations.${locale}.description`,
-        value: page.translations?.[locale]?.description
+        value: pageTranslation?.description
       });
     }
   });
@@ -830,8 +879,8 @@ function validatePolicy(schema, policy, issues) {
   }
   const collectedLocales = collectSchemaLocales(schema);
   const registeredLocales = /* @__PURE__ */ new Set([
-    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-    ...schema.supportedLocales ?? []
+    ...collectedLocales.defaultLocale === void 0 ? [] : [collectedLocales.defaultLocale],
+    ...collectedLocales.supportedLocales
   ]);
   for (const locale of collectedLocales.translationLocales) {
     if (registeredLocales.has(locale)) continue;
@@ -845,23 +894,27 @@ function validatePolicy(schema, policy, issues) {
     }
   }
   if (policy.allowedLocales !== void 0) {
+    const allowedLocales = new Set(policy.allowedLocales.map(canonicalLocaleOrRaw));
     const pathsByLocale = /* @__PURE__ */ new Map();
-    if (schema.defaultLocale !== void 0) pathsByLocale.set(schema.defaultLocale, ["defaultLocale"]);
+    if (collectedLocales.defaultLocale !== void 0)
+      pathsByLocale.set(collectedLocales.defaultLocale, ["defaultLocale"]);
     schema.supportedLocales?.forEach((locale, index) => {
-      pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], `supportedLocales[${index}]`]);
+      const canonical = canonicalLocaleOrRaw(locale);
+      pathsByLocale.set(canonical, [...pathsByLocale.get(canonical) ?? [], `supportedLocales[${index}]`]);
     });
     for (const [locale, paths] of collectedLocales.translationLocalePaths) {
       pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], ...paths]);
     }
     for (const [locale, paths] of pathsByLocale) {
-      if (!policy.allowedLocales.includes(locale)) {
+      if (!allowedLocales.has(locale)) {
         for (const path of paths) {
           issue(issues, path, "disallowed_locale", `Locale ${locale} is not allowed by the form policy.`);
         }
       }
     }
-    for (const locale of policy.requiredLocales ?? []) {
-      if (!policy.allowedLocales.includes(locale)) {
+    for (const rawLocale of policy.requiredLocales ?? []) {
+      const locale = canonicalLocaleOrRaw(rawLocale);
+      if (!allowedLocales.has(locale)) {
         issue(
           issues,
           "policy.requiredLocales",
@@ -874,7 +927,8 @@ function validatePolicy(schema, policy, issues) {
   if (policy.maxLocales !== void 0 && collectedLocales.allUniqueLocales.size > policy.maxLocales) {
     issue(issues, "supportedLocales", "max_locales_exceeded", `At most ${policy.maxLocales} locales are allowed.`);
   }
-  for (const locale of policy.requiredLocales ?? []) addRequiredTranslationIssues(schema, locale, issues);
+  for (const locale of policy.requiredLocales ?? [])
+    addRequiredTranslationIssues(schema, canonicalLocaleOrRaw(locale), issues);
   if (policy.maxSchemaBytes !== void 0) {
     try {
       const byteLength = new TextEncoder().encode(JSON.stringify(schema)).byteLength;
@@ -909,8 +963,12 @@ function validateFormSchema(input, options = {}) {
       );
     }
   }
-  if (input.defaultLocale !== void 0 && !isNonEmptyString(input.defaultLocale)) {
-    issue(issues, "defaultLocale", "invalid_locale", "Expected a non-empty default locale.");
+  if (input.defaultLocale !== void 0) {
+    if (!isNonEmptyString(input.defaultLocale)) {
+      issue(issues, "defaultLocale", "invalid_locale", "Expected a non-empty default locale.");
+    } else if (normalizeLocale(input.defaultLocale) === null) {
+      issue(issues, "defaultLocale", "invalid_locale", "Expected a valid BCP 47 locale.");
+    }
   }
   if (input.supportedLocales !== void 0) {
     if (!Array.isArray(input.supportedLocales) || input.supportedLocales.length === 0) {
@@ -920,10 +978,15 @@ function validateFormSchema(input, options = {}) {
       input.supportedLocales.forEach((locale, index) => {
         if (!isNonEmptyString(locale)) {
           issue(issues, `supportedLocales[${index}]`, "invalid_locale", "Expected a non-empty locale.");
-        } else if (locales.has(locale)) {
-          issue(issues, `supportedLocales[${index}]`, "duplicate_locale", "Locales must be unique.");
         } else {
-          locales.add(locale);
+          const normalized = normalizeLocale(locale);
+          if (normalized === null) {
+            issue(issues, `supportedLocales[${index}]`, "invalid_locale", "Expected a valid BCP 47 locale.");
+          } else if (locales.has(normalized)) {
+            issue(issues, `supportedLocales[${index}]`, "duplicate_locale", "Locales must be unique.");
+          } else {
+            locales.add(normalized);
+          }
         }
       });
     }
@@ -2192,8 +2255,15 @@ function withTranslationMetadata(node, locale, property, metadata) {
     }
   };
 }
-function createSlot(kind, nodeId, property, locale, sourceText, existingText, nodeMetadata, existingTranslationMetadata, options = {}) {
-  const path = `${kind}.${nodeId}.${property}`;
+function localeRecordEntry2(record, locale) {
+  const normalizedLocale = normalizeLocale(locale) ?? locale;
+  for (const [candidate, value] of Object.entries(record ?? {})) {
+    if ((normalizeLocale(candidate) ?? candidate) === normalizedLocale) return value;
+  }
+  return void 0;
+}
+function createSlot(kind, nodeId, property, locale, sourceText, existingText, nodeMetadata, existingTranslationMetadata, options = {}, parentId) {
+  const path = kind === "form" ? `form.${property}` : kind === "option" ? `fields.${parentId ?? ""}.options.${nodeId}.${property}` : `${kind}s.${nodeId}.${property}`;
   const manual = options.isManualTranslation?.(existingTranslationMetadata, { path, locale }) ?? isManualTranslationMetadata(existingTranslationMetadata);
   const normalizedMetadata = existingTranslationMetadata === void 0 ? void 0 : options.normalizeMetadata === void 0 ? existingTranslationMetadata : { ...options.normalizeMetadata(existingTranslationMetadata, sourceText) };
   const status = getTranslationStatusWithManualOverride(sourceText, existingText, normalizedMetadata, manual);
@@ -2213,7 +2283,10 @@ function createSlot(kind, nodeId, property, locale, sourceText, existingText, no
   };
 }
 function translationSlots(schema, locale, options = {}) {
+  locale = normalizeLocale(locale) ?? locale;
   const descriptors = [];
+  const schemaTranslation = localeRecordEntry2(schema.translations, locale);
+  const schemaTranslationMetadata = localeRecordEntry2(schema.translationMetadata, locale);
   const addFormSlot = (property, sourceText) => {
     const slot = createSlot(
       "form",
@@ -2221,17 +2294,17 @@ function translationSlots(schema, locale, options = {}) {
       property,
       locale,
       sourceText,
-      schema.translations?.[locale]?.[property],
+      schemaTranslation?.[property],
       schema.metadata,
-      schema.translationMetadata?.[locale]?.[property],
+      schemaTranslationMetadata?.[property],
       options
     );
     descriptors.push({
       slot,
-      manual: options.isManualTranslation?.(schema.translationMetadata?.[locale]?.[property], {
+      manual: options.isManualTranslation?.(schemaTranslationMetadata?.[property], {
         path: slot.path ?? "",
         locale
-      }) ?? isManualTranslationMetadata(schema.translationMetadata?.[locale]?.[property]),
+      }) ?? isManualTranslationMetadata(schemaTranslationMetadata?.[property]),
       apply: (current, value, metadata) => withTranslationMetadata(
         { ...current, translations: mergeLocalizedText(current.translations, locale, property, value) },
         locale,
@@ -2244,6 +2317,8 @@ function translationSlots(schema, locale, options = {}) {
   if (schema.description !== void 0) addFormSlot("description", schema.description);
   if (schema.completionMessage !== void 0) addFormSlot("completionMessage", schema.completionMessage);
   schema.fields.forEach((field, fieldIndex) => {
+    const fieldTranslation = localeRecordEntry2(field.translations, locale);
+    const fieldTranslationMetadata = localeRecordEntry2(field.translationMetadata, locale);
     const addFieldSlot = (property, sourceText) => {
       const slot = createSlot(
         "field",
@@ -2251,17 +2326,17 @@ function translationSlots(schema, locale, options = {}) {
         property,
         locale,
         sourceText,
-        field.translations?.[locale]?.[property],
+        fieldTranslation?.[property],
         field.metadata,
-        field.translationMetadata?.[locale]?.[property],
+        fieldTranslationMetadata?.[property],
         options
       );
       descriptors.push({
         slot,
-        manual: options.isManualTranslation?.(field.translationMetadata?.[locale]?.[property], {
+        manual: options.isManualTranslation?.(fieldTranslationMetadata?.[property], {
           path: slot.path ?? "",
           locale
-        }) ?? isManualTranslationMetadata(field.translationMetadata?.[locale]?.[property]),
+        }) ?? isManualTranslationMetadata(fieldTranslationMetadata?.[property]),
         apply: (current, value, metadata) => ({
           ...current,
           fields: current.fields.map(
@@ -2282,23 +2357,26 @@ function translationSlots(schema, locale, options = {}) {
     if (field.description !== void 0) addFieldSlot("description", field.description);
     if ("options" in field) {
       field.options.forEach((option, optionIndex) => {
+        const optionTranslation = localeRecordEntry2(option.translations, locale);
+        const optionTranslationMetadata = localeRecordEntry2(option.translationMetadata, locale);
         const slot = createSlot(
           "option",
           option.id,
           "label",
           locale,
           option.label,
-          option.translations?.[locale],
+          optionTranslation,
           option.metadata,
-          option.translationMetadata?.[locale]?.label,
-          options
+          optionTranslationMetadata?.label,
+          options,
+          field.id
         );
         descriptors.push({
           slot,
-          manual: options.isManualTranslation?.(option.translationMetadata?.[locale]?.label, {
+          manual: options.isManualTranslation?.(optionTranslationMetadata?.label, {
             path: slot.path ?? "",
             locale
-          }) ?? isManualTranslationMetadata(option.translationMetadata?.[locale]?.label),
+          }) ?? isManualTranslationMetadata(optionTranslationMetadata?.label),
           apply: (current, value, metadata) => ({
             ...current,
             fields: current.fields.map((candidate, candidateIndex) => {
@@ -2324,6 +2402,8 @@ function translationSlots(schema, locale, options = {}) {
     }
   });
   schema.pages?.forEach((page, pageIndex) => {
+    const pageTranslation = localeRecordEntry2(page.translations, locale);
+    const pageTranslationMetadata = localeRecordEntry2(page.translationMetadata, locale);
     const addPageSlot = (property, sourceText) => {
       const slot = createSlot(
         "page",
@@ -2331,17 +2411,17 @@ function translationSlots(schema, locale, options = {}) {
         property,
         locale,
         sourceText,
-        page.translations?.[locale]?.[property],
+        pageTranslation?.[property],
         page.metadata,
-        page.translationMetadata?.[locale]?.[property],
+        pageTranslationMetadata?.[property],
         options
       );
       descriptors.push({
         slot,
-        manual: options.isManualTranslation?.(page.translationMetadata?.[locale]?.[property], {
+        manual: options.isManualTranslation?.(pageTranslationMetadata?.[property], {
           path: slot.path ?? "",
           locale
-        }) ?? isManualTranslationMetadata(page.translationMetadata?.[locale]?.[property]),
+        }) ?? isManualTranslationMetadata(pageTranslationMetadata?.[property]),
         apply: (current, value, metadata) => ({
           ...current,
           ...current.pages === void 0 ? {} : {
@@ -2429,7 +2509,7 @@ var migrateSchemaTranslationMetadata = (schema, migratorOrOptions) => {
     (locale, property) => ({
       locale,
       defaultLocale,
-      path: property,
+      path: `form.${property}`,
       property,
       nodeKind: "form"
     }),
@@ -2528,8 +2608,11 @@ function collectTranslationSlots(schema, locale) {
   return translationSlots(schema, locale).map((descriptor) => descriptor.slot);
 }
 function resolveLocalizedSchema(schema, targetLocale) {
-  if (targetLocale === void 0 || targetLocale.length === 0 || targetLocale === schema.defaultLocale) return schema;
-  const formTranslation = schema.translations?.[targetLocale];
+  if (targetLocale === void 0 || targetLocale.length === 0) return schema;
+  const normalizedTargetLocale = normalizeLocale(targetLocale) ?? targetLocale;
+  const defaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale);
+  if (normalizedTargetLocale === defaultLocale || targetLocale === schema.defaultLocale) return schema;
+  const formTranslation = localeRecordEntry2(schema.translations, normalizedTargetLocale);
   const completionMessage = formTranslation?.completionMessage ?? schema.completionMessage;
   return {
     ...schema,
@@ -2537,7 +2620,7 @@ function resolveLocalizedSchema(schema, targetLocale) {
     ...(formTranslation?.description ?? schema.description) === void 0 ? {} : { description: formTranslation?.description ?? schema.description },
     ...completionMessage === void 0 ? {} : { completionMessage },
     fields: schema.fields.map((field) => {
-      const translation = field.translations?.[targetLocale];
+      const translation = localeRecordEntry2(field.translations, normalizedTargetLocale);
       const localized = {
         ...field,
         title: translation?.title ?? field.title,
@@ -2548,13 +2631,13 @@ function resolveLocalizedSchema(schema, targetLocale) {
         ...localized,
         options: field.options.map((option) => ({
           ...option,
-          label: option.translations?.[targetLocale] ?? option.label
+          label: localeRecordEntry2(option.translations, normalizedTargetLocale) ?? option.label
         }))
       };
     }),
     ...schema.pages === void 0 ? {} : {
       pages: schema.pages.map((page) => {
-        const translation = page.translations?.[targetLocale];
+        const translation = localeRecordEntry2(page.translations, normalizedTargetLocale);
         const title = translation?.title ?? page.title;
         const description = translation?.description ?? page.description;
         return {
@@ -2568,8 +2651,13 @@ function resolveLocalizedSchema(schema, targetLocale) {
 }
 async function populateSchemaTranslations(schema, targetLocales, adapter, options = {}) {
   assertValidFormSchema(schema);
-  const locales = [...new Set(targetLocales.filter((locale) => locale.length > 0 && locale !== schema.defaultLocale))];
-  const allowedLocales = options.policy?.allowedLocales;
+  const defaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale) ?? schema.defaultLocale;
+  const locales = [
+    ...new Set(
+      targetLocales.map((locale) => normalizeLocale(locale) ?? locale.trim()).filter((locale) => locale.length > 0 && locale !== defaultLocale)
+    )
+  ];
+  const allowedLocales = options.policy?.allowedLocales?.map((locale) => normalizeLocale(locale) ?? locale);
   const collectedLocales = collectSchemaLocales(schema);
   const disallowedLocale = [...collectedLocales.allUniqueLocales, ...locales].find(
     (locale) => allowedLocales !== void 0 && !allowedLocales.includes(locale)
@@ -2611,7 +2699,7 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
       adapter,
       selected.map((descriptor) => descriptor.slot.sourceText),
       locale,
-      schema.defaultLocale
+      defaultLocale
     );
     if (translated.length !== selected.length) {
       throw new Error(`Translation adapter returned ${translated.length} texts for ${selected.length} inputs.`);
@@ -2620,7 +2708,7 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
       const translatedText = translated[index];
       if (translatedText === void 0) throw new Error("Translation adapter returned an unexpected result.");
       const metadata = options.createMetadata?.(descriptor.slot, translatedText) ?? {
-        sourceLocale: schema.defaultLocale ?? "",
+        sourceLocale: defaultLocale ?? "",
         sourceTextHash: computeSourceTextHash(descriptor.slot.sourceText),
         translationSource: "automatic",
         translatedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -2631,8 +2719,8 @@ async function populateSchemaTranslations(schema, targetLocales, adapter, option
   }
   const supportedLocales = [
     .../* @__PURE__ */ new Set([
-      ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-      ...schema.supportedLocales ?? [],
+      ...defaultLocale === void 0 ? [] : [defaultLocale],
+      ...(schema.supportedLocales ?? []).map((locale) => normalizeLocale(locale) ?? locale),
       ...locales
     ])
   ];
@@ -2967,6 +3055,7 @@ export {
   matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   migrateSchemaTranslationMetadata,
+  normalizeLocale,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,
   populateSchemaTranslations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "publishConfig": {
     "access": "public"
   },