A Step-by-Step Guide to i18n in Spring WebFlux

One of the new features in Spring 5 is reactive web development supported by Spring WebFlux. In this article, we will explore how to configure a web application with internationalization and localization support in Spring WebFlux.

In our previous blog posts, we have already talked about how to implement internationalization with Spring Boot and Spring MVC. In this guide to i18n in Spring WebFlux, we will create a web application with internationalization and localization support in Spring WebFlux. First, we will go through all basic steps to bring up a simple web application with Spring Boot 2.0 and Spring WebFlux. Furthermore, we will add the necessary configuration to support internationalization and localization. Besides, we will use Thymeleaf as template engine. Hence, we expect the reader has basic knowledge of Maven, Spring Boot, Spring WebFlux, and Thymeleaf.

Project Setup

Let us go over the basics of setting up our project to get things rolling…


First of all, we declare our project parent in pom.xml to spring-boot-starter-parent. Then, we add dependencies for Spring WebFlux and Thymeleaf as below:

In fact, the latest Spring Boot version can be found over on Maven Central.

Meanwhile, please note that we use Java 9 in this article. Hence, the declaration is as below:


We create a WebConfig class and decorate it with @Configuration annotation as below:

In the above code, the WebConfig implements the ApplicationContextAware to allow us getting access to the ApplicationContext. Moreover, we also need to implement the WebFluxConfigurer as this will make it possible for us to register our ViewResolver later.

Additionally, we decorate the class with @EnableWebFlux annotation. This will enable the use of annotated controllers and functional endpoints. However, only one @Configuration class should have the @EnableWebFlux annotation.

Using Thymeleaf As Template Engine

Thymeleaf, as a modern server-side Java template engine that emphasizes natural HTML templates, offers a reactive-friendly way to integrate with Spring 5 WebFlux:

As we can see here, we need a Template Resolver, a Template Engine, and a View Resolver as the necessary settings.

For instance, we use SpringResourceTemplateResolver as the implementation of Template Resolver. This is where we specify the location of our template files and the file extension. In this article, our templates will be in HTML format.

After that, we assign that Template Resolver to a Template Engine which is the SpringWebFluxTemplateEngine. Similarly, the Template Engine is referred to by a View Resolver which is the ThymeleafReactiveViewResolver here.

Eventually, we register our View Resolver to Spring by overriding the configureViewResolvers method of the interface WebFluxConfigurer.

Next, we can put a sample index.html file under resources/views as our template. The file content is:

Handler and Router

Until here, we can create a WelcomeHandler which will return the index.html template:

In Spring WebFlux, we need a Router to route a request to the corresponding handler. Let’s create a WelcomeRouter as below:

As a result, the request comes to /index, will be handled by WelcomeHandler.hello method.

Running the Application

At this point, we add below class to be able to run our Spring Boot application:

Now run our application and access the server at http://localhost:8080/index. We will see the following result:

I18n in Spring WebFlux

We’ve now reached the point at which we can start implementing i18n and l10n…

MessageSource Config

To support multiple languages in our project, we need to declare a message properties file for each of the supported languages.

Let’s add a messages.properties under resources/languages to serve the default language:

Additionally, we can add messages_de.propertiesmessages_fr.properties and messages_zh.properties. This will add the ability to support German, French and Chinese languages.

Meanwhile, we can see that a message properties file contains a set of key-pair values. We will use the key to refer to the desired message in our view later.

Afterward, we need to tell Spring where we put our message properties files. Therefore, we declare a MessageSource bean in our WebConfig as below:

Custom LocaleContextResolver

There are two implementations of LocaleContextResolver available:

  • AcceptHeaderLocaleContextResolver: uses the primary locale specified in the “Accept-Language” header of the HTTP request. This is the default one.
  • FixedLocaleContextResolver: always returns a fixed locale and optionally time zone

In this article, we will try to implement a custom LocaleContextResolver. The purpose of it is to resolve the locale from a request parameter:

Furthermore, we need to tell Spring to use our implementation as the LocaleContextResolver. Hence, we add a configuration class which extends the DelegatingWebFluxConfiguration class. Then, we will override the method createLocaleContextResolver to return our custom implementation:

Welcome Page

Up until here, we have everything ready for the configuration. Let’s create a welcome.html template as below:

The above template uses Thymeleaf syntax to render localized messages. Indeed, the real message will be chosen at runtime based on the selected locale.

In addition to this, we also need to update our WelcomeHandler and WelcomeRouter to use this template:


Altogether, our project is ready for final testing. Let’s start the application and access http://localhost:8080/welcome:

Then, click on French anchor. What you will see:

That being the case, we have successfully set up a Spring WebFlux project with I18N support.


Let’s summarize what we have done in this article.

At first, we have brought up a Spring WebFlux project which uses Thymeleaf as Template Engine. Subsequently, we added internationalization and localization support to the project by using message.properties, MessageResource and LocaleContextResolver.

Regardless of the two available implementations of LocaleContextResolver, we have tried to implement a custom RequestParamLocaleContextResolver. Therefore, we can change the application locale by changing the request parameter.

Finally, we can find the whole implementation of this article on our Github.

(Visited 7 times, 1 visits today)
A Step-by-Step Guide to i18n in Spring WebFlux
4.6 (92%) 5 votes