msg-react

React components for rendering messages from @worldware/msg.

Installation

@worldware/msg is a peer dependency of @worldware/msg-react (and is marked external in the build). Install both packages in your app:

npm install @worldware/msg@^0.12.0 @worldware/msg-react

That keeps a single shared @worldware/msg instance and types in the dependency tree and avoids duplicate copies. On 0.x, caret ranges do not include the next minor, so install a @worldware/msg release that satisfies this package's peer (^0.12.0).

Components

MsgResourceProvider

Provides a MsgResource to descendants via React context. On mount, it resolves a language tag from the nearest ancestor with a lang attribute, or falls back to navigator.language, then calls resource.getTranslation(lang) and updates the context with the result.

Prop	Type	Description
resource	MsgResource	Message resource to expose and translate
children	React.ReactNode	Tree that can consume the resource

Also exports MsgResourceContext if you need to read the resource directly with useContext.

MsgMessage

Looks up a message by key from MsgResourceContext and renders it inside a <span> with lang and dir from the message attributes.

Prop	Type	Description
msgKey	string	Key of the message to render
data	Record<string, any> (optional)	Values passed to message.format()
options	MessageFormatOptions (optional)	Options forwarded to message.format()

• With data: calls message.format(data, options)
• Without data: calls message.toString()
• Missing key or null context: renders an empty <span>

Usage

Basic setup

Wrap your app (or a subtree) with MsgResourceProvider passing in an MsgResource instance, then render messages with MsgMessage:

import { MsgResource } from '@worldware/msg'
import { MsgResourceProvider, MsgMessage } from 'msg-react'

const resource = MsgResource.create(/* ... */)

function App() {
  return (
    <div lang="en">
      <MsgResourceProvider resource={resource}>
        <h1>
          <MsgMessage msgKey="greeting" data={{ name: 'Kat' }} />
        </h1>
      </MsgResourceProvider>
    </div>
  )
}

Format with data and options

Pass data (and optional options) to call message.format():

<MsgMessage
  msgKey="greeting"
  data={{ name: 'Kat' }}
  options={{ bidiIsolation: 'none' }}
/>

Plain message text

Omit data to render message.toString() instead:

<MsgMessage msgKey="welcome" />

Language resolution

MsgResourceProvider picks a language from the nearest ancestor with a lang attribute:

<div lang="fr">
  <MsgResourceProvider resource={resource}>
    <MsgMessage msgKey="greeting" data={{ name: 'Kat' }} />
  </MsgResourceProvider>
</div>

If no lang ancestor exists, it falls back to the navigator.language setting.

Read the resource from context

Use MsgResourceContext when you need the resource outside of MsgMessage:

import { useContext } from 'react'
import { MsgResourceContext } from 'msg-react'

function MessageCount() {
  const resource = useContext(MsgResourceContext)
  // use resource.get(...), etc.
  return null
}

Scripts

Script	Description
npm test	Run tests once
npm run test:watch	Run tests in watch mode
npm run build	Bundle ESM + CJS (and types) to dist/ via tsup