@form-engine-ts/core 2.1.1 → 2.3.0

package/README.md

@@ -40,8 +40,15 @@ round-trips. `completionMessage` is localized with the rest of the form text.
 
 `transformFieldType` changes a question's type without discarding source text, translations, conditions, or extension
 metadata. `validateFormSchema(schema, { policy })` applies the framework-independent `FormPolicy`, including field,
-option, text, serialized-byte, allowed-type, and required-locale constraints. Required locales cover every source text
-that exists on the form, its fields, options, and pages.
+option, text, serialized-byte, allowed-type, and locale constraints. `allowedLocales` constrains the default and supported
+locales, `maxLocales` limits their unique total, and contradictory required/allowed locale policies are reported.
+Required locales cover every source text that exists on the form, its fields, options, and pages.
+
+`collectSchemaLocales(schema)` scans registrations plus every form/page/field/option `translations` and
+`translationMetadata` key. Validation reports unregistered translation locales and applies `allowedLocales` and
+`maxLocales` to the complete collected set. `sanitizeSchema` purges unregistered locale content. Pass
+`{ policy: { allowedLocales, maxLocales } }` to `populateSchemaTranslations` to reject inadmissible targets before the
+translation adapter runs.
 
 Translation callbacks receive `nodeMetadata` and `existingTranslationMetadata` separately. The deprecated `metadata`
 slot property remains an alias for `nodeMetadata` during migration.

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   calculateFieldVisibility: () => calculateFieldVisibility,
   calculateNumericSummary: () => calculateNumericSummary,
   calculatePageVisibility: () => calculatePageVisibility,
+  collectSchemaLocales: () => collectSchemaLocales,
   createSubmission: () => createSubmission,
   dispatchWebhook: () => dispatchWebhook,
   escapeCsvCell: () => escapeCsvCell,
@@ -46,7 +47,95 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/policy.ts
+function collectRecordKeys(value, path, pathsByLocale) {
+  for (const locale of Object.keys(value ?? {})) {
+    const paths = pathsByLocale.get(locale) ?? [];
+    paths.push(`${path}.${locale}`);
+    pathsByLocale.set(locale, paths);
+  }
+}
+function collectSchemaLocales(schema) {
+  const pathsByLocale = /* @__PURE__ */ new Map();
+  collectRecordKeys(schema.translations, "translations", pathsByLocale);
+  collectRecordKeys(schema.translationMetadata, "translationMetadata", pathsByLocale);
+  schema.fields.forEach((field, fieldIndex) => {
+    collectRecordKeys(field.translations, `fields[${fieldIndex}].translations`, pathsByLocale);
+    collectRecordKeys(field.translationMetadata, `fields[${fieldIndex}].translationMetadata`, pathsByLocale);
+    if (!("options" in field)) return;
+    field.options.forEach((option, optionIndex) => {
+      collectRecordKeys(
+        option.translations,
+        `fields[${fieldIndex}].options[${optionIndex}].translations`,
+        pathsByLocale
+      );
+      collectRecordKeys(
+        option.translationMetadata,
+        `fields[${fieldIndex}].options[${optionIndex}].translationMetadata`,
+        pathsByLocale
+      );
+    });
+  });
+  schema.pages?.forEach((page, pageIndex) => {
+    collectRecordKeys(page.translations, `pages[${pageIndex}].translations`, pathsByLocale);
+    collectRecordKeys(page.translationMetadata, `pages[${pageIndex}].translationMetadata`, pathsByLocale);
+  });
+  const translationLocales = new Set(pathsByLocale.keys());
+  const allUniqueLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? [],
+    ...translationLocales
+  ]);
+  return {
+    ...schema.defaultLocale === void 0 ? {} : { defaultLocale: schema.defaultLocale },
+    supportedLocales: schema.supportedLocales ?? [],
+    translationLocales,
+    allUniqueLocales,
+    translationLocalePaths: pathsByLocale
+  };
+}
+
 // src/sanitization.ts
+function registeredEntries(value, registeredLocales) {
+  if (value === void 0) return void 0;
+  const entries = Object.entries(value).filter(([locale]) => registeredLocales.has(locale));
+  return entries.length === 0 ? void 0 : Object.fromEntries(entries);
+}
+function sanitizeNodeLocales(node, registeredLocales) {
+  const { translationMetadata: _translationMetadata, ...base } = node;
+  const translationMetadata = registeredEntries(node.translationMetadata, registeredLocales);
+  return {
+    ...base,
+    ...translationMetadata === void 0 ? {} : { translationMetadata }
+  };
+}
+function sanitizeOptionLocales(option, registeredLocales) {
+  const { translations: _translations, ...base } = sanitizeNodeLocales(option, registeredLocales);
+  const translations = registeredEntries(option.translations, registeredLocales);
+  return { ...base, ...translations === void 0 ? {} : { translations } };
+}
+function sanitizeFieldLocales(field, registeredLocales) {
+  const localizedNode = sanitizeNodeLocales(field, registeredLocales);
+  const { translations: _translations, ...base } = localizedNode;
+  const translations = registeredEntries(field.translations, registeredLocales);
+  const localized = {
+    ...base,
+    ...translations === void 0 ? {} : { translations }
+  };
+  if (!("options" in localizedNode)) return localized;
+  const { translations: _choiceTranslations, ...choiceBase } = localizedNode;
+  return {
+    ...choiceBase,
+    ...translations === void 0 ? {} : { translations },
+    options: localizedNode.options.map((option) => sanitizeOptionLocales(option, registeredLocales))
+  };
+}
+function sanitizePageLocales(page, registeredLocales) {
+  const localizedNode = sanitizeNodeLocales(page, registeredLocales);
+  const { translations: _translations, ...base } = localizedNode;
+  const translations = registeredEntries(page.translations, registeredLocales);
+  return { ...base, ...translations === void 0 ? {} : { translations } };
+}
 function cyclicQuestionIds(fields) {
   const firstById = /* @__PURE__ */ new Map();
   for (const field of fields) {
@@ -133,8 +222,13 @@ function validateSchemaStructure(schema) {
 }
 function sanitizeSchema(schema) {
   const existingQuestionIds = new Set(schema.fields.map((field) => field.id));
+  const registeredLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? []
+  ]);
   const cyclic = cyclicQuestionIds(schema.fields);
-  const sanitizedFields = schema.fields.map((field) => {
+  const sanitizedFields = schema.fields.map((sourceField) => {
+    const field = sanitizeFieldLocales(sourceField, registeredLocales);
     const sourceId = field.displayCondition?.questionId;
     if (sourceId === void 0 || existingQuestionIds.has(sourceId) && sourceId !== field.id && !cyclic.has(field.id)) {
       return field;
@@ -142,15 +236,19 @@ function sanitizeSchema(schema) {
     const { displayCondition: _displayCondition, ...sanitized } = field;
     return sanitized;
   });
+  const localizedSchema = sanitizeNodeLocales(schema, registeredLocales);
+  const { translations: _translations, ...schemaWithoutLocaleContent } = localizedSchema;
+  const translations = registeredEntries(schema.translations, registeredLocales);
   const base = {
-    ...schema,
+    ...schemaWithoutLocaleContent,
+    ...translations === void 0 ? {} : { translations },
     fields: sanitizedFields
   };
   if (schema.pages === void 0) return base;
   const assigned = /* @__PURE__ */ new Set();
-  const pages = schema.pages.map((page) => ({
-    ...page,
-    questionIds: page.questionIds.filter((id) => {
+  const pages = schema.pages.map((sourcePage) => ({
+    ...sanitizePageLocales(sourcePage, registeredLocales),
+    questionIds: sourcePage.questionIds.filter((id) => {
       if (!existingQuestionIds.has(id) || assigned.has(id)) return false;
       assigned.add(id);
       return true;
@@ -554,6 +652,52 @@ function validatePolicy(schema, policy, issues) {
       }
     }
   }
+  const collectedLocales = collectSchemaLocales(schema);
+  const registeredLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? []
+  ]);
+  for (const locale of collectedLocales.translationLocales) {
+    if (registeredLocales.has(locale)) continue;
+    for (const path of collectedLocales.translationLocalePaths.get(locale) ?? []) {
+      issue(
+        issues,
+        path,
+        "unregistered_translation_locale",
+        `Translation locale ${locale} is not registered by defaultLocale or supportedLocales.`
+      );
+    }
+  }
+  if (policy.allowedLocales !== void 0) {
+    const pathsByLocale = /* @__PURE__ */ new Map();
+    if (schema.defaultLocale !== void 0) pathsByLocale.set(schema.defaultLocale, ["defaultLocale"]);
+    schema.supportedLocales?.forEach((locale, index) => {
+      pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], `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)) {
+        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)) {
+        issue(
+          issues,
+          "policy.requiredLocales",
+          "required_locale_not_allowed",
+          `Required locale ${locale} is not included in allowedLocales.`
+        );
+      }
+    }
+  }
+  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);
   if (policy.maxSchemaBytes !== void 0) {
     try {
@@ -1454,6 +1598,18 @@ 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 collectedLocales = collectSchemaLocales(schema);
+  const disallowedLocale = [...collectedLocales.allUniqueLocales, ...locales].find(
+    (locale) => allowedLocales !== void 0 && !allowedLocales.includes(locale)
+  );
+  if (disallowedLocale !== void 0) {
+    throw new RangeError(`Translation locale ${disallowedLocale} is not allowed by the form policy.`);
+  }
+  const projectedLocales = /* @__PURE__ */ new Set([...collectedLocales.allUniqueLocales, ...locales]);
+  if (options.policy?.maxLocales !== void 0 && projectedLocales.size > options.policy.maxLocales) {
+    throw new RangeError(`At most ${options.policy.maxLocales} locales are allowed by the form policy.`);
+  }
   const updatedSlots = [];
   const skippedSlots = [];
   let result = schema;
@@ -1511,6 +1667,7 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
   calculateFieldVisibility,
   calculateNumericSummary,
   calculatePageVisibility,
+  collectSchemaLocales,
   createSubmission,
   dispatchWebhook,
   escapeCsvCell,

package/dist/index.d.cts

@@ -4,6 +4,8 @@ interface FormPolicy {
     readonly maxFields?: number;
     readonly maxOptionsPerField?: number;
     readonly requiredLocales?: readonly string[];
+    readonly allowedLocales?: readonly string[];
+    readonly maxLocales?: number;
     readonly maxTextLength?: number;
     readonly maxSchemaBytes?: number;
 }
@@ -266,6 +268,17 @@ declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig,
  */
 declare function transformFieldType(field: FormField, nextType: QuestionType): FormField;
 
+interface CollectedLocales {
+    readonly defaultLocale?: string;
+    readonly supportedLocales: readonly string[];
+    readonly translationLocales: ReadonlySet<string>;
+    readonly allUniqueLocales: ReadonlySet<string>;
+    /** Every translation or translation-metadata locale and the schema paths where it occurs. */
+    readonly translationLocalePaths: ReadonlyMap<string, readonly string[]>;
+}
+/** Collects locale registrations and every locale key used by translations or translation metadata. */
+declare function collectSchemaLocales(schema: FormSchema): CollectedLocales;
+
 type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
 interface SchemaStructureIssue {
     readonly type: SchemaStructureIssueType;
@@ -305,6 +318,8 @@ interface PopulateTranslationOptions {
     readonly overwrite?: "missing-only" | "all";
     readonly shouldOverwrite?: (slot: TranslationSlot) => boolean;
     readonly createMetadata?: (slot: TranslationSlot, translatedText: string) => Readonly<Record<string, JsonValue>>;
+    /** Applies locale admission and count limits before the adapter is called. */
+    readonly policy?: Pick<FormPolicy, "allowedLocales" | "maxLocales">;
 }
 interface TranslationReport {
     readonly updatedSlots: readonly TranslationSlot[];
@@ -326,4 +341,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 AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, collectSchemaLocales, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -4,6 +4,8 @@ interface FormPolicy {
     readonly maxFields?: number;
     readonly maxOptionsPerField?: number;
     readonly requiredLocales?: readonly string[];
+    readonly allowedLocales?: readonly string[];
+    readonly maxLocales?: number;
     readonly maxTextLength?: number;
     readonly maxSchemaBytes?: number;
 }
@@ -266,6 +268,17 @@ declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig,
  */
 declare function transformFieldType(field: FormField, nextType: QuestionType): FormField;
 
+interface CollectedLocales {
+    readonly defaultLocale?: string;
+    readonly supportedLocales: readonly string[];
+    readonly translationLocales: ReadonlySet<string>;
+    readonly allUniqueLocales: ReadonlySet<string>;
+    /** Every translation or translation-metadata locale and the schema paths where it occurs. */
+    readonly translationLocalePaths: ReadonlyMap<string, readonly string[]>;
+}
+/** Collects locale registrations and every locale key used by translations or translation metadata. */
+declare function collectSchemaLocales(schema: FormSchema): CollectedLocales;
+
 type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
 interface SchemaStructureIssue {
     readonly type: SchemaStructureIssueType;
@@ -305,6 +318,8 @@ interface PopulateTranslationOptions {
     readonly overwrite?: "missing-only" | "all";
     readonly shouldOverwrite?: (slot: TranslationSlot) => boolean;
     readonly createMetadata?: (slot: TranslationSlot, translatedText: string) => Readonly<Record<string, JsonValue>>;
+    /** Applies locale admission and count limits before the adapter is called. */
+    readonly policy?: Pick<FormPolicy, "allowedLocales" | "maxLocales">;
 }
 interface TranslationReport {
     readonly updatedSlots: readonly TranslationSlot[];
@@ -326,4 +341,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 AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, collectSchemaLocales, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -1,4 +1,92 @@
+// src/policy.ts
+function collectRecordKeys(value, path, pathsByLocale) {
+  for (const locale of Object.keys(value ?? {})) {
+    const paths = pathsByLocale.get(locale) ?? [];
+    paths.push(`${path}.${locale}`);
+    pathsByLocale.set(locale, paths);
+  }
+}
+function collectSchemaLocales(schema) {
+  const pathsByLocale = /* @__PURE__ */ new Map();
+  collectRecordKeys(schema.translations, "translations", pathsByLocale);
+  collectRecordKeys(schema.translationMetadata, "translationMetadata", pathsByLocale);
+  schema.fields.forEach((field, fieldIndex) => {
+    collectRecordKeys(field.translations, `fields[${fieldIndex}].translations`, pathsByLocale);
+    collectRecordKeys(field.translationMetadata, `fields[${fieldIndex}].translationMetadata`, pathsByLocale);
+    if (!("options" in field)) return;
+    field.options.forEach((option, optionIndex) => {
+      collectRecordKeys(
+        option.translations,
+        `fields[${fieldIndex}].options[${optionIndex}].translations`,
+        pathsByLocale
+      );
+      collectRecordKeys(
+        option.translationMetadata,
+        `fields[${fieldIndex}].options[${optionIndex}].translationMetadata`,
+        pathsByLocale
+      );
+    });
+  });
+  schema.pages?.forEach((page, pageIndex) => {
+    collectRecordKeys(page.translations, `pages[${pageIndex}].translations`, pathsByLocale);
+    collectRecordKeys(page.translationMetadata, `pages[${pageIndex}].translationMetadata`, pathsByLocale);
+  });
+  const translationLocales = new Set(pathsByLocale.keys());
+  const allUniqueLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? [],
+    ...translationLocales
+  ]);
+  return {
+    ...schema.defaultLocale === void 0 ? {} : { defaultLocale: schema.defaultLocale },
+    supportedLocales: schema.supportedLocales ?? [],
+    translationLocales,
+    allUniqueLocales,
+    translationLocalePaths: pathsByLocale
+  };
+}
+
 // src/sanitization.ts
+function registeredEntries(value, registeredLocales) {
+  if (value === void 0) return void 0;
+  const entries = Object.entries(value).filter(([locale]) => registeredLocales.has(locale));
+  return entries.length === 0 ? void 0 : Object.fromEntries(entries);
+}
+function sanitizeNodeLocales(node, registeredLocales) {
+  const { translationMetadata: _translationMetadata, ...base } = node;
+  const translationMetadata = registeredEntries(node.translationMetadata, registeredLocales);
+  return {
+    ...base,
+    ...translationMetadata === void 0 ? {} : { translationMetadata }
+  };
+}
+function sanitizeOptionLocales(option, registeredLocales) {
+  const { translations: _translations, ...base } = sanitizeNodeLocales(option, registeredLocales);
+  const translations = registeredEntries(option.translations, registeredLocales);
+  return { ...base, ...translations === void 0 ? {} : { translations } };
+}
+function sanitizeFieldLocales(field, registeredLocales) {
+  const localizedNode = sanitizeNodeLocales(field, registeredLocales);
+  const { translations: _translations, ...base } = localizedNode;
+  const translations = registeredEntries(field.translations, registeredLocales);
+  const localized = {
+    ...base,
+    ...translations === void 0 ? {} : { translations }
+  };
+  if (!("options" in localizedNode)) return localized;
+  const { translations: _choiceTranslations, ...choiceBase } = localizedNode;
+  return {
+    ...choiceBase,
+    ...translations === void 0 ? {} : { translations },
+    options: localizedNode.options.map((option) => sanitizeOptionLocales(option, registeredLocales))
+  };
+}
+function sanitizePageLocales(page, registeredLocales) {
+  const localizedNode = sanitizeNodeLocales(page, registeredLocales);
+  const { translations: _translations, ...base } = localizedNode;
+  const translations = registeredEntries(page.translations, registeredLocales);
+  return { ...base, ...translations === void 0 ? {} : { translations } };
+}
 function cyclicQuestionIds(fields) {
   const firstById = /* @__PURE__ */ new Map();
   for (const field of fields) {
@@ -85,8 +173,13 @@ function validateSchemaStructure(schema) {
 }
 function sanitizeSchema(schema) {
   const existingQuestionIds = new Set(schema.fields.map((field) => field.id));
+  const registeredLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? []
+  ]);
   const cyclic = cyclicQuestionIds(schema.fields);
-  const sanitizedFields = schema.fields.map((field) => {
+  const sanitizedFields = schema.fields.map((sourceField) => {
+    const field = sanitizeFieldLocales(sourceField, registeredLocales);
     const sourceId = field.displayCondition?.questionId;
     if (sourceId === void 0 || existingQuestionIds.has(sourceId) && sourceId !== field.id && !cyclic.has(field.id)) {
       return field;
@@ -94,15 +187,19 @@ function sanitizeSchema(schema) {
     const { displayCondition: _displayCondition, ...sanitized } = field;
     return sanitized;
   });
+  const localizedSchema = sanitizeNodeLocales(schema, registeredLocales);
+  const { translations: _translations, ...schemaWithoutLocaleContent } = localizedSchema;
+  const translations = registeredEntries(schema.translations, registeredLocales);
   const base = {
-    ...schema,
+    ...schemaWithoutLocaleContent,
+    ...translations === void 0 ? {} : { translations },
     fields: sanitizedFields
   };
   if (schema.pages === void 0) return base;
   const assigned = /* @__PURE__ */ new Set();
-  const pages = schema.pages.map((page) => ({
-    ...page,
-    questionIds: page.questionIds.filter((id) => {
+  const pages = schema.pages.map((sourcePage) => ({
+    ...sanitizePageLocales(sourcePage, registeredLocales),
+    questionIds: sourcePage.questionIds.filter((id) => {
       if (!existingQuestionIds.has(id) || assigned.has(id)) return false;
       assigned.add(id);
       return true;
@@ -506,6 +603,52 @@ function validatePolicy(schema, policy, issues) {
       }
     }
   }
+  const collectedLocales = collectSchemaLocales(schema);
+  const registeredLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? []
+  ]);
+  for (const locale of collectedLocales.translationLocales) {
+    if (registeredLocales.has(locale)) continue;
+    for (const path of collectedLocales.translationLocalePaths.get(locale) ?? []) {
+      issue(
+        issues,
+        path,
+        "unregistered_translation_locale",
+        `Translation locale ${locale} is not registered by defaultLocale or supportedLocales.`
+      );
+    }
+  }
+  if (policy.allowedLocales !== void 0) {
+    const pathsByLocale = /* @__PURE__ */ new Map();
+    if (schema.defaultLocale !== void 0) pathsByLocale.set(schema.defaultLocale, ["defaultLocale"]);
+    schema.supportedLocales?.forEach((locale, index) => {
+      pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], `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)) {
+        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)) {
+        issue(
+          issues,
+          "policy.requiredLocales",
+          "required_locale_not_allowed",
+          `Required locale ${locale} is not included in allowedLocales.`
+        );
+      }
+    }
+  }
+  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);
   if (policy.maxSchemaBytes !== void 0) {
     try {
@@ -1406,6 +1549,18 @@ 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 collectedLocales = collectSchemaLocales(schema);
+  const disallowedLocale = [...collectedLocales.allUniqueLocales, ...locales].find(
+    (locale) => allowedLocales !== void 0 && !allowedLocales.includes(locale)
+  );
+  if (disallowedLocale !== void 0) {
+    throw new RangeError(`Translation locale ${disallowedLocale} is not allowed by the form policy.`);
+  }
+  const projectedLocales = /* @__PURE__ */ new Set([...collectedLocales.allUniqueLocales, ...locales]);
+  if (options.policy?.maxLocales !== void 0 && projectedLocales.size > options.policy.maxLocales) {
+    throw new RangeError(`At most ${options.policy.maxLocales} locales are allowed by the form policy.`);
+  }
   const updatedSlots = [];
   const skippedSlots = [];
   let result = schema;
@@ -1462,6 +1617,7 @@ export {
   calculateFieldVisibility,
   calculateNumericSummary,
   calculatePageVisibility,
+  collectSchemaLocales,
   createSubmission,
   dispatchWebhook,
   escapeCsvCell,

package/package.json

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