Software localization

A Quick I18n Tutorial for Spring MVC Apps

Learn all the steps for equipping a Spring MVC web application with internationalization and localization support.
Software localization blog category featured image | Phrase

1. Project Setup

1.1. Dependency

We start by adding spring-webmvcjstl and javax.servlet-api dependencies into our pom.xml file:

















The latest version of all dependencies above can be checked out at Maven Central: spring-webmvc, jstl, javax.servlet-api.

In this article, the versions we use for those dependencies are declared as below:






1.2. WebMvcConfigurer

Next, we will add an implementation of WebMvcConfigurer to enable MVC support:




  (basePackages = { "com.phraseapp.internationalization.mvclocale.controller" })

public class WebConfig implements WebMvcConfigurer {


    public void configureViewResolvers(ViewResolverRegistry registry) {

        registry.jsp("/WEB-INF/pages/", ".jsp");




In the configuration above, we decorate our WebConfig with the @Configuration annotation to state that the class will declare one or more @Bean methods in its body. Spring container will generate bean definition for those beans at runtime.

The @ComponentScan(basePackages = { "com.phraseapp.internationalization.mvclocale.controller" }) will refer to the package where we will implement our controllers later.

We also put the @EnableWebMvc annotation to enable the default configuration for Spring MVC.

Moreover, we override the configureViewResolvers method to register our JSP pages in /WEB-INF/pages/.

1.3. Welcome Page

Now, we will create welcome.jsp page under WEB-INF/pages folder as below:

<!DOCTYPE html>



        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

        <title>Internationalziation in Spring MVC</title>



        Congratulation, your web application has been set up successfully!



Furthermore, we need to implement a Controller which will process the request and return back our welcome page:


public class HomeController {

    Logger log = Logger.getLogger(HomeController.class.getName());

    @GetMapping(value = "/welcome")

    public String welcomePage() {"INTO welcomePage");

        return "welcome";




1.4. WebApplicationInitializer

Up until here, most of the configuration is ready. We will register all our configuration to the ApplicationContext and the ServletContext by implementing the WebApplicationInitializer interface:

public class WebAppInitializer implements WebApplicationInitializer {


    public void onStartup(ServletContext container) {

        AnnotationConfigWebApplicationContext rootContext

          = new AnnotationConfigWebApplicationContext();


        container.addListener(new ContextLoaderListener(rootContext));

        AnnotationConfigWebApplicationContext dispatcherServlet

          = new AnnotationConfigWebApplicationContext();

        ServletRegistration.Dynamic dispatcher

          = container.addServlet("dispatcher",

          (Servlet) new DispatcherServlet(dispatcherServlet));





In the WebAppInitializer class above, we registered our WebConfig to the Application Context. In addition, we also create a simple ServletContext which will handle all incoming requests.

Hence, we can deploy our application on an application server and try to access the welcome page to verify our setup. In this example, we use Tomcat 8.5 at port 8080 for demonstration.

When everything is done properly, consequently we will see below result when access http://localhost:8080/mvclocale/welcome URL:

Successfully set up web app | Phrase

2. Internationalization And Localization

2.1. Message Properties

We begin to add the possibility of supporting multiple languages to our project by declaring a message properties file for each supported language.

The default language will be declared in a file called Let's choose the default language is English. Our file will be like below:

label.welcome = Welcome

label.content = This is sample project for Internalization and Localization in Spring MVC

label.changeLang = Supported languages

label.lang.en = English = French = Chinese = German

As can be seen, the file contains a set of key-value pair. We will use the key to refer to a message in our view later on.

In this article, we will support the displaying of a page in English, Chinese, German and French. Hence, we also need to add a message properties file for the other three languages. To do this, with each specific language, we create a message file in the name, where XX is the locale code of the preferred language.

Therefore, we need to create additional 3 message properties files called: (Chinese), (French) and (German).

Similarly, all the keys which are present in default file should also be available in the specific language message file.

For example, the content of will be like below:

label.welcome = Bienvenue

label.content = Ceci est un exemple de projet pour l'internalisation et la localisation dans Spring MVC

label.changeLang = Langues supportées

label.lang.en = Anglais = Français = Chinois = Allemand

Finally, we will put all message properties files under resources/languages folder.

2.2. MessageResource

Until now, we need to register our message properties files to Spring by declaring a MessageResource bean in our WebConfig :


public MessageSource messageSource() {

    ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();



    return messageSource;


In the declaration above, we create an instance of the ResourceBundleMessageSource as MessageResource bean. Moreover, we register basename as "languages/messages" because we have put all messages properties file under the languages folder.

It's worth to note that Spring will load all the messages properties files content and store in memory. Thus, if in any case, we want to update the messages properties file and expect the changes are updated to the system at runtime, we can consider using the ReloadableResourceBundleMessageSource instead.

2.3. LocaleResolver

Additionally, we need to declare a LocaleResovler bean that helps to identify which locale is being used. Spring provides 4 concrete implementations of LocaleResolver as below:

  • AcceptHeaderLocaleResolver: uses the primary locale specified in the "accept-language" header of the HTTP request
  • FixedLocaleResolver: always return a fixed default locale and optionally time zone
  • SessionLocaleResolver: use the locale attribute in the user session, with a fallback to the specified default locale or the request's accept-header locale.
  • CookieLocaleResolver: persists a custom locale and/or a time zone information as the browser cookie. We use this CookieLocaleResolver in case the application has to be stateless

In this article, we will use the CookieLocaleResolver:


public LocaleResolver localeResolver() {

    return new CookieLocaleResolver();


2.4. LocaleChangeInterceptor

At the same time, we register a LocaleChangeInterceptor to allow specifying the desired locale on every request:


public void addInterceptors(InterceptorRegistry registry) {

    LocaleChangeInterceptor localeChangeInterceptor = new LocaleChangeInterceptor();




The configuration above provides the possibility to choose a specific language for each request via a request parameter lang.

2.5. Using Message In View

Let's create an index.jsp page as below:

<%@ page language="java" contentType="text/html; charset=UTF-8"


<%@ taglib prefix="fmt" uri=""%>

<!DOCTYPE html>



<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">



		<fmt:message key="label.welcome" />



		<span><fmt:message key="label.content" /></span>



		<fmt:message key="label.changeLang" />



		<li><a href="?lang=en"><fmt:message key="label.lang.en" /></a></li>

		<li><a href="?lang=de"><fmt:message key="" /></a></li>

		<li><a href="?lang=fr"><fmt:message key="" /></a></li>

		<li><a href="?lang=zh"><fmt:message key="" /></a></li>




In this file, we use the <fmt:message> tag to map a key to a localized message.

Next, we need a Controller method for this page:

@GetMapping(value = "/index")

public String index() {"INTO index");

    return "index";


At this point, our project structure will be like below:

Project structure | Phrase

2.6. Testing

Accordingly, we can deploy our application and access the index page to see the result:

Project index page in English | Phrase

Click on German to view the page in the German language:

Project index page in German | Phrase

Similarly for Chinese:

3. Conclusion

In this article, we have explored how to set up a Spring MVC Web Application with internationalization and localization support from the beginning.

Basically, we need a MessageResource, a LocaleResolver and LocaleChangeInterceptor to be able to support multiple languages and dynamically switching between languages.

Besides, to be able to update current message files as well as adding new language at runtime we may need to use the ReloadableResourceBundleMessageSource implementation of MessageResource interface, which we cover in our article Database-Stored Messages for I18n in Spring Boot.

Worry not, the whole project can be found on our Github.

All fired up to work with the Spring framework? So are we! Check out our further resources: