@molecule/api-ai-translation-molecule

molecule.dev hosted translation provider.

Implements the @molecule/api-ai-translation contract by calling molecule.dev's hosted translation service with a project API key — no DeepL/Google account needed. molecule.dev translates with a language model (every language an app is likely to ship), keeps protect placeholders intact, and meters the characters to the project the key belongs to.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider, requireProvider } from '@molecule/api-ai-translation'
import { provider } from '@molecule/api-ai-translation-molecule'

setProvider(provider) // reads MOLECULE_API_KEY on first use

const { translations } = await requireProvider().translate({
  text: ['{{count}} items in your cart', 'Checkout'],
  targetLang: 'de',
  protect: ['{{count}}'],
  context: 'Labels in an online store',
})

Type

provider

Installation

npm install @molecule/api-ai-translation-molecule @molecule/api-ai-translation @molecule/api-secrets

API

Interfaces

MoleculeTranslationConfig

Options for createProvider. Every field falls back to an env var, so the zero-argument provider export works from .env alone.

interface MoleculeTranslationConfig {
  /**
   * The molecule project API key (`mk_…`), or the sandbox token molecule.dev
   * writes for in-IDE apps (`mbk_…`). Defaults to `MOLECULE_API_KEY`.
   */
  apiKey?: string
  /**
   * The hosted services base URL, without a trailing slash. Defaults to
   * `MOLECULE_SERVICES_URL`, then `https://api.molecule.dev/api/v1/services`.
   */
  servicesUrl?: string
  /** Per-request timeout in milliseconds. Default 120000 (a large batch takes a while). */
  timeoutMs?: number
}

Functions

createProvider(config)

Creates a molecule.dev hosted translation provider.

function createProvider(config?: MoleculeTranslationConfig): AITranslationProvider

• config — API key, services URL and timeout; each falls back to env.

Returns: An AITranslationProvider backed by molecule.dev.

Constants

provider

The provider implementation.

const provider: AITranslationProvider

aiTranslationMoleculeSecretDefinitions

Secret definitions required by the molecule.dev hosted translation bond.

const aiTranslationMoleculeSecretDefinitions: SecretDefinition[]

Core Interface

Implements @molecule/api-ai-translation interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-ai-translation'
import { provider } from '@molecule/api-ai-translation-molecule'

export function setupAiTranslationMolecule(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai-translation >=1.1.0
• @molecule/api-secrets ^1.0.1

Environment Variables

• MOLECULE_API_KEY (required) — molecule.dev project API key
  • Setup: Create one for your project with mlcl apikey create --project <id> --name <name> (keys start with mk_).
  • Get it here: https://www.molecule.dev
  • Example: mk_...

Runtime Dependencies

• @molecule/api-ai-translation

• @molecule/api-secrets

• Config: MOLECULE_API_KEY (required — a project key from mlcl apikey create; in a molecule.dev sandbox the platform writes it for you) and MOLECULE_SERVICES_URL (optional, default https://api.molecule.dev/api/v1/services; https required — plain-http is refused unless the host is loopback or a private-network endpoint (RFC 1918 / *.docker.internal, e.g. the sandbox gateway host.docker.internal)).

• Server-side only. The key bills your project — never ship it to a browser; call this from your API and rate-limit any route that translates user input.

• Per call: at most 200 texts, 5,000 characters each, 50,000 in total. Split larger jobs. A 413 names the limit that was hit.

• Pass placeholders in protect — and still check every result holds them before storing it; a model can drop one.

• Only text, targetLang, sourceLang, protect and context are sent; formality, glossaryId, tagHandling and modelType are not supported.

• Errors throw an Error with the HTTP status and molecule's errorKey: 401/403 (bad or under-scoped key — the key needs scope broker or broker:translation), 402 (the project's budget is used up), 429 (rate limited — retry later), 502 (the translation model failed — retry).

• Molecule's other translation bonds (-deepl, -google, -llm) take the same calls, so switching away is one import.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip. The sandbox has a live AI provider, so translations run for real; output is non-deterministic, so assert on the resulting LANGUAGE/meaning, never an exact string:

• Translating real text to a target language through the UI returns text ACTUALLY in that language — English→Spanish produces recognizably Spanish, not the original echoed back or left in English.
• Switching the target language (from the picker populated by getSupportedLanguages('target')) changes the output language for the same input — the same source re-translates into the newly chosen language.
• With sourceLang omitted the provider auto-detects: a known-language input comes back with the correct detectedSourceLang, and if the UI shows a detected-language label it names the right one.
• Text already in the target language is left sensible — unchanged or a valid paraphrase, never mangled, doubled, or emptied.
• Empty or untranslatable input (whitespace, emoji, a bare code snippet) is handled gracefully — a clear UI state, nothing crashes.
• A provider failure (bad key, quota exhausted, network drop) surfaces a visible error in the UI, not an unhandled 500 or a silently blank result.
• The translate call runs server-side only — the provider key never reaches the browser (check the network panel: no key in any request).