Microsphere Internationalisation

Microsphere Projects for Internationalisation

Microsphere Internationalisation is a comprehensive i18n framework for Java applications, with deep integration into the Spring ecosystem. It provides a modular, extensible architecture for managing localized messages across deployment scenarios ranging from standalone Spring applications to distributed, cloud-native microservices.

Table of Contents

• Features
• Modules
• Requirements
• Getting Started
  • Add the BOM
  • Spring Applications
  • Spring Boot Applications
  • Spring Cloud Applications
  • OpenFeign Integration
  • Centralized I18n Server
• Message Files
• Configuration Properties
• Actuator Endpoint
• Building from Source
• Getting Help
• Contributing
• License

Features

• Layered message sources — load localized messages from classpath properties files, Spring Environment, or external configuration systems, all through a unified ServiceMessageSource abstraction.
• Composite sources with priority ordering — combine multiple message sources via CompositeServiceMessageSource; higher-priority sources shadow lower-priority ones.
• Dynamic configuration — Spring Cloud integration enables runtime message updates without application restarts.
• Spring MessageSource bridge — the primary ServiceMessageSource bean is automatically exposed as Spring's MessageSource, so it works transparently with @Value, Thymeleaf, and other Spring facilities.
• Bean Validation integration — i18n-aware LocalValidatorFactoryBean translates constraint violation messages through the same source.
• OpenFeign propagation — an Accept-Language request interceptor automatically forwards the current locale to downstream Feign clients.
• Actuator endpoint — read and write i18n messages at runtime through /actuator/i18n.
• Centralized i18n server — serve consolidated message bundles across microservices via a dedicated Spring Cloud server module.

Modules

Module	Purpose
microsphere-i18n-parent	Defines the parent POM with dependency management and Spring Cloud version profiles
microsphere-i18n-dependencies	Centralizes dependency management for all project modules
microsphere-i18n-core	Provides fundamental i18n abstractions and message source implementations
microsphere-i18n-openfeign	Propagates the current locale to downstream OpenFeign clients
microsphere-i18n-spring	Integrates with Spring Framework's MessageSource and Environment
microsphere-i18n-spring-boot	Auto-configuration and Actuator endpoint
microsphere-i18n-spring-cloud	Dynamic configuration updates via Spring Cloud config
microsphere-i18n-spring-cloud-server	Centralized i18n management server

Requirements

• Java 17 or later
• Spring Framework 6.x (for the microsphere-i18n-spring module and above)
• Spring Boot 3.x (for the microsphere-i18n-spring-boot module and above)
• Spring Cloud 2022.0.x – 2025.0.x (main branch) or Hoxton – 2021.0.x (1.x branch)

Getting Started

Add the BOM

Import the Bill of Materials into your pom.xml to manage all module versions centrally:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.microsphere-projects</groupId>
            <artifactId>microsphere-i18n-dependencies</artifactId>
            <version>${microsphere-i18n.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Choose the version that matches your Spring Cloud generation:

Branch	Compatible Spring Cloud	Latest Version
main	2022.0.x – 2025.0.x	0.2.13
1.x	Hoxton – 2021.0.x	0.1.13

Spring Applications

Add the Spring integration module and enable i18n support with @EnableI18n:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-i18n-spring</artifactId>
</dependency>

@EnableI18n(sources = {"common", "myapp"})
@Configuration
public class I18nConfig {
}

Inject and use ServiceMessageSource anywhere in your Spring beans:

@Service
public class GreetingService {

    @Autowired
    private ServiceMessageSource messageSource;

    public String greet(String name) {
        // Resolves "hello" from the message files for the current request locale
        return messageSource.getMessage("hello", name);
    }
}

Spring Boot Applications

Add the auto-configuration module — no @EnableI18n annotation required:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-i18n-spring-boot</artifactId>
</dependency>

The auto-configuration activates when microsphere.i18n.enabled=true (the default). Set spring.application.name to automatically register an application-specific message source alongside the default common source:

spring.application.name=myapp
microsphere.i18n.enabled=true

Spring Cloud Applications

Add the Spring Cloud module for dynamic message refresh without application restarts:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-i18n-spring-cloud</artifactId>
</dependency>

Message sources are automatically refreshed when Spring Cloud configuration change events are received, so updating messages in a config server takes effect immediately across all instances.

OpenFeign Integration

Add the OpenFeign module to propagate the current request locale to downstream services:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-i18n-openfeign</artifactId>
</dependency>

AcceptLanguageHeaderRequestInterceptor is registered automatically. It adds an Accept-Language header to every Feign request so that downstream services resolve messages in the caller's locale.

Centralized I18n Server

Stand up a dedicated server that aggregates and serves message bundles for all microservices:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-i18n-spring-cloud-server</artifactId>
</dependency>

Annotate your Spring Boot application class:

@EnableI18nServer
@SpringBootApplication
public class I18nServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(I18nServerApplication.class, args);
    }
}

The server exposes a GET /messages endpoint that returns all registered message bundles as JSON.

Message Files

Place message properties files under META-INF/i18n/<source>/ on the classpath. The naming convention is i18n_messages_<locale>.properties:

src/main/resources/
└── META-INF/
    └── i18n/
        ├── common/
        │   ├── i18n_messages_en.properties
        │   └── i18n_messages_zh_CN.properties
        └── myapp/
            ├── i18n_messages_en.properties
            └── i18n_messages_zh_CN.properties

Message values use {} as the positional placeholder:

# i18n_messages_en.properties
hello=Hello, {}
error.notFound=Resource '{}' was not found

# i18n_messages_zh_CN.properties
hello=您好，{}
error.notFound=资源"{}"未找到

Retrieve a message with arguments at runtime:

// Resolves to "Hello, World" or "您好，World" based on the current locale
String msg = messageSource.getMessage("hello", "World");

Configuration Properties

All properties are prefixed with microsphere.i18n.:

Property	Type	Default	Description
microsphere.i18n.enabled	boolean	true	Enables or disables the i18n framework
microsphere.i18n.sources	String[]	—	Additional message source names to register (e.g., common,myapp)
microsphere.i18n.default-locale	Locale	JVM default	Default locale used when no request locale is available
microsphere.i18n.supported-locales	String[]	—	Comma-separated list of supported locales (e.g., zh_CN,en)

Actuator Endpoint

When Spring Boot Actuator is on the classpath, the /actuator/i18n endpoint is registered automatically (requires management.endpoints.web.exposure.include=i18n or *).

Method	Path	Description
GET	/actuator/i18n	List all localized messages grouped by resource file
GET	/actuator/i18n/{code}	Get all locale variants of a single message code
POST	/actuator/i18n	Add or overwrite a message at runtime

Building from Source

You don't need to build from source to use the project. To build for development or to try the latest unreleased changes:

1. Clone the repository:

git clone https://github.com/microsphere-projects/microsphere-i18n.git
cd microsphere-i18n

2. Build and run tests:

• Linux / macOS:

./mvnw verify

• Windows:

mvnw.cmd verify

Getting Help

• Documentation:
  • DeepWiki
  • ZRead
  • GitHub Wiki
  • Developer Guide
• JavaDoc:
  • microsphere-i18n-core
  • microsphere-i18n-openfeign
  • microsphere-i18n-spring
  • microsphere-i18n-spring-boot
  • microsphere-i18n-spring-cloud
  • microsphere-i18n-spring-cloud-server
• Bug reports / feature requests: GitHub Issues — please search existing issues before opening a new one and include as much detail as possible.

Contributing

We welcome contributions of all kinds. Please read the Code of Conduct before submitting a pull request.

Maintainer: Mercy Ma (@mercyblitz) — lead architect and primary developer.

License

Microsphere Internationalisation is released under the Apache License 2.0.