Trox
Trox is a source-extraction localization system for Rust, TypeScript/TSX, and
static RON data. Developers write complete English messages beside their use
sites; Trox extracts them, expands locale-specific grammar into flat CSV rows,
and builds deterministic bundles for Rust and TypeScript runtimes. Messages
remain immutable, locale-independent LocalizedString values until an
explicit Localizer renders them at the presentation boundary, avoiding text
fragments, translator-authored programs, implicit locale state, and runtime
morphology.
Here is a Rust message with interpolation, exact-zero wording, and cardinal plural selection:
use *;
let value = cards_remaining;
let text = localizer.resolve;
assert_eq!;
Install and start
Trox requires Rust 1.89 or newer. Add the runtime library to an application and install the source-extraction CLI separately:
The trox-cli package installs a binary named trox. Its Rust modules are
implementation details of the executable and are not a supported library API.
Create a trox.ron at the project root:
(
source_locale: "en-US",
terms: "terms.ron",
source_bundle: "generated/en-US.trox.json",
source_report: "generated/en-US.csv",
sources: [(language: Rust, include: ["src/**/*.rs"])],
locales: {},
term_forms: {},
)
Create an empty terms.ron containing {}, author messages with the Rust API
below, and validate the project:
Add a locale's profile, CSV, and bundle paths to trox.ron, then create its
initial files with trox locale init LOCALE. The full configuration contract
is documented under Project configuration.
Support policy
troxandtrox-clisupport Rust 1.89 and newer.- The Rust runtime is tested on Linux, macOS, and Windows.
- The
troxcommand is tested on Linux, macOS, and Windows. On non-Unix platforms its optional benchmark reports no peak-memory measurement. - The
troxlibrary follows Cargo semantic versioning. Thetrox-clipackage exposes only thetroxexecutable; its internal Rust modules are not API. - Bundle and serialized-value compatibility is versioned explicitly by their embedded format versions and validated when data is loaded.
Capabilities and boundaries
Trox provides:
- Inline complete English messages.
- Named placeholders in Rust and TypeScript.
- Exact, cardinal, ordinal, and semantic selection.
- RON message and typed-template extraction.
- Locale-specific row expansion.
- Non-destructive CSV synchronization.
- Deterministic JSON bundles.
- Compatible Rust and TypeScript runtimes.
- Canonical serialization of unresolved messages.
- Visible source fallback with diagnostics.
Trox does not provide:
- String-fragment composition.
- Translator-authored selector syntax.
- A general expression language.
- Automatic articles, case, or morphology.
- Arbitrary nested localized messages.
- Implicit global locale discovery.
- Runtime filesystem or network access.
- Currency, date, unit, or list formatting.
- Interpreted HTML or rich-text markup.
Design rules:
- Every selector leaf is a complete message.
- Translation files contain text, not programs.
- Terms are sparse, shallow, and explicit.
- Application code owns semantic inputs.
- Locale profiles own locale-private grammar.
- Deterministic tooling is authoritative.
Repository
.
├── crates/
│ ├── trox/ Rust API, bundles, wire values, resolver
│ └── trox-cli/ `trox` binary, scanners, CSV workflow, bundle builder
├── packages/
│ └── trox/ `@trox/runtime` TypeScript package
├── crates/trox/tests/fixtures/
│ └── conformance/ canonical cross-language fixtures
├── crates/trox-cli/tests/fixtures/
│ └── quest/ multilingual scenario corpus
├── Cargo.toml Rust workspace
├── package.json npm workspace
└── README.md project documentation
Build and test:
Run the Quest workflow:
Typical application workflow:
- Add
txortxacalls to Rust or TypeScript. - Add flat
Tx(...)records to configured RON data. - Declare runtime grammatical terms only when needed.
- Configure inputs and outputs in
trox.ron. - Run
trox check. - Run
trox extract. - Translate the generated CSV cells.
- Run
trox check --deny warningsin CI. - Run
trox bundle. - Load a source bundle and a target bundle.
- Resolve messages only at the presentation boundary.
Rust syntax
Use the prelude in ordinary authoring modules:
use *;
It exports:
LocalizedString,Localizer, andTermId.tx,txa,meaning,ls, andtx_args!.plural,ordinal, andselect.exact,zero,one,two,few,many, andother.when,otherwise, andTroxSelector.term,indefinite,counted, andopaque.
Static text
Use tx when there are no visible placeholders:
The final argument is required translator context. The result is not a host
String:
let value: LocalizedString = close_label;
let text: String = localizer.resolve;
Intentionally untranslated text
Use ls when runtime text is intentionally safe to display without
translation:
Appropriate uses are:
- Migrations, while existing text is being moved behind
LocalizedStringAPIs. - Raw user input that must be displayed verbatim, such as a player name.
- Tests that need a lightweight
LocalizedStringvalue. - Developer-only surfaces whose text is not translated.
Calling ls asserts that this text does not need translation at this call
site. Do not use it for ordinary user-facing product copy. The extractor
deliberately ignores these calls, and the value resolves to
the supplied text in every locale, including text containing braces. Replace
migration uses with tx or txa as localization work is completed.
Interpolation
Use txa for visible placeholders:
Bind multiple values or map a different expression:
tx_args! evaluates each expression once and converts it into an owned Trox
value. It borrows ordinary input variables by default.
Placeholder names match:
[a-z][a-z0-9]*(?:_[a-z0-9]+)*
Valid:
{name}
{card_name}
{player_2_name}
Rejected:
{0}
{CardName}
{cardName}
{card.name}
{card-name}
{cárd_name}
Rules:
- Names use lowercase ASCII snake case.
- Names are at most 64 ASCII bytes.
- Every visible placeholder has one binding.
- Every binding appears in at least one leaf.
- Target rows may move, repeat, or omit declared placeholders.
- Target rows cannot invent placeholders.
{{and}}render literal braces.
tx
Meaning
Disambiguate identical text with a semantic meaning key:
The meaning key changes message identity. It is not an arbitrary developer
message ID. Extraction includes it at the start of the translator-facing
description as Meaning: <key>.
Cardinal selection
Use plural for locale-dependent cardinal categories:
Selection order:
- Exact integer branch.
- Target locale's CLDR category.
- Matching category branch.
- Required
otherbranch.
Extraction adds target-only categories. A Russian CSV can receive one,
few, many, and other rows from an English source pattern.
The count need not be visible:
tx
Ordinal selection
Plural and ordinal selectors accept nonnegative integers from zero through
2^53 - 1. Fractions, negative values, NaN, and infinities are invalid.
Semantic selection
Define explicit stable keys:
Select complete messages:
Rules:
otherwiseis mandatory.- Keys are stable serialization contracts.
- Keys are unique within the selector.
- Keys use one uniform string or boolean type.
- Generic
selectis not a numeric plural operation. - Ordinary application branching stays in ordinary control flow.
Nested selectors are supported. Every final leaf must still contain the full sentence, including articles, verbs, and punctuation.
Terms and atoms
Map domain values to explicit term IDs:
Request an indefinite form:
txa
indefinite(id) is shorthand for:
term.form
It does not generate a versus an from spelling.
Request a counted form:
txa
counted(id, number) is shorthand for:
term.form.number
The count selects the term surface. The separate placeholder renders the number.
Keep fixed vocabulary inline:
txa
Create a term only when a runtime-selected concept needs a form, count, locale facet, or deliberately centralized proper name.
opaque(value) inserts an atomic localized value. The nested value must be one
text leaf with no arguments or selectors. If it needs grammatical interaction,
model it as a term.
Application-annotated placeholders
Trox translations remain plain text. Translators cannot author HTML, Markdown, component syntax, or other interpreted rich-text markup. Applications can, however, attach opaque metadata to a message's existing named placeholders and use that metadata at the final presentation boundary. This is structured placeholder resolution, not rich-text parsing.
In Rust, annotate a still-lazy LocalizedString without a Localizer:
use *;
let message = txa;
let annotated = message.annotate?;
let parts = localizer.resolve_parts_checked?;
Rust's annotate consumes the cheap-to-clone LocalizedString and accepts any
IntoIterator of (name, metadata) pairs, including arrays, Vec, and owned
BTreeMap values. Duplicate names are rejected instead of being silently
overwritten.
ResolvedLocalizedPart::Literal contains translator-authored literal runs.
ResolvedLocalizedPart::Placeholder contains the semantic placeholder name,
its display-ready localized surface, and Option<&EntityAnnotation>.
The TypeScript lifecycle is equivalent:
const message = txa(
"Gain {offered_card}.",
{ offered_card: opaque(cardName) },
"An effect granting the displayed card.",
);
const annotated = message.annotate({
offered_card: { kind: "entity", entityId: "card-7" },
});
const parts = localizer.resolvePartsChecked(annotated);
Construction, annotation, view-model storage, and application-layer transport
remain locale independent. Only resolve_parts_checked / resolvePartsChecked
and their recovering counterparts require the active Localizer. A target row
may reorder, repeat, or omit declared placeholders: the part sequence follows
that target row exactly, repeated occurrences reference the same annotation,
and omitted occurrences produce no part. Other placeholders resolve normally
with no annotation.
Placeholder value fields are display-ready and include FSI/PDI controls when
the bundle enables bidirectional isolation. Concatenating every part's value
is therefore exactly equal to resolve_checked / resolveChecked (and likewise
for recovering resolution). Scalar text, formatted numbers, terms, and opaque
nested localized values use the same formatting and recovery path as ordinary
string resolution.
Annotations are application data, not localization data. The Rust wrapper owns
its metadata and resolved parts borrow it; the TypeScript wrapper retains the
application values by reference in a shallow-frozen name map. Neither wrapper
implements Trox canonical serialization, and TypeScript JSON.stringify
rejects it explicitly. To cross a process or persistence boundary, serialize
the underlying LocalizedString through its existing canonical wire format and
serialize application metadata through an application-owned protocol, then
validate the names again by calling .annotate(...) on the decoded
LocalizedString. Unknown annotation names fail immediately with
trox.unknown-annotation.
Resolution and rejected forms
let text = localizer.resolve;
let checked = localizer.resolve_checked?;
let json = value.to_canonical_json?;
let decoded = localizer.localized_string_from_json?;
Decoding validates IDs, schemas, selectors, numeric ranges, terms, and limits.
Patterns, branches, arguments, and descriptions must stay inline. Dynamic
patterns, concatenation, missing descriptions, numeric select, concat!, and
arbitrary localized nesting are rejected.
TypeScript syntax
import {
Localizer,
counted,
exact,
few,
indefinite,
assertLocalized,
one,
opaque,
ordinal,
other,
otherwise,
plural,
select,
termId,
two,
tx,
txa,
when,
type LocalizedString,
type TermId,
} from "@trox/runtime";
Static and interpolated messages mirror Rust:
export function closeLabel(): LocalizedString {
return tx(
"Close deck browser",
"Accessible label that closes the deck browser.",
);
}
export function deckLabel(deck_name: string): LocalizedString {
return txa(
"Deck: {deck_name}",
{ deck_name },
"Label followed by the user-defined deck name.",
);
}
Use assertLocalized(rawString) for migrations, verbatim user input, tests, and
developer-only surfaces. It returns a LocalizedString that resolves to
rawString in every locale and is deliberately not extracted:
export function playerName(rawString: string): LocalizedString {
return assertLocalized(rawString);
}
Calling it asserts that the text does not need translation at that call site;
do not use it for ordinary user-facing product copy. Replace migration uses
with tx or txa as localization work is completed.
The argument object must be inline. Spreads and prebuilt objects are not extractable.
Cardinal and ordinal selection:
export function cardsRemaining(
card_count: number,
): LocalizedString {
return txa(
plural(card_count, [
exact(0, "No cards remain."),
one("{card_count} card remains."),
other("{card_count} cards remain."),
]),
{ card_count },
"Status text showing cards remaining in the deck.",
);
}
export function turnPosition(
turn_number: number,
): LocalizedString {
return txa(
ordinal(turn_number, [
one("{turn_number}st turn"),
two("{turn_number}nd turn"),
few("{turn_number}rd turn"),
other("{turn_number}th turn"),
]),
{ turn_number },
"Label for a turn's ordinal position.",
);
}
Semantic selection uses finite literal unions:
type BattleZone = "deck" | "hand" | "void";
export function searchZone(zone: BattleZone): LocalizedString {
return tx(
select(zone, [
when("deck", "Search your deck."),
when("hand", "Search your hand."),
when("void", "Search your void."),
otherwise("Search that zone."),
]),
"Rules text directing the player to search a zone.",
);
}
Map application values to explicit TermId values, then use indefinite,
counted, or opaque exactly as in Rust. Resolve and serialize explicitly:
const text: string = localizer.resolve(value);
const json: string = value.toCanonicalJSON();
const decoded = localizer.localizedStringFromJSON(json);
LocalizedString is not assignable to string. Host interpolation, prebuilt
or spread argument objects, and dynamic descriptions are rejected. Single and
double quotes and template literals without interpolation are accepted. The
scanner handles .ts and .tsx without module resolution.
RON source extraction
RON supports flat static messages and text templates with explicitly typed placeholders:
(
internal_id: "close-deck-browser",
label: Tx("Close deck browser"),
accessibility_label: Tx(
text: "Close deck browser",
description: "Accessible label that closes the browser.",
),
open_state: Tx(
text: "Open",
meaning: "open-state",
description: "Status for a room accepting players.",
),
deck_summary: Tx(
text: "Deck: {deck_name} ({count})",
description: "Deck label followed by its card count.",
placeholders: {
"deck_name": Opaque,
"count": Scalar,
},
),
)
Rules:
- Only
Txrecords are extracted. - Use the short
Tx("text")form for plain static text. - Use the named form when supplying
descriptionormeaning;textis required. description,meaning, andplaceholdersare optional named fields.- Every placeholder in
textmust have exactly one declaration. UseScalarfor text, finite numbers, or booleans;Opaquefor an atomic localized value; andTerm(form: "counted", number: true)for a term with an exact form and number-presence contract. - Generated descriptions include the structural RON field path, such as
Path: CardDefinition.ability_text. Array indexes are omitted so every value in the same field shares a stable path. - Unwrapped strings are ignored.
- Selectors are rejected. RON templates are text patterns only.
- Runtime argument values are not embedded in RON; only their schemas are declared.
{{and}}render visible braces.
Rejected by source extraction:
(
ignored: "Close deck browser",
undeclared: Tx(text: "Deck: {deck_name}"),
extra: Tx(text: "Deck", placeholders: { "deck_name": Opaque }),
)
Configure description defaults for authored data:
ron_description_defaults: {
"data/cards.ron": "Rules text for a game card.",
"data/**/*.ron": "Player-authored game data label.",
},
An explicit description overrides a matching path default. The structural RON field path is appended to either description; when neither is present, the path itself supplies the description.
Serde round-tripping
Application-owned Rust types may contain LocalizedString fields and derive
Serde normally:
let record = Record ;
let encoded = to_string?;
assert_eq!;
let decoded: Record = from_str?;
assert_eq!;
This application-data representation uses the same Tx forms as source
extraction. A value without a meaning serializes as Tx("Foo"); a value with
a meaning uses the named form Tx(text: "Open", meaning: "open-state") so the
meaning survives the round trip. Selectors and already-bound dynamic values
return a RON serialization error.
A placeholder-bearing Tx deserializes as an unbound template. Bind its
runtime values before canonical serialization or localization:
let template: LocalizedString = from_str?;
let value = template.bind_ron_template?;
let rendered = localizer.resolve_checked?;
Transporting RON messages without text lowering
Use a SourceMessageRef when application data must cross a Rust-to-TypeScript
boundary before runtime arguments are available. The reference contains only
stable entry, identity, and contract signatures. It contains neither English
source text nor runtime argument values.
let template: LocalizedString = from_str?;
let source_ref = template.source_message_ref?;
let json = source_ref.to_canonical_json?;
Authorize the parsed reference with the deployed source bundle, then bind its exact typed argument contract:
const message = sourceCatalog.sourceMessageFromJSON(json);
const localized = message.bind({ count: 3 });
const rendered = localizer.resolve(localized);
sourceMessageFromValue accepts an already-parsed JSON value. A
SourceMessage exposes an immutable argumentSchemas record and rejects
missing, extra, wrong-kind, unauthorized term-form, and non-atomic opaque
bindings. Static references bind with an empty record. Rust provides the same
catalog authorization and SourceMessage::bind contract.
The bound argument names and kinds must exactly match their declarations. Term bindings must also match the declared form and whether a number is present.
Descriptions do not round-trip through LocalizedString. They are authoring
metadata and are not retained in the runtime value or message identity. For
example, Tx(text: "Foo", description: "Example label.") can be read, but
serializing the resulting value produces Tx("Foo").
Term catalog
terms.ron is one top-level map:
{
"card-subtype.warrior": (
description: "The Warrior card subtype.",
value: "Warrior",
forms: {
"indefinite": "a Warrior",
"counted": Number([
One("Warrior"),
Other("Warriors"),
]),
},
),
}
Rules:
- A term has one stable ID and default value.
- Named forms are declared by project configuration.
- Numbered forms contain CLDR cardinal surfaces.
- Terms do not reference terms or messages.
- Source calls authorize exact form and number contracts.
- Fixed vocabulary stays in complete messages.
Project configuration
Minimal complete trox.ron:
(
source_locale: "en-US",
terms: "terms.ron",
source_bundle: "dist/locales/en-US.trox.json",
source_report: "locales/en-US.csv",
sources: [
(
language: Rust,
include: ["src/**/*.rs"],
exclude: [],
),
(
language: TypeScript,
include: ["web/**/*.ts", "web/**/*.tsx"],
exclude: [],
),
(
language: Ron,
include: ["data/**/*.ron"],
exclude: [],
),
],
locales: {
"es": (
profile: "locales/es.ron",
csv: "locales/es.csv",
bundle: "dist/locales/es.trox.json",
),
},
max_expanded_rows_per_entry: 256,
term_forms: {
"counted": (
description: "Term inflected for a cardinal count.",
number: Required,
),
"indefinite": (
description: "Nonspecific singular noun phrase.",
source_fallback: Default,
),
},
ron_description_defaults: {
"data/**/*.ron": "Player-authored game data label.",
},
)
The CLI discovers the nearest parent trox.ron. Select another complete
configuration with:
Locale profiles
Spanish example:
(
locale: "es",
direction: Ltr,
isolation: Isolate,
fallbacks: ["en-US"],
facets: {
"gender": (
scope: Message,
values: ["masculine", "feminine"],
),
},
term_facets: {
"card-subtype.warrior": {
"gender": "masculine",
},
"card-subtype.relic": {
"gender": "feminine",
},
},
)
Profiles own:
- Locale identifier and fallback chain.
- Left-to-right or right-to-left direction.
- Placeholder isolation behavior.
- Locale-private facet IDs and values.
- Term classification under those facets.
Message-scoped facets expand containing messages into rows. Term-scoped facets remain term context. Application code passes stable term IDs, not Spanish gender or other locale-private metadata.
Trox does not guess grammar from spelling, person names, or machine translation. Pass explicit semantic values when agreement requires them.
Extraction and CSV
Commands:
# Validate without writes.
# Synchronize every locale or one locale.
# Scaffold a locale.
# Build strict or development bundles.
# Remove reviewed obsolete rows.
# Create and merge a curated translator workbook.
Extraction is transactional:
- It validates every requested output before replacement.
- Any failure leaves all requested outputs unchanged.
- Successful replacements are atomic.
- Repeated extraction without changes is byte-identical.
- Parallel scanning does not change output order.
- Message rows follow source path, then numeric line and column. When the same message appears more than once, its earliest occurrence determines its position.
Extraction preserves:
- Existing translations.
- Translator notes.
- Unknown workflow columns.
- Previous translations for changed rows.
- Removed rows as obsolete records in target-locale CSVs.
Row state:
- New untranslated rows are missing.
- Translator-relevant source changes make rows stale.
- Removed source or expansion rows become obsolete in target-locale CSVs.
- Obsolete rows are removed automatically from the English source report; target CSVs retain them until explicit pruning.
Representative translator-facing CSV columns (managed metadata follows):
english,description,translation
{count} card,"Card count label.\n\nConditions: count.plural=one",
{count} cards,"Card count label.\n\nConditions: count.plural=other",
Managed IDs are tool-owned. Selector conditions are included in the description so translators can read all source context in one column; translators edit surface text and notes, not selectors.
For an external translator, use trox handoff export instead of sending the
canonical CSV. The .xlsx handoff contains active rows only; obsolete rows and
unknown workflow columns remain in the canonical CSV as translation memory.
Only the Translation and Translator note columns are editable. Managed metadata
is hidden and protected, and every cell is written as spreadsheet text so source
strings beginning with =, +, -, or @ cannot become formulas.
trox handoff import rejects formulas, added or removed rows and columns,
modified IDs, source metadata, or placeholder declarations, a changed source
catalog, and canonical CSV edits made after export. Imported translations also
run the project's normal placeholder and localization lint policy. A hidden
manifest binds the workbook to the locale, source locale, active row set, and
catalog fingerprint. Worksheet protection is for editing guidance; import
validation is the integrity boundary.
Condition examples:
card_count.exact=0
card_count.plural=few
turn_number.ordinal=other
zone.select=deck
subtype.gender=feminine
An exact translation cell containing ^ inherits the resolved translation
from the immediately preceding active row of the same entry:
description,translation
"Conditions: subtype.gender=masculine",Crear {count} Guerrero.
"Conditions: subtype.gender=feminine",^
Caret rules:
^cannot cross an entry boundary.- Blank cells remain missing.
- Consecutive carets resolve through prior active rows.
- Bundles materialize inherited text.
- Extraction protects meaning when adjacency changes.
Rows become stale when text, description, selector context, argument schema,
term-form request, or locale expansion changes. The old translation is kept in
previous_translation.
Run extraction before pruning. prune rejects a CSV that no longer matches the
current catalog, so a row that became active again is not deleted.
Lint policy
lint: (
default_warning: Warn,
rules: {
"trox.unchanged-translation": (
level: Deny,
),
"trox.human-row-expansion": (
level: Allow,
reason: "Reviewed translator cost in issue 123.",
),
},
),
Rules:
Warnreports a warning.Denypromotes a warning to an error.Allowrequires a nonempty review reason.- Reasons on
WarnorDenyare invalid. - Expansion above 32 rows requires reasoned suppression.
- The configured row limit remains a hard cap.
One-run overrides:
JSON diagnostics include a stable rule ID, severity, path, source span when
known, explanation, and suggested correction. trox.internal means an
implementation failure, not an ordinary authoring error.
Bundles and runtime
Every bundle operation emits:
- The configured source bundle.
- Every selected target bundle.
Deploy one source bundle and one active target bundle:
source bundle ─┐
├─> Localizer ─> resolve(LocalizedString) ─> String
target bundle ─┘
Bundles are canonical JSON containing:
- Explicit format version.
- Pinned locale-data version.
- Source-catalog fingerprint.
- Canonical entry and row IDs.
- Target plural and ordinal behavior.
- Direction and isolation settings.
- Validated term forms and facet metadata.
The source bundle authorizes message identities, full signatures, visible argument schemas, terms, and forms. Version 1.1 bundles also carry a contract signature derived from the identity and argument schemas. Target bundles contain translated rows and compatibility data.
Loading rejects unknown major versions, unsupported features, noncanonical JSON, duplicate IDs, irreproducible IDs, invalid paths, and invalid signatures.
A catalog mismatch can preserve entry-level compatibility in normal mode. Version 1.1 entries require matching contract signatures; version 1.0 entries use their stable source signatures. Incompatible entries use source fallback. Strict construction rejects any catalog-fingerprint mismatch.
Runtime responsibilities:
- Resolve selectors with target locale rules.
- Format numeric placeholders as locale decimals.
- Resolve terms and message-scoped facets.
- Apply configured directional isolation.
- Reorder, repeat, or omit declared placeholders.
- Emit diagnostics with visible source fallback.
Application responsibilities:
- Load bundle bytes.
- Choose the active target locale.
- Construct and distribute the
Localizer. - Keep
LocalizedStringunresolved in non-presentation layers. - Use checked resolution for tests and validation.
The runtime does not read files, fetch resources, discover locale state, mutate globals, parse CSV, run extraction, or evaluate translator-authored code.
Identity and compatibility
Entry IDs hash canonical JSON containing the identity version, meaning key, pattern structure, source leaves, and branch order. Descriptions, locations, runtime values, dynamic term IDs, and host predicates do not define identity.
Descriptions and argument contracts still affect source revision or signature, so their changes can stale translations without changing the entry ID.
Stable IDs are at most 96 ASCII bytes and match:
[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*
Numeric branches use exact values in ascending order, followed by zero,
one, two, few, many, and other. Generic select keeps authored order
and puts otherwise last.
Validation and conformance
trox check validates:
- Configuration and source globs.
- Rust, TypeScript, TSX, and RON syntax.
- Terms and named forms.
- Locale profiles and term classifications.
- Existing managed CSV state.
- Placeholders and selector branches.
- Target row expansion.
- Lint policy and reasons.
Runtime loading validates:
- Bundle and wire versions.
- Canonical encoding.
- Catalog fingerprints.
- Entry signatures and argument schemas.
- Selector values and paths.
- Term authorization.
- Expansion row IDs.
Shared fixtures cover static and dynamic identities, canonical wire bytes, source-message references, argument authorization, nested selectors, lookup, legacy version upgrades, and fallback.
Before changing identity, bundle, or wire behavior, run:
Confirm that a second extraction is byte-identical. The benchmark uses 100 MiB of equal Rust, TypeScript, TSX, and RON source with 10,000 calls:
Gates are warm startup below 50 ms, throughput of at least 200 MiB/s, peak RSS below twice the source size, and an optional 15 percent median regression cap.
Terminology
- Argument: runtime value bound to a visible placeholder.
- Atomic localized value: text leaf with no arguments or selectors,
inserted explicitly through
opaque. - Bundle: deterministic runtime JSON for source or target locale data.
- Cardinal: quantity category selected by
plural. - Caret inheritance: CSV
^shorthand for the preceding active row. - Catalog fingerprint: digest pairing compatible source and target bundles.
- Condition: read-only CSV label for one selector or facet choice.
- Description: translator context attached to a message or term.
- Entry: one extracted message family or term-form family.
- Entry ID: content-derived versioned message identifier.
- Exact branch: numeric branch checked before a CLDR category.
- Facet: locale-owned term metadata such as grammatical gender.
- Fallback: visible source text used when target data is unusable.
- Form: declared semantic term surface such as
indefinite. - Identity descriptor: canonical structure hashed into an entry ID.
- Locale profile: direction, isolation, fallback, and facet configuration.
- LocalizedString: immutable unresolved message value.
- Localizer: resolver built from one source and one target bundle.
- Meaning key: discriminator for identical text with different semantics.
- NFC: required Unicode Normalization Form C.
- Opaque: assertion that a localized value is grammatically atomic.
- Ordinal: position category selected by
ordinal. - Pattern: text leaf or finite selector tree of complete leaves.
- Placeholder: named insertion point such as
{card_name}. - RON: Rusty Object Notation used for checked static data.
- Row: one translation unit after locale-specific expansion.
- Scalar: visible text, finite number, or boolean argument.
- Select: finite semantic branch using a stable application value.
- Selector: plural, ordinal, or semantic pattern node.
- Source catalog: runtime authority for identities and argument contracts.
- Source report: source-locale CSV describing extracted rows.
- Source revision: translator context that may stale a row.
- Source signature: digest proving exact source compatibility.
- Stale row: active row whose source context changed.
- Term: stable lexical concept used for runtime grammar.
- Translation row: flat CSV record containing one editable pattern.
- Wire value: canonical serialized
LocalizedString.