Skip to Content

AI translation suggestions

Validate optional AI-generated translation suggestions without automatically modifying catalogs.

@puzzle-ui/i18n/ai exposes a provider contract rather than a built-in model or API client. Call it from a trusted server environment:

import { suggestTranslation } from "@puzzle-ui/i18n/ai";

const suggestion = await suggestTranslation(provider, {
  sourceLocale: "en",
  targetLocale: "nl",
  key: "welcome",
  sourceMessage: "Hello {name}",
  context: "A friendly greeting",
});

The helper validates the candidate ICU syntax and requires the same placeholder names as the source. It returns approved: false and never writes to a catalog. Provider errors are surfaced as TranslationSuggestionError with a stable code; the original provider error remains available as cause. Wrap a provider with createRateLimitedSuggestionProvider to bound concurrent requests and optionally space them apart. createAuthorizedSuggestionProvider runs a server-owned authorization callback for each request and fails closed before calling the provider if authorization is denied or fails.

For approval and change history, use a TranslationReviewStore implementation:

import {
  createTranslationReviewWorkflow,
} from "@puzzle-ui/i18n/ai";

const workflow = createTranslationReviewWorkflow(provider, reviewStore, {
  quality: {
    terminology: [{ source: "Save", target: "Enregistrer", weight: 2 }],
    checks: [{
      id: "context-fit",
      evaluate: ({ request, suggestion }) =>
        request.context?.includes("button") && suggestion ? 100 : 0,
    }],
  },
});
const pending = await workflow.suggest({
  sourceLocale: "en",
  targetLocale: "nl",
  key: "welcome",
  sourceMessage: "Hello {name}",
});

// Authenticate and authorize the reviewer in your application first.
const result = await workflow.approve(pending.id, reviewer.id);

Approval applies a suggestion only when its base translation revision is still current. The store must enforce this comparison atomically; the included createInMemoryTranslationReviewStore is for tests and demonstrations, not durable production use. Persist the suggestion and audit trail in a protected database for production, and authorize reviewers before calling approve or reject. createTransactionalTranslationReviewStore adapts a database-neutral transaction contract for atomic suggestion writes, translation compare-and-set, and audit append; provide an implementation backed by your application's transactional database.

Quality rules produce a weighted report on the suggestion. Terminology checks look for configured source/target terms; custom checks can use contextual information and return a score or a score with a message. Quality is advisory: it does not approve or apply suggestions automatically.

Call the provider only from a trusted server environment. Keep credentials and source content out of client bundles and routine logs; the package does not provide an AI service or application identity system. The authorization callback and reviewer identity must be derived and enforced by the host application. Provider calls throw a server-only error in browser runtimes as a guard against accidental client usage.