Public value types for `core` and `react` are too loose

[yslpn]

Some public types in the translation API are much broader than the runtime behavior they describe:

// core
export type Values = Record<string, unknown>

// react
values?: Record<string, unknown>
components?: { [key: string]: React.ElementType | any }

At the type level, this means "almost anything is allowed". In practice, that is not true.

For example, this looks valid:

<Trans id="message.id" values={{ someDate: new Date() }} />

TypeScript accepts it because Date fits into unknown. But that does not mean the value is safe for the React layer. A Date object is not a valid React child, so this kind of input can still fail at runtime depending on how Trans handles it.

In practice, the failure looks like this:

Objects are not valid as a React child (found: [object Date]).
If you meant to render a collection of children, use an array instead.

The confusing part is that new Date() is a reasonable value in core, where date-like values can be passed into message formatting. On the React side, though, there is an explicit negative test for passing Date through <Trans values={...}>. So the same value is acceptable in one place and rejected in another, while both surfaces still expose very loose public types.

That makes the API hard to understand. The real contract is not obvious from the types. You have to infer it from implementation details, runtime behavior, and scattered tests.

It also makes these areas hard to refactor. When the public types allow almost anything, it is hard to answer simple questions with confidence:

• Which values are meant for message formatting?
• Which values are meant to become React children?
• Which values should be rejected at compile time?

Without clear answers, tightening the implementation becomes risky. It is too easy to break a case that was intentionally supported, or to preserve a case that only happened to work by accident.

Runtime checks are not enough here. They can tell us what happens today, but they do not clearly define what should be supported. The types need to carry more of that meaning, especially where core and react intentionally differ.

[yslpn]

Something like this can be done without changing the runtime, but the question of whether the runtime needs to be changed is still open.

// i18n.ts

import {
  ...
  type DateTimeFormatValue,
  type NumberFormatValue,
} from "./formats"

export type PrimitiveValue = string | number | boolean | null | undefined

export type MessageValue =
  | PrimitiveValue
  | DateTimeFormatValue
  | NumberFormatValue

export type Values = Record<string, MessageValue>

...

export type MessageDescriptor = {
  ...
  values?: Values
}

// TransNoContext.tsx

export type TransComponents = Record<string, React.ReactElement>

export type TransValue =
  | PrimitiveValue
  | React.ReactElement
  | Array<React.ReactNode>

export type TransValues = Record<string, TransValue>

export type TransProps = {
  ...
  values?: TransValues
  components?: TransComponents
  ...
}

[timofei-iatsenko]

Do you want to improve this? What should be done to push it forward?

[yslpn]

Do you want to improve this? What should be done to push it forward?

I'd like to fix this, but I wasn't completely sure what exactly needed to be done. It would be good to align on a shared vision first and discuss it with someone else.

I see two options:

1. Extend Trans values to bigint | Date | false | null | undefined

Pros

• The types would match the actual runtime behavior of the i18n core.
• This could simplify things for users in some cases, since they would not need to call toString() for Date or similar values manually.

Cons

• This extension would require further support over time, such as adding Temporal or other objects, handling more edge cases, and so on.
• The Values extension in React Trans cannot be fully identical to the i18n core because of JSX specifics.

For example, i18n._("x", { v: false }) will yield "x false", while <Trans message="x {v}" values={{ v: false }} /> will yield "x ".

2. Narrow Trans values down to string | number

Pros

• Passing Date | false | null | undefined in values, or something similar, is usually not what the user wants and can lead to a silent error.
• The API would be more predictable for consumers and developers.
• The code would be easier to maintain in the long run.

Cons

• I would consider limiting input types in the i18n core in the future as well, making them string | number, which would lead to breaking changes.
• It might be inconvenient for some users who would need to call toString() themselves.

I personally prefer the second option. And want to hear your opinion @timofei-iatsenko . Maybe I missed something.

Context:

• I previously tried the first option in this PR, but it was closed and the work is not finished: fix: trans values typing and runtime #2502
• There is also a user PR that tries to add bigint, but I think this needs a more complete solution: fix(core): add bigint to MessagePlaceholder type #2507