A React I18n Experiment with Storybook and i18next
In this step-by-step tutorial, we will learn how to localize a React component in a Storybook-based project. We will introduce you to the i18next library, set up our demo project, localize the component, and add further configurations as needed.
We assume you have prior experience with React, Storybook, and i18next. Otherwise, you can review the excellent official React documentation, go through our own tutorial on React i18next localization, and we will briefly cover Storybook. Let’s begin!
A brief introduction to Storybook and i18next
Now is a good time to introduce you to the other libraries and start with the demo component code.
Libraries we will be using
We will be using the following NPM packages (with the version number in parentheses):
- React (18.1.0)
- i18next (21.9.1)
- react-i18next (11.18.5)
- i18next-browser-languagedetector (6.1.5)
- storybook-react-i18next (1.1.2)
- TailwindCSS (3.0.24)
Our demo: Pricing plan component
We will be building this small pricing plan component and use Storybook and i18next localization to understand how to write a story for this React component. Here’s what it looks like:
As you can see, it is a card layout with a “Most Popular” tag, plan name, description, pricing, and a CTA button. While in Storybook, we will be able to easily switch between different localization variants of the same card. With that in place, it’s time to start writing some code. Let’s begin!
We will be starting from scratch, so let’s spin off a new React app using the Create React App command:
After the new app is created in your favorite directory, let’s remove all the boilerplate code we have inside the App.js file with the following:
Here we just want to render the PricingPlan component, which we have imported above. The next obvious thing is to write the JSX for the pricing plan component card. So, we make this PricingPlan.jsx file inside a new /components directory with the following code:
🗒️ Note » You can access the full source code (along with the Tailwind CSS class styles) in our repo here.
Next, let’s add Storybook to the mix so that we isolate this component and start writing our first story!
How do I install and setup Storybook?
As we already have our React app running, let’s open a new tab in our terminal window and execute the following command to use the Storybook CLI inside our existing project’s root directory:
Storybook CLI will look into our project’s dependencies while it installs and provides us with the best configuration available.
🗒️ Note » If you run NPM version 8.2.0, the CLI will automatically prompt you to run its ‘npm7’ migration on your project. This will add a tiny .npmrc file at the root of your project with
legacy-peer-deps=true, so it’s completely safe to proceed with accepting this suggestion. More about this issue can be found on their GitHub.
That should be it for installation. It’s now time to take a look at our Storybook window! Let’s go ahead and run the following command to start Storybook locally in our app:
npm run storybook
This will automatically open a new browser tab/window, and you should see a Storybook window. Good work!
Writing our first story
A story is a function that returns a component’s state with some optionally provided arguments (
args). Typically, we write stories in a story file alongside our component file, and this isn’t included in our production bundle. Let’s start by creating a new story file inside the src/components folder and call it PricingPlan.stories.jsx with the following code:
This is called the default export of a story. This metadata controls how Storybook lists your stories and provides information used by add-ons.
Before you start running Storybook, make sure you have imported your CSS styles in the preview.js file:
Now start the Storybook process to see our pricing plan component on the canvas.
How do I use i18next to localize a React component?
We have successfully created our own story for the component, but now the crucial part is localizing it. We want our component to be rendered in the default user device’s language, say English (‘en’) but also in Spanish (‘es’) in Storybook.
Our app will use the
react-i18next packages. The latter gives us the required components, Hooks, and plugins on top of
i18next. Let’s install both of them in our project:
After the installation, we need to add a configuration file called i18n.js inside our /src folder. This file will bootstrap an i18n instance.
Let’s import this config file into our root index.js:
Now we are all ready to use our i18n configurations in the component. For starters, let’s just try to display our
component_name using i18next’s
t() function of the
If you check your running app, you should see a new heading, ‘Pricing Plans’ in English, above the pricing plan card.
To see the translation in action, let’s switch the active language to Spanish in our config file:
When the app reloads, you should see “Planes de precios” as the heading. Fantastic, we just processed our first localization!
Let’s update the code in your component JSX with the t() function:
Now when you try changing the active language from
en you should see the correct translation file being loaded asynchronously, and that it’s getting the required translation values. While we have now localized our component, we also need to include this in Storybook, where we can manually select the required translation language. Let’s see how.
How do I set up the react-i18next Storybook add-on?
Storybook comes with a good amount of add-ons that unlock advanced features and new workflows as needed. In our app, we will be using the Storybook react-i18next add-on, which allows us to easily add react-i18next support to Storybook. It adds a globe icon in the Storybook toolbar from where we can easily choose a language via a dropdown which we will be able to customize.
Let’s add it to our project:
Next, let’s enable this plugin so that Storybook recognizes it and loads when it starts its instance by inserting this in our addons array of the main.js file:
Finally, we will need to add some
locale parameters along with the exported
i18n configuration in the preview.js file:
locale is what we want our default locale to be, i.e., our default translation will be
en for English. On the other hand,
locales is an object where we put all the translation languages included in our app.
title is the string we want to display in the dropdown. We can add an optional value that will appear
left of the title in the dropdown. This is useful when we want to add an emoji flag, for example.
After we have correctly configured the plugin, we are ready to go! Let’s kill the running Storybook server and start it again. When the browser tab opens, you should see a globe icon in the toolbar, and when you click on it, it will show a dropdown with the
locales we defined above.
Additional configuration with react-i18next add-on
The react-i18next add-on also provides other ways to configure your locale parameters. We can use full region-based locale strings as keys, given that we have configured our i18n properly to something like this:
We also get the right key value to go alongside the title key:
Ready to take localization to the next level?
We truly hope you enjoyed building this project with us and got to learn how useful Storybook’s add-ons can be, and how powerful the i18next package is.
If you’re ready to level up your software localization process, let the Phrase Localization Suite do the heavy lifting.
With its dedicated software localization solution, Phrase Strings, you can manage translation strings for your web or mobile app more easily and efficiently than ever.
With a robust API to automate translation workflows and integrations with GitHub, GitLab, Bitbucket, and other popular software platforms, Phrase Strings can do the heavy lifting for you to stay focused on your code.
Phrase Strings comes with a full-featured strings editor where translators can pick up the content for translation you had pushed. As soon as they’re done with translation, you can pull the translated content back into your project automatically.
As your software grows and you want to scale, our integrated suite lets you connect Phrase Strings with a cutting-edge translation management system (TMS) to fully leverage traditional CAT tools and AI-powered machine translation capabilities.
Check out all Phrase features for developers and see for yourself how they can streamline your software localization workflows from the get-go.
Take your software global without any hassle
Adapt your web or mobile app, website, or video game for global audiences with the leanest, fastest, and most realiable software localization platform.
Last updated on September 15, 2023.