Introduction

Localization and translations are essential for building a good cross-border e-commerce, we have included some tools to help you with that.

Translations

Much of the content in comes from the API, which already handles translations. However, there's many cases where you want to keep the texts inside the shop repository, or where you want to do some kind of formatting before rendering the text. For this we have a wrapper around the library format-message. The wrapper around format-message is needed to use the correct translations when doing server-side rendering.

When you want to render a translation string you should preferrably use the useIntl hook to wrap your translation strings:

import { useIntl } from "@jetshop/intl";

const App = () => {
  const t = useIntl();

  return <button>{t("This is my translatable button text")}</button>;
};

This will result in a pure text string rendered where you call the function. There are lots of places where we use an older way of rendering translation strings, importing t directly from @jetshop/intl. This works, but is not recommended, since it has some special behaviour that might cause issues in some places.

import t from '@jetshop/intl';

const App = () => {
  return <button>{t('This is my translatable button text')}</button>;
}

// what is actually being rendered
const App = () => {
  return <button><IntlContext.Consumer>{t => t('This is my translatable button text')}</IntlContext></button>
}

In most cases this works well, but if you try to use a translation string inside e.g. a input placeholder, you will end up with broken markup.

You can also work with inline placeholders:

import { useIntl } from "@jetshop/intl";

const App = () => {
  const t = useIntl();
  return <span>{t("Hi {name}! How are you doing?", { name: "User" })}</span>;
};

The ICU Message Format that format-message uses, also support pluralization:

import { useIntl } from "@jetshop/intl";

const App = () => {
  const t = useIntl();
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      {t(
        `{count, plural,
        =0 {You have not pressed the button}
        one {You have pressed the button one time}
        other {You have pressed the button # times}
      }`,
        { count }
      )}
    </button>
  );
};

Finally it's also possible to render your own components for inline styling using t.rich:

import t from "@jetshop/intl";

const Important = ({ children }) => <strong key="important">{children}</strong>;

const App = () => (
  <span>
    {t.rich("This text is <Important>very important!</Important>", {
      Important,
    })}
  </span>
);

Note that this does not work with the useIntl import.

Localization

format-message can also help with formatting text according to local standards, such as date, time, numbers etc. It's basically a wrapper around the built in Intl functions in the browser and can be used either together with translation strings as a part of the ICU message format, or by using the exposed helper functions on its own. See these examples on the format-message documentation.