@form-engine-ts/core 4.6.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
@@ -63,7 +66,9 @@ and missing, translated, stale, or manual states for authoring tools. `populateS
 and missing entries while preserving manual translations and reports skipped reasons.
 
 Legacy translation metadata can be recognized with `isManualTranslationMetadata` and migrated with
-`migrateSchemaTranslationMetadata`; pass a custom migrator when legacy fields need application-specific conversion.
+`migrateSchemaTranslationMetadata`; pass a custom migrator (directly or as `{ migrator }`) when legacy fields need
+application-specific conversion. The migrator receives `TranslationMigrationContext` with the locale, JSON path,
+property, node kind, and node identifiers.
 `PopulateTranslationsOptions` is a compatibility alias for `PopulateTranslationOptions`, which also accepts custom
 manual-translation detection and metadata normalization callbacks. `removeLocaleFromSchema(schema, locale)` removes
 the locale from registrations and all form, page, field, option translation values and metadata; the default locale

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 ? {} : {
@@ -2456,10 +2537,9 @@ function removeLocalizedNodeLocale(node, locale) {
     ...translationMetadata === void 0 ? {} : { translationMetadata }
   };
 }
-function migrateMetadata(metadata, sourceText, defaultLocale, customMigrator) {
-  if (customMigrator !== void 0) return customMigrator(metadata, sourceText);
+function defaultTranslationMetadataMigrator(metadata, sourceText, defaultLocale) {
   const record = metadata !== null && typeof metadata === "object" ? metadata : void 0;
-  const sourceLocale = typeof record?.sourceLocale === "string" ? record.sourceLocale : defaultLocale ?? "";
+  const sourceLocale = typeof record?.sourceLocale === "string" ? record.sourceLocale : defaultLocale;
   const translationSource = isManualTranslationMetadata(record) ? "manual" : "automatic";
   return {
     sourceLocale,
@@ -2469,22 +2549,33 @@ function migrateMetadata(metadata, sourceText, defaultLocale, customMigrator) {
     ...typeof record?.editedAt === "string" ? { editedAt: record.editedAt } : {}
   };
 }
-function migrateNodeMetadata(node, sourceTexts, defaultLocale, customMigrator) {
+function migrateMetadata(metadata, sourceText, context, migrator) {
+  return migrator(metadata, sourceText, context);
+}
+function isTranslationMetadataProperty(property) {
+  return property === "title" || property === "description" || property === "label" || property === "completionMessage";
+}
+function migrateNodeMetadata(node, sourceTexts, contextFor, migrator) {
   if (node.translationMetadata === void 0) return node;
   const translationMetadata = Object.fromEntries(
     Object.entries(node.translationMetadata).map(([locale, properties]) => [
       locale,
       Object.fromEntries(
-        Object.entries(properties).map(([property, metadata]) => [
-          property,
-          migrateMetadata(metadata, sourceTexts[property] ?? "", defaultLocale, customMigrator)
-        ])
+        Object.entries(properties).map(([property, metadata]) => {
+          if (!isTranslationMetadataProperty(property)) return [property, metadata];
+          return [
+            property,
+            migrateMetadata(metadata, sourceTexts[property] ?? "", contextFor(locale, property), migrator)
+          ];
+        })
       )
     ])
   );
   return { ...node, translationMetadata };
 }
-var migrateSchemaTranslationMetadata = (schema, customMigrator) => {
+var migrateSchemaTranslationMetadata = (schema, migratorOrOptions) => {
+  const defaultLocale = schema.defaultLocale ?? "";
+  const migrator = typeof migratorOrOptions === "function" ? migratorOrOptions : migratorOrOptions?.migrator ?? ((metadata, sourceText, context) => defaultTranslationMetadataMigrator(metadata, sourceText, context.defaultLocale));
   const migratedSchema = migrateNodeMetadata(
     schema,
     {
@@ -2492,21 +2583,47 @@ var migrateSchemaTranslationMetadata = (schema, customMigrator) => {
       ...schema.description === void 0 ? {} : { description: schema.description },
       ...schema.completionMessage === void 0 ? {} : { completionMessage: schema.completionMessage }
     },
-    schema.defaultLocale,
-    customMigrator
+    (locale, property) => ({
+      locale,
+      defaultLocale,
+      path: `form.${property}`,
+      property,
+      nodeKind: "form"
+    }),
+    migrator
   );
   const fields = schema.fields.map((field) => {
     const migratedField = migrateNodeMetadata(
       field,
       { title: field.title, ...field.description === void 0 ? {} : { description: field.description } },
-      schema.defaultLocale,
-      customMigrator
+      (locale, property) => ({
+        locale,
+        defaultLocale,
+        path: `fields.${field.id}.${property}`,
+        property,
+        nodeKind: "field",
+        nodeId: field.id
+      }),
+      migrator
     );
     if (!("options" in migratedField)) return migratedField;
     return {
       ...migratedField,
       options: migratedField.options.map(
-        (option) => migrateNodeMetadata(option, { label: option.label }, schema.defaultLocale, customMigrator)
+        (option) => migrateNodeMetadata(
+          option,
+          { label: option.label },
+          (locale, property) => ({
+            locale,
+            defaultLocale,
+            path: `fields.${field.id}.options.${option.id}.${property}`,
+            property,
+            nodeKind: "option",
+            nodeId: option.id,
+            parentId: field.id
+          }),
+          migrator
+        )
       )
     };
   });
@@ -2517,8 +2634,15 @@ var migrateSchemaTranslationMetadata = (schema, customMigrator) => {
         ...page.title === void 0 ? {} : { title: page.title },
         ...page.description === void 0 ? {} : { description: page.description }
       },
-      schema.defaultLocale,
-      customMigrator
+      (locale, property) => ({
+        locale,
+        defaultLocale,
+        path: `pages.${page.id}.${property}`,
+        property,
+        nodeKind: "page",
+        nodeId: page.id
+      }),
+      migrator
     )
   );
   return {
@@ -2561,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,
@@ -2570,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,
@@ -2581,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 {
@@ -2601,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)
@@ -2644,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.`);
@@ -2653,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()
@@ -2664,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
     ])
   ];
@@ -3001,6 +3133,7 @@ function assertVersionMutable(status) {
   matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   migrateSchemaTranslationMetadata,
+  normalizeLocale,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,
   populateSchemaTranslations,