RFC: message references

[debel27]

Introduction

next-intl promotes translating messages within React components. This is a great design decision, because messages depend on reactive data that can change across renders (such as the user locale).

However, like many internationalization libraries, next-intl expects developers to identify the message to translate directly within the call site of t. As explained later, this approach results in usability issues.

I would like to introduce the concept "message references" to next-intl, which gives the ability to identify messages without immediately translating them.

Motivations

Giving the ability to reference a message separately from the translation operation introduces a useful decoupling, improving flexibility and ergonomics:

1. it allows referencing messages in contexts where the t function is not available.
2. developers no longer need to call useTranslations every time they need to translate something. They can simply declare a message reference and pass it to translation-aware components/hooks, which will deal with the actual translation operation.

Those benefits are particularly appreciated in data-driven codebases, as the upcoming examples will illustrate.

Before getting to the examples, I will formalize the proposal a bit.

Proposal

Basic principle

next-intl will introduce an IntlMessage type, defined as follows:

type IntlMessage = {
  key: string;
  parameters: Record<string, TranslationValue>:
}

The strict typing of key and parameters will be adressed later in the document.

The signature of the t function will be updated to accept IntlMessage as an argument.

Here is a simple example to illustrate the idea:

import { type IntlMessage, useTranslations } from "next-intl";

const msg: IntlMessage = { 
  key: "common.greetings",
  parameters: { firstName: "John" }
};

function Component() {
  const { t } = useTranslations();
  // IntlMessage objects are valid arguments for `t`
  t(msg);
  // referencing messages inline still works
  t("common.save");
}

Creating IntlMessage objects

Developers will not create IntlMessage objects directly. They will do it with the help of a utility i18n function. i18n accept the exact same parameters as t:

const msg = i18n("common.greetings", { fistName: "John" });

i18n is not to be confused with t! i18n can be called outside React components and does not translate anything. It only allows declaring a reference to a message, to be translated later by t.

i18n makes declaring references easier and will play nicer with TypeScript (as shown later). To make sure developers use it, we can make IntlMessage branded:

const i18nSymbol = Symbol("i18n");

type IntlMessage = {
  [i18nSymbol]: "";
  key: string;
  parameters: Record<string, TranslationValue>:
}

Package consumers will not have access to i18nSymbol, forcing them to create IntlMessage objects through the i18n function.

TypeScript augmentation

i18n accepts the exact same parameters as t. Therefore, it can benefit from the same TypeScript APIs, includng the strict typing of ICU arguments. For this reason, I'm assuming type safety will be trivial to implement.

Examples

These examples illustrate the possibilities unlocked by the new IntlMessage type.

Static references

IntlMessage allows developers to declare messages references statically, outside React space. This gives more flexibility to organize code.

topBarEntries.ts

export const topBarEntries = [
  {
    id: "profile",
    label: i18n("topBarItem.profile")
    link: "/profile",
  },
  {
    id: "settings",
    label: i18n("topBarItem.settings"),
    link: "/settings"
  }
];

topBar.ts

import { topBarEntries } from "./topBarEntries.js";

export function TopBar() {
  const { t } = useTranslations();
  return (
    <div className="top-bar">
      {topBarEntries.map(entry => {
        const {id, label, link} = entry;
        return <a key={id} href={link}>{t(label)}</a>
      })}
    </div>
  );
}

I18n-first components

Now that message references are first-class citizen of the next-intl package, they can be used to improve developer experience in application space, since they allow writing components with built-in I18n support.

For instance, consider we developed a wrapper on top of <input/> to support label internationalization:

import { type IntlMessage, useTranslations } from 'next-intl';

// other props are ignored
type InputProps = {
  label: IntlMessage;
}

export function Input(props: InputProps) {
  const { label } = props;
  const { t } = useTranslations();
  return (
    <label>
      {t(label)}
      <input />
    </label>
  );
}

Our Input has an API that improves developer experience, because callers of that component no longer need to call useTranslations to pass down a translated label.

import { i18n } from 'next-intl';

function Component() {
  return (
    <Input label={i18n("field.firstName")} />
  );
}

Given i18n can be auto-imported by the IDE, there is less ceremony involved when dealing with internationalization.

Additional utilities

We can leverage the IntlMessage ecosystem by introducing the following utility functions

i18nIdentity

If an API only accepts an IntlMessage as input, the developer needs a workaround when they want to display some text "as is" instead of an internationalized message.

The i18nIdentity function can be for such case:

function i18nIdentity(data: string): IntlMessage {
  return {
    [i18nSymbol]: "",
    key: "__identity",
    parameters: { data }
  };
}

The utility relies on a built-in message __identity: "{data}", inserted automatically by next-intl.

Example: i18nIdentity("Some text coming from the server")

isIntlMessage

Convenience function to determine if an object is an IntlMessage

function isIntMessage(data: unknown): data is IntlMessage {
  return (
    !!data && typeof data === "object" && i18nSymbol in data;
  );
}

This can be particularly handy for I18n-first components:

import type { ReactNode } from "react";
import { type IntlMessage, isIntMessage, useTranslations } from "next-intl";

type InputProps = {
  label: IntlMessage | ReactNode
}

function Input(props: ComponentProps) {
  const { label } = props;
  const { t } = useTranslations();

  const resolvedLabel = isIntMessage(label) ? t(label) : label;
  return (
    <label>
      {resolvedLabel}
      <input />
    </label>
  );
}

[amannn]

Hey @debel27, thanks for taking the time to write up this RFC!

On a first look, it seems like this use case is already supported to some extend, see e.g.: #1575 (comment).

Separating data from translations is quite common and good practice IMO. E.g. in a codebase I'm currently working on I have the rule that any "service" works purely on data and translations must only be applied in components (with Server Actions that are defined along with components also counting as part of that). E.g. submitProductReview can return validation errors and it's the job of the component to turn it into a human readable label. In this case, I want submitProductReview to not be aware of translations at all, also a "message reference" would break this separation of concerns IMO.

Regarding your examples, it seems like these can already be realized currently:

const topBarEntries = [
  {
    id: "profile",
    link: "/profile",
  },
  {
    id: "settings",
    link: "/settings"
  }
];

function TopBar() {
  const t = useTranslations();
  return (
    <div className="top-bar">
      {topBarEntries.map(entry => {
        const {id, link} = entry;
        return <a key={id} href={link}>{t(`topBarItem.${id}`)}</a>
      })}
    </div>
  );
}

import { useTranslations } from 'next-intl';

function Component() {
  const t = useTranslations();
  return (
    <Input label={t("field.firstName")} />
  );
}

(Benefit: Any label can be accepted, translated or not)

So as things stand currently, I have to say that don't really see a large benefit of introducing this. Does that make sense to you? I tend to be quite conservative with APIs that are added to next-intl to ensure the library remains as minimal as possible, therefore if something is already possible without much inconvenience, I prefer sticking to the existing feature set.

[debel27]

Thank you for your reply! I appreciate you took the time to review this.

So as things stand currently, I have to say that don't really see a large benefit of introducing this. Does that make sense to you? I tend to be quite conservative with APIs that are added to next-intl to ensure the library remains as minimal as possible, therefore if something is already possible without much inconvenience, I prefer sticking to the existing feature set.

As a maintainer myself, I completely understand you do not want to overbloat your package. Especially if the solution can be implemented in userland, which is the case here.

I wrote the RFC because I kept re-introducing this pattern in the codebases I work with. Since it solves a clear problem for me, I though it would be nice to have the primitive built into the library itself.

I'll try and develop further why I consider the pattern useful. I don't mean to push for it. If you don't consider this useful, feel free to reject this RFC.

---

About existing support

On a first look, it seems like this use case is already supported to some extend, see e.g.: #1575 (comment).

It is indeed already possible to refactor the arguments of t into variables, giving the ability to reference message outside the arguments of t.

What my proposal provides is semantics. With IntlMessage, the refactored variables can be identified as a "message to be translated". This new primitive can be leveraged by developers throughout their code.

The few teams I introduced to this concept came to appreciate the ability to identify messages this way, because it adds a sense of robustness to their code. For starters, going from

const message = "field.firstName";

... to

const message = i18n("field.firstName");
//              ^^^^ returns an `IntlMessage` object

... makes it immediately clear what message is about.

The IntlMessage type also has the convenience of bundling the key and parameters together, so it is more than a string alias:

const message = i18n("field.greetings", { firstName: "John" });

Beyond ergonomics and convenience, I think the main appeal for IntlMessage is that developers know exactly how to process this type when they encounter it in TypeScript APIs. Only i18n can create an IntlMessage object, so IntlMessage has some sort of authenticity. You know the object is legit and can be safely droped in a t function for translation purposes.

If anything, IntlMessage makes things more explicit and development more streamlined. At least, this is what I've observed.

About software architecture

Separating data from translations is quite common and good practice IMO. E.g. in a codebase I'm currently working on I have the rule that any "service" works purely on data and translations must only be applied in components (with Server Actions that are defined along with components also counting as part of that). E.g. submitProductReview can return validation errors and it's the job of the component to turn it into a human readable label.

Precisely. I think many popular libraries failed to abstract themselves from translations (zod, react-hook-form, ...). This is a real problem to deal with when you're trying to keep things decoupled.

I want submitProductReview to not be aware of translations at all, also a "message reference" would break this separation of concerns IMO.

I agree. Validation systems should emit error codes, not message references. I design them the same way.

The scope of my proposal is not about introducing translation concerns to unrelated parties. It is rather about giving more flexibility to code that is already translation-aware.

About provided examples

Regarding your examples, it seems like these can already be realized currently:

const topBarEntries = [
  {
    id: "profile",
    link: "/profile",
  },
  {
    id: "settings",
    link: "/settings"
  }
];

function TopBar() {
  const { t } = useTranslations();
  return (
    <div className="top-bar">
      {topBarEntries.map(entry => {
        const {id, link} = entry;
        return <a key={id} href={link}>{t(`topBarItem.${id}`)}</a>
      })}
    </div>
  );
}

100% correct. Again, the difference between this code and my proposal are semantics.

My proposal considers message references as part of the data. It is static information that lives alongside id and link, not something that is derived during render. In data-driven applications, it is rather idiomatic to consider message references as first class data. The ability to define them statically alongside other data, outside React components is also a big plus.

I get this might be too opinionated for your taste. Please, note that IntlMessage would be an addition to the ecosystem, not a replacement. You'd still be able to write the code you just shared. It simply gives more choice and flexibility for developers to manage their internationalized code.

import { useTranslations } from 'next-intl';

function Component() {
  const t = useTranslations();
  return (
    <Input label={t("field.firstName")} />
  );
}
(Benefit: Any label can be accepted, translated or not)

Sure. To be clear, the example I shared to illustrate "isIntlMessage" also accepts any label, because we have label: IntlMessage | ReactNode.

function Component() {
  return (
    <div>
      <Input label={i18n("field.firstName")} />
      <Input label="Some custom label" /> // also works
      <Input label={<span>label</span>} /> // also works
    </div>
  );
}

[amannn]

Thanks for expanding on your idea!

I think for the time being I don't really see the value of introducing this layer to the concept of rendering messages, I hope you can understand.

If it's something you'd really like to use, could this by realized in your codebase with something like this?

const msg = i18n("field.firstName", {firstName: "John"});
t(...msg);

[debel27]

No problem, I understand.

If you ever feel frustrated about message references in your own application code, I hope you will give this idea a shot :)

Indeed, we can totally manage this in our own codebase. In practice, we created a monorepo package that encapsulate the library and adds our i18n abstraction on top of t.