This article explains how to implement internalization in Strapi.
Author: Popoola Temitope
Have you ever visited a site and noticed that it is not in your native language or any language you speak and understand? It could be frustrating and disappointing at the same time. You would likely be left with only two options in those moments: walk away or find a way to translate the site.
Not being able to read the contents of a website due to differences in language is a massive flaw in the user experience. This experience is not what you wish for your users if you are a Strapi admin or own a Strapi website.
Strapi has a solution for this. The i18n localization Strapi plugin shipped together with version 3.6.0 or higher handles this effectively. Here's how to build applications for an International Audience Using Strapi i18n Plugin. Now, let's take a moment to explore the customization of this plugin and some of its best practices.
i18n and L10n are abbreviations for internationalization and localization, respectively. Internationalization and localization are software development techniques that aim to serve content to users in the language they understand without making engineering changes. The process involves translating content into different languages and even restructuring pages to suit users.
Often, localization and internationalization are used interchangeably, but they are not the same. There is a difference between the two terms. The difference is a straightforward one.
Internationalization is the process of developing software with the interests of the international community at heart. It involves making software adaptable to the various languages and regions without making engineering changes, while localization adapts internationalized software to focus on a particular part. I can do this by translating text and adding relevant components specific to a particular local. It is only internationalized software that can localize.
To follow this tutorial properly, you should have:
- Node.js V14.x or V12 installed on your computer. To check your node version, use the node -v command.
- NPM or Yarn is installed on your computer. ## Localization in Strapi
Localization, as with many other site admin responsibilities, has been simplified for Strapi users. To implement localization in a Strapi application, you need to install and properly configure the Strapi i18n plugin.
Strapi applications running on version 3.6.0 or higher do not need to install this plugin as it is shipped with it already. If your application is running on a version of Strapi lower than what we have here, you can consider migrating your application. If you do not know how to, click here. You can also install the plugin using NPM or Yarn commands:
yarn strapi install i18n
npm run strapi install i18n
The i18n Strapi plugin requires some configuration to take effect on the Strapi admin dashboard. Let's explore the steps involved in implementing the i18n plugin.
How to Implement i18n
To properly understand this, we need some hands-on experience. We will get started by creating a new Strapi project using the following command.
Yarn create-strapi-app@latest my-project --quickstart
npx create-strapi-app@latest my-project --quickstart
After a successful installation, Strapi will automatically run and launch the project on your browser, where you will be required to create an admin account.
After successfully creating the account, it should redirect you to your Strapi dashboard. i18n is a Strapi Plugin and can be found on the plugin list page. To view your plugins, from the sidebar menu, navigate through General→Plugin to ensure you have the plugin installed in your project.
Next, we need to activate this plugin and create new locales. To do this, from the side bar menu, navigate through Settings→Internationalization→Add Locale.
Let's add a new locale to test out. I'll add a new French locale. The process is simple. Click on add a locale→select Locale from the dropdown→save.
Note: You can add as many locales as you want for your project.
From the internationalization dashboard, you can delete locales or change the default locale for your project. For this tutorial, we’ll leave the default locale as English.
Create a Collection Type
We need some content to test out localization in Strapi. To continue, let’s create a content type and add some content to it. If you're new to Strapi and don't know how to create a collection type, don't worry. we'll walk you through the process.
To create the Post content type, follow the instructions below.
- From the dashboard menu, click on Content-type Builder→create a new collection type.
Select all the necessary fields for the Post collection type. In our case, our Post content type will have the following fields:
Name: This will have a type of string
Body: This will have a type of rich-text
After adding these fields, click Save, and you should have a Post data type in your project.
Repeat the process in the image above for the rest of the fields.
Save. After saving, we should have a newly created collection type of Post.
We need to create our first post content and then look at creating the same Post in different languages or locales with Strapi. Create a new post content by Navigating through Content Manager → Post collection and click on the "Create an entry".
Enter all the necessary content for each field and save it. After saving it, click on publish. Now, we have successfully created our Post collection content for the default locale (English).
The Strapi development team did so much work, making Localization very easy to achieve. Some of the excellent features they built into it include:
- Easily edit Post.
- Import content from a previous locale into the newly created Locale.
- Some fields can be set not to change no matter the Locale.
- Editing or creating a unique page structure for a particular Locale.
Add Locale Content
Let's explore some of these features above by making our first Post available in French. Click Post→select a post→click edit. On the editing page, locate Internationalization in the right corner and select French.
As shown in the image above, from the left side, select French under locales and fill in the Post's content from the previous Locale, which happens to be English in our case. This way, you can easily edit into the current language you want.
In my case, I used Google Translate to get a French translation of the content of my test post, as you can see in the image above. The main point to note here is that translating your Post into a new language becomes a lot easier with Strapi.
Once you save the Post, it becomes available in English and French, which is fantastic. One more thing you can do is disable localization in parts of the Post that you want to retain the default language.
Editing Field’s Locale
We can edit the Post content type and disable localization for this field. Let's disable localization for the Name field in our Post. Click on Edit the fields → edit → advanced setting →disable Localization.
The images below explain more.
Click on the pen icon as shown in the image below:
Enable localization for the field and click on Finish.
We can further edit the page of our French Local to look unique. We can add features that won't be there in the English locale. I find this very useful.
Using the API
You can leverage the beauty of Localization even when working with Strapi content API. We can fetch content specific to a particular locale and do plenty of other cool stuff with the API.
Let's get right into it. For this tutorial, I will be using Postman to interact with my Strapi application.
Getting Localized Content
Let’s make a request to our Strapi endpoint and fetch all content belonging to the default language. In our case, English is the default language, but If you attempt making this request with Postman at this point, you will get an error with an error message like the one we have below.
Take a look at the response body, and you will notice that the request returned a forbidden error.
This script is a permission error. We need to edit our post collection to accept requests from unauthenticated users for this tutorial. To do that, click the settings→roles→permission→application.
Here, you can choose who should have access. Once more, for this simple tutorial, I will select all.
With this done, let's head over to Postman and make the call again. Now, our request is successful. Did you notice that we fetched the default language of the Post, which is what we wanted?
With the locale API parameter, we can fetch data belonging to a particular locale. You should pass the locale code along with the call as a parameter. The request should be a GET request. With that said, let's try making a call to the endpoint using Postman to fetch all Post in French version.
Notice the URL we made the call to
/post is the endpoint to fetch posts from our Post collection. We added a prefix of _locale which specifies that we want to fetch contents from a particular locale. fr-CA is specifying that we want to fetch Post from the French locale.
We can create a localized entry for a post using the content API. We can do this by sending a Post request to content API. The request should contain a locale parameter that will point to the new Locale we intend to create. The code snippet below is an example of how a localized post request should look.
"name": "She's Cake",
"description": "She's Cake restaurant description in French",
If you requested without the locale parameter, the request would create the Post in the default locale. The code below does not contain a locale parameter. This script will create this Post in English, which is the default locale in our case.
"description": "Oplato restaurant description in English"
With this said, let's get our hands dirty. Let's create a new locale through Strapi API using Postman. We will send our request to the Posts endpoint,
As you can see, we have successfully created a post to a new locale using the API. We have just scratched the surface of how you can leverage Localization using the API. For a more detailed guide on how to carry out localization tasks using the API, click here.
Some best practices that I can recommend when working with Strapi include the following:
- Browse contents by locales.
- Edit pages or posts in locales and switch between them easily.
- Choose what locale should be displayed first.
- Keep the content the same for all locales.
- Handle editors and writers according to locale. ## Conclusion
By now, you should:
- Have a better understanding of localization and internationalization (i18n and L10),
- Be able to implement localization in Strapi from the dashboard and the API respectively, and
- Understand best practices when implementing localization in Strapi.