Use with localization frameworks

Plasmic supports integration with popular localization frameworks like Lingui, react-intl, or react-i18next.

This works with both codegen and the Headless API.


1. Enable localization in your project

First, open the project you want to test, click on the ellipsis menu by the name of the project on the top-left corner, and select “Enable localization for this project” and press Confirm. Turning it on will effectively change codegen to wrap all text blocks in a wrapper component for localization.

(Notice it doesn’t affect previously published versions of the project.)

2. Provide a translation function

Then, pass a translation function _t to the translator prop of PlasmicRootProvider to be used by the wrapper component (assuming you’re using Headless API).

This function implementation may change a little bit depending on which framework you’re using. For example, if you’re using Lingui, it could look like this:

import { i18n } from '@lingui/core';
import { Trans, I18nProvider } from '@lingui/react';
export const _t: PlasmicTranslator = (key, opts) => {
if (opts?.components) {
return <Trans id={key} components={opts.components} />;
} else {
return i18n._(key);

3. Generate strings for translators’ workflow

To generate all possible messages, we added a new sub-command localization-strings to the Plasmic CLI. A quick example if you want to write those messages to a file ./locale/en/plasmic_messages.po:

plasmic localization-strings --projects PROJECTID --format po -o locale/en/plasmic_messages.po

That’s all there is to it! Read on for a deeper understanding of how Plasmic integrates with these localization frameworks.

Background on localization frameworks

The three top localization frameworks are:

react-i18next is the most popular:

They mostly work the “same” way:

  • At run time, some global provider provides a big dictionary of key to translated string for the current locale.
  • In code, localizable strings are wrapped in some function or React component.
  • At run time, these functions or components use the global dictionary to look up and output the translated string.
  • There are some extraction tools that can extract the localizable strings from source code by looking for their special wrapper functions and components. Some do rather extensive code transformations as well.
  • There are some schemes for localizing for plurals, dates, and numbers as well.

These “translation function / components” (often called t() and <Trans/>) therefore serve at least two purposes:

  • At build time, extracting strings that are translatable. The functions must receive the string key, as well as the “default” string value (say, english). If a string key is omitted, the default string value is often just used as the key.
  • At run time, swapping in the localized strings. The functions must receive the string key, as well as any run-time values for interpolation or figuring out which plural form to use, etc. Note that the “default string value” is not needed at run time, as the dictionary is used, and including the default string value here would be a waste; some frameworks (like lingui) therefore may transform the source files and exclude the default string values at build time.

How localization happens with Plasmic

Localizable strings can currently show up as rendered React elements. These are text elements in Plasmic designs.

In the last section we described there being both build-time and run-time steps to localization. Especially for the Plasmic Headless API, because there’s no “build time” where our source files are processed by a build system, there’s no one who will be doing string extraction or source transformation for us. Therefore, at least for loader, we provide the localizable strings via API, so you can merge them with your existing dictionaries.

Give feedback on this page