Tres Marías Language

Versioned vocabulary and serializable message contracts for TPAA. Shared by products, not owned by Indigo, Capibara, a UI framework or a provider. Private alpha package; not published to npm. The initial release contains 11 common messages in es-AR/pt-BR.

import { createMessageResolver } from '@tres-marias/language/paraglide';
import { pack, release, ref } from '@tres-marias/language/catalog';

const messages = createMessageResolver({
  locale: 'es-AR',
  bindings: [{ pack, expected: release }],
});
messages.resolve(ref('surface.collection.selected', { count: 2 }));

Production assemblies pin expected to their admitted catalog manifest. Passing a pack's own release above is a local assembly example, NOT authentication of downloaded code. Installation pins tarball integrity as well. No network or dynamic evaluation occurs during message resolution. Paraglide and its plugin are exact build dependencies; the plugin loads from node_modules, not a runtime CDN. Compiler version 2.18.1 matches the existing Manteca installation. Generated JS and declarations ship in the package.

Ownership and boundaries

• ./contracts: MessageRef, typed parameters, catalog release and resolver port. No Paraglide runtime/DOM/provider/DB dependency. Controller returns stable codes, normalized facts and message references, never translated strings as command IDs.
• ./catalog: common vocabulary, generated typed reference builder and compiled pack.
• ./paraglide: validates exact bindings, locale support, unique keys and parameters, then invokes precompiled functions. This is an adapter, not another translation engine.
• Domain/app packages own domain messages. A fiscal package publishes the SAME messages in Capibara standalone and its AgentOS App. Do not put fiscal or AgentOS-specific copy into the common catalog or create parallel copies per channel.
• DS components receive resolved strings. Their geometry and approved copy stay intact. Locale never determines permissions, status, currency, timezone or effects.
• Messages authored by users/agents (.msg), file contents, notes and object titles are content, not translation keys. Render them as escaped text; this package returns plain strings, not trusted HTML. No HTML interpolation is authorized by a message catalog.

One immutable resolver per request/render; no module-global mutable locale. For a language change create the new resolver from the same pinned bindings. Manteca's legacy es/pt aliases must be supplied explicitly as {es:'es-AR',pt:'pt-BR'} by its consumer; other regional variants are not silently mapped. All bound packs must support the requested locale. Unknown keys/parameters/releases/locales fail explicitly.

Domain extension

Domain packages compile their own catalogs using Paraglide. Publish a LanguagePack with release metadata, supported locales and {params, format} for every message. format is a trusted compiled message function accepting explicit locale, not controller JSON. Use createReferences(schema, release) to produce serializable references. The assembly binds common and domain packs together; duplicate keys/catalogs are errors. The reference's optional catalog field is omitted ONLY by legacy producers whose assembly already pins the owning catalog. New reference builders always include it.

Use complete messages, not verb+noun concatenation. Parameter schemas preserve numbers for plural selection. Two identical phrases can have different meaning and should not be deduplicated blindly. Keys are stable semantic identities: do not rename them merely because wording or component placement changes. User-visible errors, aria names, empty states, confirmations and outcomes are part of coverage.

Versioning and migration

Catalog releases are immutable: id/version/digest. Key removal, changed parameter types or changed meaning requires a breaking release and explicit consumer migration. Copy corrections still create a new version/digest, never alter an installed artifact. Old history retains its catalog binding; resolving it requires that compatible release, not whichever happens to be latest. Digest identifies content, not permission to load it.

Extract existing strings without editorial changes; compare rendered text and behavior, then remove the old path. The framework's legacy regex catalog path remains explicitly deprecated until consumers migrate. A provided resolver's failure MUST NOT fall back to it. Do not strip old product functionality to make a migration pass.

Initial tests cover common messages, types, plural inputs, concurrent locales, serialized refs, collisions, stale release/digest, missing/extra/inherited/nonfinite parameters. Full Indigo/Capibara migration and visual acceptance are separate gates. They are NOT claimed by this package. New common Portuguese translations are technical candidates, not a claim of owner editorial approval.

Reproduce

Node 24: npm ci --ignore-scripts; npm run verify; npm pack. Sources: catalog.json, messages/*.json. scripts/build.mjs checks locale/key/input coverage, compiles with Paraglide and generates reference types/catalog bindings. Generated files are never edited. Lockfile pins build dependencies; tests do not use provider credentials or external inference. npm pack is local, not registry publish.

License

Apache-2.0 — see LICENSE at the repository root. "Tres Marías" and its logos are trademarks, not covered by this code license — see TRADEMARKS.md.