@verbx/localize-core

The frozen contracts for VerbX Localize. Zero runtime dependencies.

Everything else in the platform — the runtime engine, every framework adapter, the CLI, the scanner, the typed client, and the backend's mirrored Python models — depends on these types and on nothing else of each other's. That is what lets the cloud AI chain and the on-device ONNX chain be swapped without redesigning anything above them (PRD §12).

Interfaces frozen at INTERFACE_VERSION 1.4.0 — the SDK and the backend advance in step.

You do not install this directly — every VerbX Localize package depends on it. It is documented here for people building a new adapter.

What's in here

| Module | Doc 03 § | Contents | |---|---|---| | sdk.ts | §1 | VerbXProviderConfig, TranslateOptions, VerbXClient | | runtime.ts | §2 | RuntimeEngine, TranslateRequestItem, TranslationResult, runtime events | | context.ts | §3 | ContextDescriptor, ContextCollector, DetectHint | | translation-service.ts | §4 | TranslationService — the single cloud-vs-ONNX seam | | cache.ts | §5 | CacheProvider, CacheKeyParts, CacheEntry, BundleLoader | | translation-memory.ts | §6 | TranslationMemory (TS mirror of the server-side contract) | | plugin.ts | §7 | VerbXPlugin, VerbXRegistry — framework / capability / provider / storage | | management.ts | §8 | Runtime + management API shapes, ManagementClient | | cli.ts | §9 | CliCommand, VerbXConfig |

Plus the shared pure helpers every layer must agree on:

| Module | Why it lives in core | |---|---| | keys.ts | hashString / buildCacheKey / buildContextKey — the SDK, the CLI-built bundle, and the backend's TM must derive identical keys or nothing is reusable. FNV-1a is pinned by a golden test. | | redact.ts | redactContext — the single gate app-derived context passes through before egress (decision #4, R4). | | discovery.ts | isTranslatable / rejectionReason — the false-positive filter shared by the runtime and the scanner (decision #6, R2). | | interpolate.ts | interpolate / placeholderNames / selectPluralCategory / hasIcuSyntax — values are substituted on-device and never sent (03 §2.4, decision #7). | | constants.ts | The resolved decision numbers (batch window, context caps, usage taxonomy, free-tier caps) in one reviewable place. |

Contract tests

import { describeTranslationServiceContract } from "@verbx/localize-core/testing";

describeTranslationServiceContract("cloud", {
  create: () => new CloudTranslationService(config),
  supportedLocale: "es",
  unsupportedLocale: "xx-ZZ",
  privacyMode: "cloud",
});

Every implementation of TranslationService, CacheProvider, or ContextCollector runs the shared suite. This is what makes "swap cloud for ONNX" a safe operation rather than a hope (doc 09 §5). vitest is an optional peer dependency used only by the ./testing entry — the main entry imports nothing.

Changing these interfaces

Additive changes within a major are allowed; removals and signature changes are not. A breaking change means bumping INTERFACE_VERSION's major and a deprecation window.

Docs

localize.verbxeco.com

License

Proprietary. See LICENSE.md and the VerbX terms of service.