spring-boot-i18n

Spring Boot I18N Engine

Naming Conventions

• Name message-source component classes with the *Messages or *LogMessages suffix (e.g., ApplicationMessages, UserLogMessages).
• Use the *LogMessages suffix explicitly for log-event resolution components (e.g., PaymentLogMessages, OrderLogMessages).
• Use domain-specific component names (never Messages, AppMessages, or LogMessages without a domain prefix).

Rules

• Set spring.messages.basename=i18n/messages in application.yml.
• Set spring.messages.encoding=UTF-8 in application.yml.
• Place message bundles under src/main/resources/i18n/; name locale variants messages.properties, messages_pt_BR.properties, etc.
• Use UTF-8-safe content in all message bundle files.
• Use # Section Name comments inside .properties files to group keys by namespace.
• Keep key naming stable and domain-oriented.
• Use the error.validation.* namespace for Bean Validation constraint messages.
• Use the error.* namespace for domain errors; keep error text only in the bundle.
• Use the api.* namespace for API response messages.
• Use the openapi.* namespace for API documentation strings.
• Use the log.* namespace for log-event messages.
• Keep placeholders indexed and consistent across all locale variants.
• Keep identical key sets across all locale variants; add every new key to all locale files simultaneously.
• Use Accept-Language as the default locale negotiation strategy for API and web flows.
• Use en and pt-BR as baseline defaults unless the project explicitly defines a different supported locale set.
• Resolve all user-facing text in Java classes through message keys.
• Declare each *LogMessages component as a public class annotated with @Component.
• Place each *LogMessages component in an i18n sub-package of the module root or owning feature.
• Place a module-root *LogMessages component (e.g., AppLogMessages) in <root-package>.i18n when the component is consumed by cross-cutting shared classes such as @RestControllerAdvice or @ControllerAdvice.
• Use feature-scoped *LogMessages components (e.g., HolidayLogMessages in holiday.i18n) only when the component is consumed exclusively within that feature.
• Use dedicated *LogMessages components backed by MessageSource with Locale.ENGLISH for log events.
• Expose a get(String key, Object... args) method on each *LogMessages component that resolves messages with Locale.ENGLISH.
• Expose a get(Locale locale, String key, Object... args) overload on each *LogMessages component for caller-specified locale resolution.
• Keep the locale-aware overload signature fixed as get(Locale locale, String key, Object... args).
• Implement get(String key, Object... args) by delegating to get(Locale.ENGLISH, key, args).
• Keep messages_pt_BR.properties entries written in natural Portuguese with correct orthography and diacritics.
• Add log.* keys only when the same change wires those keys through a *LogMessages component used by application code.
• Add openapi.* keys only when the same change includes an OpenAPI component governed by a component-creation rule.
• Add error.validation.* and error.* keys only when the same change includes the controller or service component that produces those validation errors or domain failures.