Localize your application

Respond to a localized version of your application with LocalizedMessageSource.

Authors: Sergio del Amo

Micronaut Version: 4.6.3

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

2. What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=graalvm \
    --build=gradle \
    --lang=java \
    --test=junit

If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add graalvm features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Properties

Create a default messages.properties file:

src/main/resources/i18n/messages.properties

hello.world=Hello World

Create a messages_es.properties file for Spanish locale:

src/main/resources/i18n/messages_es.properties

hello.world=Hola Mundo

4.2. Message Source

Create a MessageSource that uses the previous properties files:

src/main/java/example/micronaut/MessageSourceFactory.java

package example.micronaut;

import io.micronaut.context.MessageSource;
import io.micronaut.context.annotation.Factory;
import io.micronaut.context.i18n.ResourceBundleMessageSource;
import jakarta.inject.Singleton;

@Factory (1)
class MessageSourceFactory {
    @Singleton (2)
    MessageSource createMessageSource() {
        return new ResourceBundleMessageSource("i18n.messages");
    }
}

1	A class annotated with the `@Factory` annotated is a factory. It provides one or more methods annotated with a bean scope annotation (e.g. `@Singleton`). Read more about Bean factories.
2	Use `jakarta.inject.Singleton` to designate a class as a singleton.

4.3. Controller

src/main/java/example/micronaut/HelloWorldController.java

package example.micronaut;

import io.micronaut.context.LocalizedMessageSource;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;

import java.util.Optional;

@Controller (1)
public class HelloWorldController {

    private final LocalizedMessageSource messageSource;

    public HelloWorldController(LocalizedMessageSource messageSource) { (2)
        this.messageSource = messageSource;
    }

    @Produces(MediaType.TEXT_PLAIN) (3)
    @Get (4)
    Optional<String> index() { (5)
        return messageSource.getMessage("hello.world"); (6)
    }
}

1	The class is defined as a controller with the @Controller annotation mapped to the path `/`.
2	Use constructor injection to inject a bean of type `LocalizedMessageSource`.
3	Set the response content-type to `text/plain` with the `@Produces` annotation.
4	LocalizedMessageSource contains methods to fetch a message with a code, a default message, or variables.

4.4. Tests

src/test/java/example/micronaut/HelloWorldControllerTest.java

package example.micronaut;

import io.micronaut.http.HttpHeaders;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

@MicronautTest (1)
class HelloWorldControllerTest {

    @Inject
    @Client("/") (2)
    HttpClient httpClient;

    @Test
    void useOfLocalizedMessageSource() {
        BlockingHttpClient client = httpClient.toBlocking();
        HttpRequest<?> request = HttpRequest.GET("/")
                .header(HttpHeaders.ACCEPT_LANGUAGE, "es"); (3)
        assertEquals("Hola Mundo", client.retrieve(request));
        request = HttpRequest.GET("/");
        assertEquals("Hello World", client.retrieve(request));
    }

}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
2	Inject the `HttpClient` bean and point it to the embedded server.
3	Creating HTTP Requests is easy thanks to the Micronaut framework fluid API.

5. Testing the Application

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

6. Learn More

The application changes the locale with the Accept-Language HTTP Header. Learn more about Locale Resolution.

7. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…).

Table of Contents