[FEATURE] markup placeholders (html, rich text, components)

[samuelstroschein]

💡 Upvote and subscribe to this issue to increase prioritization.

Problem

Users can not use markup placeholders.

See this long thread https://github.com/opral/monorepo/discussions/1959#discussioncomment-8004920

And this one from https://discord.com/channels/897438559458430986/1110687789395226716/1110903944143712338:

Proposal

Add markup placeholders.

From the message format working group https://github.com/unicode-org/message-format-wg/blob/main/spec/syntax.md#markup-elements

Originally posted by @samuelstroschein in https://github.com/opral/monorepo/discussions/913

[samuelstroschein]

We have a longer RFC. Feel free to comment on the Google Doc https://docs.google.com/document/d/1uhLrrwKPsenyNsDvZqCl6UXJc5ZBVQYkzn7k5yBuVy0/edit#heading=h.hv9mugtjvm53

[samuelstroschein]

In the meantime you can directly write HTML in your messages and then call the message with dangeourslySetInnerHtml (react) or @html in Svelte

[machycek]

This is the biggest blocker for us not switching over to paraglide. Hoping this lands at some point. Thanks for all the hard work 💯

[gtbuchanan]

I'm providing my "injection safe" Vue implementation using the strategy from the OP's screenshot (and influenced by this) in hopes that it improves Paraglide JS adoption and guides the implementation of markup placeholders (i.e. component interpolation).

ParaglideM Functional Component

// Polyfill for RegEx.escape
import 'regexp.escape/auto';
import '@types/regexp.escape/auto';

import { createTextVNode, h } from 'vue';
import type { PropType, SetupContext, Slot, VNodeChild } from 'vue';

type ParaglideMFunction<TInputs, TOptions> = (inputs: TInputs, options?: TOptions) => string;

interface ParaglideMProps<TInputs, TOptions> {
  message: ParaglideMFunction<TInputs, TOptions>;
  inputs: TInputs;
  options?: TOptions;
  tag?: string | undefined;
}

function renderInputs(slots: Record<string, Slot | undefined>): Record<string, VNodeChild> {
  return Object.entries(slots)
    .filter(([key]) => key !== '_')
    .reduce((acc, [key, slot]) => ({
      ...acc,
      [`[${key}]`]: slot?.() as VNodeChild,
    }), {});
}

type InputReplacer = (message: string, inputs: Record<string, VNodeChild>) => string[];

function createInputReplacer(inputNames: string[]): InputReplacer {
  const inputCondition = inputNames.map(RegExp.escape).join('|');
  const regExp = new RegExp(`(\\[(${inputCondition})\\])`);
  return (message, inputs) => message
    .split(regExp)
    // HACK: The inner group in the split regex ends up in the output, so we need to skip it
    .filter((_, i, { [i - 1]: part }) => !part || typeof inputs[part] === 'undefined');
}

function interpolateSlots(
  message: string,
  slots: Record<string, Slot | undefined>,
): Array<VNodeChild | null> {
  const inputs = renderInputs(slots);
  const replaceInputs = createInputReplacer(Object.keys(slots));
  const parts = replaceInputs(message, inputs);
  return parts.map((part) => {
    const { [part]: input } = inputs;
    return typeof input === 'undefined' ? createTextVNode(part) : input;
  });
}

const defaultTag = 'span';

export const ParaglideM = <TInputs, TLocale>(
  props: ParaglideMProps<TInputs, TLocale>,
  { slots, attrs }: SetupContext,
): VNodeChild => {
  const message = props.message(props.inputs, props.options);
  const children = interpolateSlots(message, slots);
  return h(props.tag ?? defaultTag, attrs, children);
};

ParaglideM.props = {
  message: {
    /* eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       -- This is the only way to define a function prop type for function components */
    type: Function as PropType<ParaglideMFunction<Record<string, unknown>, { locale?: string }>>,
    required: true,
  },
  inputs: {
    type: Object as PropType<Record<string, unknown>>,
    required: true,
  },
  options: {
    type: Object as PropType<Record<string, unknown> | undefined>,
    default: undefined,
  },
  tag: {
    type: String as PropType<string>,
    default: 'span',
  },
};

ParaglideM Usage

{
  "$schema": "https://inlang.com/schema/inlang-message-format",
  "greeting": "Hello, [name]!"
}

<script lang="ts" setup>
import { m } from '@/paraglide/messages.js';

const props = defineProps<{ name: string }>();
</script>

<template>
  <paraglide-m
    :message="m['greeting']"
    :inputs="undefined"
    tag="p"
  >
    <template #name>
      <span class="name">{{ props.name }}</span>
    </template>
  </paraglide-m>
</template>

<style scoped>
.name {
  font-weight: bold;
}
</style>

ParaglideM Tests

import { faker } from '@faker-js/faker';
import { mount } from '@vue/test-utils';
import { describe, it } from 'vitest';
import { mockFn } from 'vitest-mock-extended';
import { createTextVNode } from 'vue';
import { ParaglideM } from '@/components/ParaglideM.js';

describe('ParaglideM', () => {
  it('renders span by default', ({ expect }) => {
    const message = mockFn().mockReturnValue('');
    const sut = mount(ParaglideM, { props: { inputs: {}, message } });

    expect(sut.html()).toBe('<span></span>');
  });

  it('renders the specified tag', ({ expect }) => {
    const message = mockFn().mockReturnValue('');
    const sut = mount(ParaglideM, { props: { inputs: {}, message, tag: 'p' } });

    expect(sut.html()).toBe('<p></p>');
  });

  it('passes through attributes to the root element', ({ expect }) => {
    const class1 = faker.word.noun();
    const id = faker.string.uuid();
    const message = mockFn().mockReturnValue('');
    const sut = mount(ParaglideM, {
      props: { inputs: {}, message },
      attrs: { class: class1, id },
    });

    expect(sut.html()).toBe(`<span class="${class1}" id="${id}"></span>`);
  });

  it('renders the slot as HTML', ({ expect }) => {
    const message = mockFn<() => string>().mockImplementation(() => `Hello, [name]!`);
    const nameHtml = `<span class="${faker.word.noun()}">${faker.person.firstName()}</span>`;
    const sut = mount(ParaglideM, {
      props: { inputs: {}, message },
      slots: { name: nameHtml },
    });

    expect(sut.html()).toBe(`<span>Hello, ${nameHtml}!</span>`);
  });

  it('prevents code injection', ({ expect }) => {
    const message = mockFn().mockReturnValue(
      `<script>throw new Error('Injected Message');</script>[value]`);
    const maliciousSlotContent = `<script>throw new Error('Injected Slot');</script>`;
    const sut = mount(ParaglideM, {
      props: { inputs: {}, message },
      slots: { value: () => createTextVNode(maliciousSlotContent) },
    });

    // Ensure v-html isn't used to render the slot content directly
    expect(sut.html()).not.toContain('<script>');
  });

  it('prevents regex injection', ({ expect }) => {
    const slotName = '.*';
    const message = mockFn<() => string>().mockImplementation(() => `[start][${slotName}][end]`);
    const sut = mount(ParaglideM, {
      props: { inputs: {}, message },
      slots: { [slotName]: '' },
    });

    expect(sut.html()).toBe(`<span>[start][end]</span>`);
  });

  it('preserves raw input words', ({ expect }) => {
    const inputName = faker.word.noun();
    const message = mockFn<() => string>()
      .mockImplementation(() => `${inputName}[${inputName}]${inputName}`);
    const input = faker.lorem.word();

    const sut = mount(ParaglideM, {
      props: { inputs: {}, message },
      slots: { [inputName]: input },
    });

    expect(sut.html()).toBe(`<span>${inputName}${input}${inputName}</span>`);
  });
});

Notes

• The message content could have been passed directly to the component instead of the message function. However, I was trying to make it forward-compatible with whatever ends up being done to support component interpolation in Paraglide JS. That may or may not be possible with markup placeholders as described in the OP.
• The inputs prop must be required or it will always be optional (even when inputs are required by the message). That's why undefined is passed explicitly in the example.
• The slots names aren't type-safe and the slots specified in the message template aren't required. I'm hoping that can change when component interpolation support is added to Paraglide JS, but I'm unsure how that will work wrt function components.

[matt-winfield]

I've created a similar component for React to allow replacing elements using a similar strategy as proposed in the OP screenshot.

Inspired by @gtbuchanan 's component for Vue, although the implementation/usage is a bit different.

Unfortunately it doesn't have strong typing for the elements (i.e. if you forget to include a tag in the list that is used in the translation it won't throw an error), and I haven't had time to thoroughly test the component. But this seems to work:

ParaglideM Component

import { ComponentType, ElementType, ReactNode } from 'react';

type ParaglideMFunction<TInputs, TOptions> = (
  inputs: TInputs,
  options?: TOptions,
) => string;

type ParaglideMProps<TInputs, TOptions> = {
  message: ParaglideMFunction<TInputs, TOptions>;
  inputs: TInputs;
  options?: TOptions;
  as?: ElementType;
  elements: Record<
    string,
    ComponentType<{
      children: ReactNode;
    }>
  >;
  className?: string;
};

/**
 * @example
 * ```tsx
 * // en.json
 * // { "key": "Hello [+bold]{variable}[-bold]" }
 *
 * <ParaglideM
 *    message={m.key}
 *    inputs={{ variable: "Bob" }}
 *    elements={{
 *      bold: ({ children }) => <strong className="font-semibold">{children}</strong>,
 *    }}
 *  />
 * ```
 */
export const ParaglideM = <TInputs, TLocale>({
  className,
  as: Tag = 'span',
  ...props
}: ParaglideMProps<TInputs, TLocale>) => {
  const message = props.message(props.inputs, props.options);
  const interpolatedMessage = replacePlaceholders(message, props.elements);

  return <Tag>{interpolatedMessage}</Tag>;
};

const replacePlaceholders = (
  message: string,
  elements: Record<string, ComponentType<{ children: ReactNode }>>,
) => {
  const regex = /\[\+(\w+)\](.*?)\[-\1\]/g;

  const parseMessage = (text: string): ReactNode[] => {
    const parts: ReactNode[] = [];
    let lastIndex = 0;

    text.replace(regex, (match, key, content, offset) => {
      // Add text before the match
      if (offset > lastIndex) {
        parts.push(text.slice(lastIndex, offset));
      }

      // Add the React component if the key exists in elements
      const Element = elements[key];
      if (Element) {
        parts.push(<Element key={offset}>{parseMessage(content)}</Element>);
      } else {
        // If no matching element, keep the original text
        parts.push(match);
      }

      lastIndex = offset + match.length;
      return match;
    });

    // Add remaining text after the last match
    if (lastIndex < text.length) {
      parts.push(text.slice(lastIndex));
    }

    return parts;
  };

  return parseMessage(message);
};

Usage

{
  "$schema": "https://inlang.com/schema/inlang-message-format",
  "greeting": "Hello, [+bold]{name}[-bold]"
}

<ParaglideM
  message={m.greeting}
  inputs={{ name: "Bob" }}
  elements={{
    bold: ({ children }) => (
      <strong className="font-semibold">{children}</strong>
     ),
  }}
/>

[aarondoet]

This is the last thing I need for me to switch to inlang. I am currently using my own i18n implementation that I based off of typesafe-i18n, which I was using before. On my Svelte 5 version of it I am using it like this:

{
  "en": {
    "contact": "Feel free to send us <link href='mailto:{email}' text='an email'>!"
  },
  "de": {
    "contact": "Schreib uns gerne <link href='mailto:{email}' text='eine Email'>!"
  }
}

<I18n message={i18n.contact} args={{email: "info@example.com"}}>
  {#snippet link({href, text})}
    <A {href}>{text}</A> <!-- component from component library for default styling, just injecting html won't work for me -->
  {/snippet}
</I18n>

I do not have enough knowledge about inlang, I only tested it a bit and decided it to be better / more comfortable than my own solution, so I don't know how one could achieve this, nor do I want to hack together some weird solution.
The problem I have with solutions like that from @matt-winfield is that the inputs could inject something:

<ParaglideM message={m.greeting} inputs={{name: "[-bold]I don't want a bold name![+bold]"}} elements={{...}} />

[osdiab]

Ive been just inserting a sentinel as the value for a variable in i18n strings, then split the resulting message on the sentinel and render the html where the hole is.

Like

const [before, after] = m["foo"]({ bar: SENTINEL }).split(SENTINEL);
return <>
  {before}<b>the content!</b>{after}
</>;

Can generalize this logic to handle arbitrary replacement of multiple sentinels. It’s jank but on the plus side, no dangerously setting HTML and full freedom of arbitrary react components with type safety (not tied to markup in i18n strings). If the content interpolated in is also an i18n string then it gets complicated to manage, though.

[MCFreddie777]

In Astro, I'm using it like this. Not ideal, using set:html, but since the translations are hardcoded, there is not risk of XSS injection.

  "section_description": "Lorem <strong class=\"font-semibold text-foreground\">ipsum</strong> dolor sit amet.",

<p
    class="text-center text-muted-foreground mb-16 text-lg max-w-3xl mx-auto"
    set:html={m.landing_page_benefits_section_description()}
 />

The only downfall is that templates live among the translations, would be better to pass rendered template inside the translation somehow.

[mklnz]

This is definitely needed, especially for stuff like:

"Please share your <a href="">personalized link</a> in order to invite your friends"

The link may appear in different locations depending on the language...

[osdiab]

Here is my helper React component btw for interpolating react nodes into i18n strings in a more declarative way

import escapeRegExp from 'escape-string-regexp';
import type { ReactNode } from "react";
import { useMemo } from "react";

type StringPlaceholderSlotProps = {
  toInterpolate: string;
  slotContent: Record<string, ReactNode>;
};

/**
 *
 * @param toInterpolate - The string to interpolate content where placeholder
 * names are present
 * @param slotContent - The content to insert into the placeholders, keyed by
 * placeholder names expected to be present in toInterpolate
 * @returns The string, with values interpolated; only the first match of each
 * placeholder is rendered; if a placeholder is not found in slotContent, it
 * will not be interpolated
 */
export function StringPlaceholderSlot({
  toInterpolate,
  slotContent,
}: StringPlaceholderSlotProps) {
  const parts = useMemo(() => {
    const parts: ReactNode[] = [];
    let remainingText = toInterpolate;
    const placeholdersToSearch = new Set<string>(Object.keys(slotContent));

    while (placeholdersToSearch.size > 0) {
      const match = new RegExp(
        `(${[...placeholdersToSearch].map((value) => escapeRegExp(value)).join("|")})`,
      ).exec(remainingText);
      if (match === null) {
        parts.push(<span>{remainingText}</span>);
        break;
      }
      const beforeMatch = remainingText.slice(0, match.index);
      const matchedPlaceholder = match[0];
      const afterMatch = remainingText.slice(match.index + match[0].length);
      parts.push(<span>{beforeMatch}</span>, slotContent[matchedPlaceholder]);
      remainingText = afterMatch;
      placeholdersToSearch.delete(matchedPlaceholder);
    }

    return <>{parts}</>;
  }, [toInterpolate, slotContent]);

  return <>{parts}</>;
}

[osdiab]

and here's a version that actually makes the i18n interpolations typesafe. Intentionally throws away the types in the implementation because it was causing typescript to crawl to a halt with the size of our app; others who don't use radash and nanoid as well as the other utilities could adapt to not use them fairly simply.

import { identity, isPrimitive, objectKeys } from "@breezehr/utilities/object";
import escapeRegExp from 'escape-string-regexp';
import { nanoid } from "nanoid";
import { isEqual, mapValues, objectify, omit } from "radash";
import type { ReactNode } from "react";
import { memo } from "react";
import type { m } from "~gen/paraglide-i18n/messages";
import type { Locale, LocalizedString } from "~gen/paraglide-i18n/runtime";

export type I18nInterpolation<Key extends keyof typeof m> = {
  mFunction: (typeof m)[Key];
  inputs: Record<keyof Parameters<(typeof m)[Key]>[0], ReactNode>;
  options?: { locale?: Locale };
};

/**
 * Interpolates ReactNode content into an i18n localized string.
 *
 * @param i18nKey - The i18n message key to use for localization
 * @param inputs - The content to insert into the i18n message, similar to the
 * first param for the m function, but supports React components instead of just
 * strings. Primitive values are passed directly to the i18n function, while
 * ReactNode values are replaced with placeholders and then interpolated into
 * the rendered output.
 * @param options - Optional localization options (e.g., locale); same as the
 * second param for the m function.
 * @returns The localized string with dynamic values interpolated in
 */
function I18nInterpolationImpl<Key extends keyof typeof m>({
  mFunction,
  inputs,
  options,
}: I18nInterpolation<Key>) {
  const inputsWithoutTypes: Record<string, ReactNode> = inputs;
  const resolvedInputs = objectify(
    objectKeys(inputsWithoutTypes),
    identity,
    (
      key,
    ):
      | { interpolateAsIs: true; contentOrPlaceholder: ReactNode }
      | {
          interpolateAsIs: false;
          contentOrPlaceholder: string;
          toReplaceWith: ReactNode;
        } => {
      const inputValue = inputsWithoutTypes[key];
      if (isPrimitive(inputValue)) {
        return { interpolateAsIs: true, contentOrPlaceholder: inputValue };
      }
      const placeholder = nanoid();
      return {
        interpolateAsIs: false,
        contentOrPlaceholder: placeholder,
        toReplaceWith: inputsWithoutTypes[key],
      };
    },
  );

  // intentionally stripping types to avoid typescript performance issues
  // since m is so huge
  const paramsWithoutTypes: unknown[] = [
    mapValues(resolvedInputs, (value) => value.contentOrPlaceholder),
    options,
  ];
  const mFunctionWithoutTypes: (..._arguments: unknown[]) => LocalizedString =
    mFunction;
  const localizedStringWithPlaceholders = mFunctionWithoutTypes(
    ...paramsWithoutTypes,
  );

  const inputsToReplace = Object.fromEntries(
    Object.entries(resolvedInputs)
      .map(([key, value]) =>
        value.interpolateAsIs ? null : ([key, value] as const),
      )
      .filter(value => value !== null),
  );
  const replacementsByPlaceholder = objectify(
    Object.entries(inputsToReplace),
    ([, value]) => value.contentOrPlaceholder,
    ([, value]) => value.toReplaceWith,
  );
  const parts: ReactNode[] = [];
  let remainingText: string = localizedStringWithPlaceholders;
  const placeholdersToSearch = new Set<string>(
    Object.keys(replacementsByPlaceholder),
  );

  while (placeholdersToSearch.size > 0) {
    const match = new RegExp(
      `(${[...placeholdersToSearch].map((value) => escapeRegExp(value)).join("|")})`,
    ).exec(remainingText);
    if (match === null) {
      parts.push(<span>{remainingText}</span>);
      break;
    }
    const beforeMatch = remainingText.slice(0, match.index);
    const matchedPlaceholder = match[0];
    const afterMatch = remainingText.slice(match.index + match[0].length);
    parts.push(
      <span>{beforeMatch}</span>,
      replacementsByPlaceholder[matchedPlaceholder],
    );
    remainingText = afterMatch;
    placeholdersToSearch.delete(matchedPlaceholder);
  }

  // Add any remaining text after all placeholders have been matched
  if (remainingText.length > 0) {
    parts.push(<span>{remainingText}</span>);
  }

  return <>{parts}</>;
}

export const I18nInterpolation = memo(
  I18nInterpolationImpl,
  (previous, next) =>
    isEqual(
      omit(previous, ["inputs", "options"]),
      omit(next, ["inputs", "options"]),
    ) &&
    isEqual(previous.inputs, next.inputs) &&
    isEqual(previous.options, next.options),
);

you will also need an override of the default React memo() typings because they don't support generics out of box:

// interfaces useful for declaration merging
/* eslint-disable @typescript-eslint/consistent-type-definitions */
/**
 * memo doesn't work by default with inferred generics, this fixes
 * that
 * @see https://github.com/DefinitelyTyped/DefinitelyTyped/issues/37087#issuecomment-937905781
 */

import "react";

declare module "react" {
  // biome-ignore lint/suspicious/noExplicitAny: we want a very general generic
  function memo<T extends ComponentType<any>>(
    Component: T,
    propsAreEqual?: (
      // eslint-disable-next-line unicorn/prevent-abbreviations
      prevProps: Readonly<ComponentProps<T>>,
      nextProps: Readonly<ComponentProps<T>>,
    ) => boolean,
  ): T & { displayName?: string | undefined };
}

[samuelstroschein]

Please give feedback on the RFC on how to implement this in Paraglide JS. Please discuss in #4309

• If there is strong consensus about the proposed API, I can ship markup this week.
• Best to inline comment on the RFC or comment on this github issue

[kmsomebody]

EDIT: Comment moved to #4309 (comment)

---

Purely from a DX standpoint as a React dev, I think option 2 in your list of "Considered alternative APIs" comes closest to what I'd expect. Though what exactly would be the reason for overloading instead of adding the markup parameters to the first argument?

Let's take this message as an example:

"balance": "You have {#tooltip}{amount} coins{/tooltip}."

This message needs the amount parameter and a tooltip function.

Options such as per-message components (<m.balance.Rich/>), a new function (m.balance.rich() or m.balance.parts()) do not make sense to me, because the regular m.balance() function couldn't be used regardless. So that leads me to the question: Why can't I just use the m.balance() function for this too? There is always only one correct way to pass parameters to the message. I think having to use a different function or a component for different types of messages unnecessarily bloats the API. I'd always prefer a single entry point for this.

Suggestion

This suggestion is framework-specific, so the framework adapters would need to extend the compiler. I can only provide feedback for React. I do not know if it's possible to implement the same way for other frameworks.

The idea is to not overload the message function, but to change the type of its inputs and the return type depending on the message.
The return type for messages that do not contain markup placeholders is string. Otherwise, it's a ReactNode.
The input type for regular parameters stays unchanged, but the type for markup parameters is a React component.

Why ReactNode as return type is okay

The message function would only be used with placeholders in places where a ReactNode is expected. If the developer needs a string, they would not be able to use a component anyway, regardless of paraglide's support for it. If a string version and a rich text version are required, they can create two different messages.

Examples

I omitted the optional options parameter here, since it's not relevant.

Markup with children

"balance": "You have {#tooltip}{amount} coins{/tooltip}."

m.balance: (
  inputs: {
    amount: NonNullable<unknown>;
    tooltip: React.ComponentType<{ children: React.ReactNode }>;
  }
) => React.ReactNode;

Markup without children

"balance": "You have {amount} coins{#tooltip/}."

m.balance: (
  inputs: {
    amount: NonNullable<unknown>;
    tooltip: React.ComponentType<Record<never, never>>;
  }
) => React.ReactNode;

No markup

"balance": "You have {amount} coins."

m.balance: (
  inputs: {
    amount: NonNullable<unknown>;
  }
) => string;

This would provide the best DX for me.
No breaking changes and there is still only one message function generated per message.
Does this make sense?