[AKnassa]

What this does

Teams that already run an i18n library (react-intl, i18next, LinguiJS) can now have Astryx's own built-in strings go through their translation setup instead of Astryx's bundled formatter.

Why

The Translator interface was already exported publicly with nothing behind it — the type shipped, InternationalizationProvider had no way to accept one, and resolve() hard-coded the runtime. The CLI docs even advertised it as unbuilt, pointing readers at this issue.

What changed

InternationalizationProvider takes an optional translator. Astryx still does its own lookup — your overrides, then your messages, then the parent language (pt-BR → pt), then the shipped English catalogue — and hands your translator the finished ICU message, never a raw @astryx.* key. That means you don't have to load Astryx's catalogue into your own store.

Every Astryx string goes through your translator, including the ones with nothing to interpolate — which is most of them (162 of 197 shipped keys; 171 of 228 callsites). values is undefined for those calls. This is deliberate: if only the interpolating quarter reached your runtime, a catalogue keyed on the English text would translate Go to page {page} and silently miss Close, with no signal that half your UI never arrived. Two things follow — your runtime's missing-translation path runs on every string, so keep it cheap; and this is what makes the issue's one-provider example (translator, no messages) actually do what it claims.

format must return a string. Anything else — react-intl's ReactNode[] for rich text, i18next's null for a miss — warns once in development and falls back to Astryx's resolved message, because that output also feeds aria-label and title, where a non-string becomes [object Object] or drops the attribute. Exceptions are not caught: a broken adapter should be loud, not quietly papered over.

Leaving the prop off is a no-op: the bundled path and its formatter cache behave exactly as before, at the cost of one != null comparison.

Needs a maintainer call

This adds a new public prop on a core provider, plus a new optional field on the publicly-exported context value. The shape isn't invented — the shipped Translator signature format(message, values?, locale?) forces the lookup/format split, and the issue names the prop verbatim — but whether the API should exist is a maintainer's decision, not a contributor's.

Two specifics worth confirming:

1. Where fallback lives. The issue lists this as an open question. The shipped type answers it by construction — format takes a message, not a key — and the code follows that answer: Astryx owns the lookup chain, the adapter owns formatting.
2. Value-less strings go through too. The alternative is to short-circuit them, which is what the first revision of this PR did. It left the adapter covering roughly a quarter of Astryx's strings while the docs advertised full catalogue override, so I moved the branch. Astryx pays nothing either way — the ICU parser is skipped in both cases; the cost is one call into a runtime the consumer opted into.

What this does not do

No catalogue-merge helper (the issue lists it as an optional nice-to-have).

No server/RSC path. translator holds a function, so it can only be passed from a client component — a server-rendered subtree stays on the bundled runtime, and a future server resolver will need to thread translator too. Relatedly, a nested InternationalizationProvider replaces the translator rather than inheriting it, matching how messages and overrides already behave. Both are documented and pinned by tests.

The react-intl example added to the docs is written from its public API but not executed, since react-intl isn't a dependency of this repo. Anyone who uses it should sanity-check that snippet — particularly the values cast, which exists because react-intl types values more narrowly than Astryx's Record<string, unknown> and its rich-text overload returns ReactNode[].

How to check it

pnpm vitest run packages/core/src/i18n/ — 73 tests (30 in this directory before the PR, 47 at the first revision). They assert that the translator receives the resolved message rather than the key (proving the fallback chain stayed inside Astryx), that value-less strings reach it, that a non-string return degrades safely instead of reaching an aria-label, and that a live translator or locale swap propagates. Edge coverage includes odd locale tags, empty-string catalogue entries, parent-locale overrides, and nested providers.

Four assertions were mutation-tested. One turned out to be fake: the dep-array test passed even with ctx.translator deleted from useTranslator's useCallback, because the provider's messages ?? {} allocates a fresh object on every memo recompute, so ctx.messages invalidated the callback on its own. Pinning messages to a stable reference kills the mutant.

Full packages/core suite: 225 files / 5254 tests, exit 0.

Refs #4029

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 26, 2026 4:30am UTC

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR

🧪 Sandbox Preview

View Sandbox for this PR

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.9KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

Visual Regression

1 of 420 shot(s) changed. View the report

A change here is a question, not a failure: check whether the after is the
picture you intended. Record that review on the PR. Baseline maintenance is an
explicit dispatch of CI; this report never rewrites the baseline or adds a release gate.

component	story	theme	mode	pixels
SideNav	Resizable in AppShell	probe	dark	3,208

SideNav — Resizable in AppShell — probe dark

Before	After	Diff

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[astracat-bot]

Thanks for wiring the Translator adapter through the provider — the lookup staying in Astryx, the resolved-message (never key) handoff, and the test coverage are clear.

Approval is waiting on a maintainer decision: this adds a new public translator prop (and context field), and a maintainer needs to provide or identify the governing spec for that addition, settling (1) that Astryx keeps lookup/locale fallback and the adapter only formats the resolved ICU message, and (2) that every resolved string, including value-less ones, is delegated. Please do not treat this as a request to remove or split the change for that reason alone.

One independent fix is also needed before approval: when translator.format returns a non-string, the fallback in resolve returns the raw ICU template (for example Go to page {page, number}), which reaches Pagination's visible label and aria-label. Please format the resolved message with its values through the bundled formatter on that path (raw message only when there are no values) and update the test/docs that currently expect the template.

[Automated review]

[AKnassa]

Thanks for the review. I've pushed an update at 5f2d7b6.

• I merged main in f08c9f3. It conflicted in all four i18n source files because refactor(i18n): pre-build lookup map for translations #4696 replaced resolve() with the getResolve() closure. The translator is now bound inside that closure, via an optional fourth argument to getResolve. The provider passes it and keeps it in the memo deps, and useTranslator is back to main's ctx.translate.
• You were right about the non-string fallback, fixed in 5f2d7b6. With a translator that returns null, every Pagination page button got the accessible name "Go to page {page, number}", and my own test was pinning that output. The non-string path now warns once and falls through to the bundled formatter, so the output matches what you get with no translator. The bad-return tests now expect "Go to page 5". A new Pagination test checks that no aria-label contains {. The docs and the changeset now describe the fallback as the bundled formatter.

Still open, for a maintainer: this adds a public translator prop, and the draft contract in #6048 leaves it as OQ3. Could someone confirm (1) that Astryx keeps lookup and fallback while the adapter only formats, which INV14 there already supports? And for (2), should value-less strings go through the adapter too? The context's translator field is no longer read internally. I've kept it for now, and I'm happy to drop it if you'd prefer a smaller public surface.

On my side, the PR description still needs updating to match.

[astracat-bot]

Thanks for wiring the Translator adapter through the provider, and for the follow-up push — I verified the non-string fallback fix at this revision: a bad adapter return now falls through to the bundled formatter, and the tests expect formatted labels (for example "Go to page 5") with no raw placeholders in Pagination's accessible names. That blocker from the previous review is resolved.

Approval is still waiting on a maintainer decision. This adds a new public translator prop on InternationalizationProvider, plus a translator field on the exported context value, and a maintainer needs to provide or identify the governing spec for that addition, settling:

• that Astryx keeps lookup and locale fallback, and the adapter only formats the resolved ICU message;
• that every resolved string, including value-less ones, is delegated to the adapter; and
• whether the context translator field is kept or dropped, since nothing internal reads it now and you noted you are happy to drop it for a smaller public surface.

Please do not treat this as a request to remove or split the change for that reason alone. Once a maintainer settles that spec question, no other fix from this review is outstanding — though the PR description update you already flagged would help the next reader.

[Automated review]