React

React is offically supported by the library. (tested with React 19+) You have to wrap your app component tree with our context provider which will provide the currently active locale and then you can use the built-in or the genereted hook (via the global seeder).

Installation

pnpm

pnpm add @ardinsys/intl @ardinsys/intl-react

npm

npm install @ardinsys/intl @ardinsys/intl-react

Usage

We will show how to use the integration with the global seeder, since this is the preferred way. Usually you need messages that are available in every component, but even if you don't, you surely don't want to repeat your number and date formats in every component, or always import them separately.

NEXT.JS

In server side / hybrid rendering environments, make sure you put "use client"; in the top of the file where you use the hook or where you create the IntlProvider which uses React context under the hood.

Lets assume @/ is an alias for your src folder.

In your application you could create an internalization/index.ts file where you can create your seeded instance:

"use client";
import { createSeededIntl } from "@ardinsys/intl-react";

// IntlProvider is the react context provider
// useIntl is the properly typed hook based on the bundles
export const { IntlProvider, useIntl } = createSeededIntl(seedBundles);

To see what seedBundles is please refer to the Quick start guide

Wrapping your component tree

In your entrypoint tsx, wrap everything with our context provider.

// Importing this from the react lib itself is also fine
import { IntlProvider } from "@/internalization";

function App() {
  return (
    <IntlProvider initialLocale="en">
      <RealApp />
    </IntlProvider>
  );
}

Using the hook in components

Now you can just import the hook into your components and use it with global data already available everywhere:

"use client";
import { useIntl } from "@/internalization";

function MyComponent() {
  const { t } = useIntl({
    en: {
      messages: {
        test: "This is a message from {name}",
      },
    },
    hu: {
      messages: {
        test: "Ez egy üzenet tőle {name}",
      },
    },
  } as const);

  return <div>{t("test", { name: "John" })}</div>;
}

Component interpolation

Use <Translation> to insert React elements into translated strings. Placeholders in the message are replaced by components.

Named placeholders

Provide a components map where keys match placeholder names.

"use client";
import { Translation } from "@ardinsys/intl-react";
import { useIntl } from "@/internalization";

export function Example() {
  const intl = useIntl({
    en: { messages: { hello: "Hello {name}!" } },
    hu: { messages: { hello: "Szia {name}!" } },
  } as const);

  return (
    <Translation
      intl={intl}
      path="hello"
      components={{ name: <strong>John</strong> }}
    />
  );
}

Positional placeholders

{0}, {1}, … are filled from the children in order.

"use client";
import { Translation } from "@ardinsys/intl-react";
import { useIntl } from "@/internalization";

export function DocsCta() {
  const intl = useIntl({
    en: {
      messages: {
        docs: "Read {0} and {1}.",
        terms: "Terms",
        privacy: "Privacy",
      },
    },
  } as const);

  const { t } = intl;

  return (
    <Translation intl={intl} path="docs">
      <a href="/terms">{t("terms")}</a>
      <a href="/privacy">{t("privacy")}</a>
    </Translation>
  );
}