DEV Community

Cover image for i18n Implementation and Best Practices in Strapi
Strapi for Strapi

Posted on • Originally published at strapi.io

i18n Implementation and Best Practices in Strapi

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.

Localization and Internationalization (i18n and L10)

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.

Internationalization vs Localization

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.

Prerequisites

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
    or
    npm run strapi install i18n
Enter fullscreen mode Exit fullscreen mode

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
    or
    npx create-strapi-app@latest my-project --quickstart
Enter fullscreen mode Exit fullscreen mode

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.

Strapi  registration

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 GeneralPlugin to ensure you have the plugin installed in your project.

Installed plugin page

Next, we need to activate this plugin and create new locales. To do this, from the side bar menu, navigate through SettingsInternationalizationAdd 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 localeselect Locale from the dropdownsave.

Adding new locale in strapi

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.

  1. From the dashboard menu, click on Content-type Buildercreate a new collection type.
  2. Enter a display name for your collection type and click Continue. Take note of the API ID field, localhost:1337/api/posts, which contains the API endpoint ID to which your content will be accessed.
    Creating new  collection type in strapi

  3. Next, we need to add fields that will hold content the post content. To do that, click on "Add another field".
    Adding fields to collection type

  4. Select all the necessary fields for the Post collection type. In our case, our Post content type will have the following fields:

  5. Name: This will have a type of string

  6. Body: This will have a type of rich-text

  7. Date: This will have a type of Datetime
    Adding fields to collection type

  8. After adding these fields, click Save, and you should have a Post data type in your project.

  9. Repeat the process in the image above for the rest of the fields.

  10. Save. After saving, we should have a newly created collection type of Post.

Managing Content
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 ManagerPost collection and click on the "Create an entry".

Creating new content

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.

Adding localization content

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 fieldseditadvanced settingdisable Localization.
The images below explain more.

Adding localization content

Click on the pen icon as shown in the image below:

Editing collection type field

Enable localization for the field and click on Finish.

Enable localization for collection type field

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.

Making request to strapi API endpoint

Take a look at the response body, and you will notice that the request returned a forbidden error.
http://localhost:1337/api/posts

 {
        "statusCode": 403,
        "error": "Forbidden",
        "message": "Forbidden"
}
Enter fullscreen mode Exit fullscreen mode

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 settingsrolespermissionapplication.

Setting API Permission

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?

Fetching post with default language

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.

Fetching post in French version

Notice the URL we made the call to localhost:1337/posts?_locale=fr-CA. The /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.

Creating a New Localized Entry

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",
      "locale": "fr-CA"
}
Enter fullscreen mode Exit fullscreen mode

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.

{
      "name": "Oplato",
      "description": "Oplato restaurant description in English"
}
Enter fullscreen mode Exit fullscreen mode

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, localhost:1337/posts.

Create in locale content via API request

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.

Best Practices for Using i18n in Strapi

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.

Strapi is an open-source headless CMS built with Node.js and React.js. You can consume the API with any front-end framework of your choice. It adopts Jamstack (a modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt markup). Check the documentation for more information on Strapi.

Oldest comments (0)