Spring MVC Internationalization Tutorial

Internationalization (i18n) is the process of making your application, services capable of delivering in different languages. In this tutorial, we will see how the Spring-Boot framework manages internationalization.


The internet has become global, which implies that any application or website can target millions of users around the world. Although half of the world’s population may have access to the internet today, only about 1/4th of world users are English speakers. This means to expand to new markets, software developers have to develop content in multi-languages.
Internationalization is a basic need for most applications and with Spring Boot it can be achieved in a very simple waySpring boot provides extended support for Internationalization (i18n) through the use of Spring Interceptor, Locale Resolvers, and Resource Bundles for different locales. This article will take you to understand how internationalization can be achieved in Spring Boot.


In this example, I’ll be using the following tools:

  • JDK 1.8
  • Intellij Idea
  • Maven
  • Springboot Application version 2.5.5

Structure of the post :

In addition, the development outline of this blog will be as follow:

  1. Create Spring Boot Web Application
  2. Include Dependencies
  3. Create Configuration beans
  4. Create Controller beans
  5. Multilingual properties
  6. Implement a View
  7. Running the Application

Step1: Create Spring Boot Web Application

Firstly, we create a simple Spring Boot web application.  You can use the Spring Initializr page to create an initial project template.
In this tutorial, we will be using a project with the following metadata.


After importing the project into IDE, we will be creating two sub-packages inside our main package ‘com.appsdeveloperblog.springbooti18n‘ as following:

  • Controller:  This contains class ‘InternationalController‘ with filename ‘InternationalController.java
  • Config:  This contains class ‘InternationalizationConfig‘ with filename ‘InternationalizationConfig.java

In the end, the final project structure will look like this:


We will learn aspects about the config, controller classes in detail in the next section.

Step 2: Include Dependencies

After that, we need to include the following dependencies in our application:
  • Spring Boot Starter Web
  • Spring Boot Starter Thymeleaf 
The source code of  “pom.xml” is as follow:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">


    <description>Spring Boot i18n demo</description>




Step 3: Create Configuration Bean

Spring MVC uses LocaleResolver to extract locale related to web requests and uses this locale object to select appropriate language messages. First, it requires a bean of LocaleResolver. We will discuss this in detail as below:

Locale Resolver

There are many LocaleResolverType provided by spring but the most common areas are below:

Type Explanation
AcceptHeaderLocaleResolver This simply selects Locale from the Accept-Language header sent by the client web browser
CookieLocaleResolver Get locale information using cookies. The setLocale() method stores Locale information in a cookie. Here,
Resolved locale data is persisted as long as cookies are alive
SessionLocaleResolver Get Locale information from the session. The setLocale() method stores Locale information in the session.
Here, Resolved locale data is persisted in a single HTTP session.
FixedLocaleResolver Fixed Locale is used. no setLocale() method


Spring provides various other locale resolvers under the standard package “org.springframework.web.servlet.i18n.
For more details, refer to the following official link:

Let’s understand CookieLocaleResolver and SessionLocaleResolver locale types in detail:


If you use locale object based on the user’s PC or browser settings then, it cannot be changed when the client wants to view the webpage in a different language. Therefore, the Locale setting using Cookie is another option as below. Now, based on user preference we can set the locale in the cookies.  A sample code for locale settings using CookieLocaleResolver is as below:

public CookieLocaleResolver localeResolver() {
  CookieLocaleResolver localeResolver = new CookieLocaleResolver();
  localeResolver.setCookieMaxAge(60 * 60); 
  return localeResolver;


If a user wants to set locale to each individual HTTP session, then SessionLocaleResolver is favored:

public LocaleResolver localeResolver() {
    SessionLocaleResolver localeResolver = new SessionLocaleResolver();
    return localeResolver;

In our example, we will be this “SessionLocaleResolver” for simplicity.


Secondly, we require another bean for interceptor in our class.

LocaleChangeInterceptor is used to change the new Locale based on the value of the language parameter added to a request. This is required when many users call with different locale calls our spring application.
To make this work,  we need to add the LocaleChangeInterceptor in the application’s registry interceptor. The configuration class should extend the WebMvcConfigurer class and override the addInterceptors method.
public LocaleChangeInterceptor localeChangeInterceptor() {
    LocaleChangeInterceptor localeChangeInterceptor = new LocaleChangeInterceptor();
    return localeChangeInterceptor;

public void addInterceptors(InterceptorRegistry registry) {

Complete source code for configuration class “InternationalizationConfig.java” is as below:

package com.appsdeveloperblog.springbooti18n.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
import org.springframework.web.servlet.i18n.SessionLocaleResolver;

import java.util.Locale;

public class InternationalizationConfig implements WebMvcConfigurer {

    public LocaleResolver localeResolver() {
        SessionLocaleResolver localeResolver = new SessionLocaleResolver();
        return localeResolver;

    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor localeChangeInterceptor = new LocaleChangeInterceptor();
        return localeChangeInterceptor;

    public void addInterceptors(InterceptorRegistry registry) {

Step 4: Create Controller

Next, we need the controller to serve our welcome page request. The complete source code for “InternationalController.java” is as below:

package com.appsdeveloperblog.springbooti18n.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

public class InternationalController {
    @RequestMapping(value = "/welcome", method= RequestMethod.GET)
    public String welcome() {
        return "welcome";

    public String home(Model model) {
        return "redirect:welcome";

Step 5: Multilingual Properties Files

The base to have an internationalized application is the language files. In Spring-Boot, we create multi-language message files like messages:

  • properties,
  • messages_es.properties,
  • messages_en.properties, etc
Here, the base name of the file (messages) is followed by the language code. In addition, in case we want to be more specific it can have the country code. Each file contains the key and value pairs. Using this spring identifies each of the texts that are present in many languages.
Important to realize, the key for the same text must be the same in all the files.
For example,
hello  = Hello!!!!!! (message_en.properties)
hello  = Bonjour!!!!!!(message_fr.properties)
hello  = Hallo!!!!!!(message_nl.properties)
hello  = こんにちは!!!!!! (message_jp.properties)

By default, these files have to be in “src/main/resources“. In our example, we created two language files i.e. English, French message properties files.

The French language messages_fr.properties will be as indicated –

welcome.message=Bonjour de appsdeveloperblog.com. C'est un endroit ideal pour apprendre.
language.change=Changer la langue en
language.french= francais

Default language messages.properties and messages_en.properties will be as indicated –

welcome.message=Hello from appsdeveloperblog.com. It's a great place for learning.
language.change=Change language to :
language.french= French

Step 6: Implement a View

To display internationalization messages in Thymeleaf, we simply have to include the message key like this #{key} within a Thymeleaf tag, the most common will be to do it in th:text because it is the most typical to display text, but it can be used in any other tag, such as for example th:value

We will create a webpage within the project’s resources/templates directory.

Here is the source code for “welcome.html

<html xmlns:th="https://www.thymeleaf.org">
<span th:text="#{language.change}"></span>:
<select id="locales">
    <option value=""></option>
    <option value="en" th:text="#{language.english}"></option>
    <option value="fr" th:text="#{language.french}"></option>
<h1 th:text="#{welcome.message}"></h1>
<script type="text/javascript">
      $(document).ready(function () {
          $("#locales").change(function () {
              var selectedOption = $('#locales').val();
              if (selectedOption != '') {
                  window.location.replace('?lang=' + selectedOption);

Step 7: Running the Application

Now, we can create the main class to start the Spring Boot Application:

package  com.appsdeveloperblog.springbooti18n;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

public class SpringBootI18nApplication {

    public static void main(String[] args) {

        SpringApplication.run(SpringBootI18nApplication.class, args);

In the end, we will run our application either via executing the following command or using the ‘Run’ button from IDE. You will find that the application started on Tomcat port 8080.

mvn spring-boot:run

Once the application started, go to the browser and open the following URL.


It will redirect to the welcome page which is created in step 6.


Thereafter, based on the language selected from the dropdown the page is automatically updated with the selected language.

For example, the French page is as below


Exceptions with Locale Messages

To this end, we may also use the support of Spring Boot Internationalization to provide local exception messages or information messages.

In the file messages.properties and other locale-specific files, we can define our error or information messages. Once the application encounters an error, Spring Boot will pick respective locale messages and construct the error message itself, based on available locales.

For example, messages_en.properties

innboundrequest.200="Invalid inbound message payload."
innboundrequest.201="Unknown inbound message attribute {0}."
innboundrequest.202="Unknown attribute value {0} for Request ID {1}."
innboundrequest.203="Inbound message missing."


innboundrequest.200="Donn\u00E9es utiles de message entrant non valides"
innboundrequest.201="Attribut {0} de message entrant inconnu"
innboundrequest.202="Valeur d'attribut inconnue {0} pour l'ID de demande {1}"
innboundrequest.203="Message entrant manquant"


In general, if your application serves many different clients around the world, it is important that the application is able to respond based on the country and language. In this post, we learned how Spring-Boot provides out-of-box support for internalization. This makes our applications more intuitive and understandable for global users.

Happy Learning!

Leave a Reply

Your email address will not be published. Required fields are marked *