Skip to content

Navigation Menu

Sign in
Sign up

docs(core): define the internationalization contract - #6048

Draft
nynexman4464 wants to merge 1 commit into
main from
nynexman4464/docs/i18n-contract
Draft

docs(core): define the internationalization contract #6048
nynexman4464 wants to merge 1 commit into
main from
nynexman4464/docs/i18n-contract

Conversation

@nynexman4464

@nynexman4464 nynexman4464 commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Problem

Astryx's released internationalization behavior is spread across RFC #3641, consumer docs, tests, and implementation. There is no current repository record that tells reviewers which runtime, fallback, ownership, locale, direction, and calendar boundaries are intentional.

That makes it easy to review a replacement API or locale-sensitive component change without the context that produced the shipped system.

Changes

  • Add a draft architecture:internationalization record for the cross-library contract.
  • Add a draft component:InternationalizationProvider contract for provider-local behavior.
  • Name the provider's nonvisual anatomy in consumer docs so the component record does not imply rendered DOM.
  • Add a docs changeset for that consumer-doc addition.

The records preserve the released provider/hook model and the deliberate differences from RFC #3641: client context, deterministic English defaults, silent translation fallback, explicit provider-locale threading, DOM-owned layout direction, and Gregorian PlainDate semantics.

Boundaries and open questions

  • Astryx owns Astryx system strings; applications own product copy.
  • This does not turn Astryx into a full application i18n framework or admit arbitrary rich-message values.
  • Malformed locale tags currently have formatter-specific throw behavior; the draft records that rather than claiming graceful fallback.
  • Instant-display utilities that delegate calendar selection to Intl are not treated as first-class alternative-calendar support.
  • Nested-provider replacement needs one focused regression test before promotion.
  • External runtime adapters and an RSC translation API remain separate API decisions.

This PR is intentionally draft. The records remain authority: draft until their owners approve them.

Test plan

  • pnpm check:knowledge
  • node scripts/check-changesets.mjs
  • pnpm exec vitest run --project node scripts/check-knowledge.test.mjs — 74 tests
  • pnpm exec vitest run --project ui packages/core/src/i18n/ — 62 tests
  • Verified the provider record against malformed-locale behavior, the current public export barrel, nested-provider source behavior, and PlainDate calendar pinning.

vercel Bot commented Sep 4, 2026
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated
astryx Ready Ready Preview Sep 4, 2026 8:29pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Sep 4, 2026

github-actions Bot commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

PR Analysis Report

Preview availability: Storybook and Sandbox were not published for this CI run.

No new or modified components detected.

Bundle Size Summary

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

Accessibility Audit

Status: No accessibility violations detected.


Generated by PR Enrichment workflow | View full report

cixzhang commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

/approve-spec 8b4f2b9

@cixzhang cixzhang left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for documenting the shared internationalization architecture and the provider-specific contract together. Approved at exact head 8b4f2b9853fae7dafb3bd4d72877301bfa489366.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cixzhang cixzhang cixzhang approved these changes
@imdreamrunner imdreamrunner Awaiting requested review from imdreamrunner imdreamrunner will be requested when the pull request is marked ready for review imdreamrunner is a code owner
@josephfarina josephfarina Awaiting requested review from josephfarina josephfarina will be requested when the pull request is marked ready for review josephfarina is a code owner

Assignees

No one assigned

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /