Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
Magnolia's internationalization (i18n) API changed in version 5.1. This page explains the differences between the old and new APIs.
Read first Internationalization basics and Translatable text to understand the concepts. On this page we focus on translatable text stored in message bundles.
Summary
Magnolia 5.1 introduced a new i18n API with new concepts and classes. The new classes are in a Maven module magnolia-i18n which is a sub-module of the main magnolia-project. The base package is info.magnolia.i18nsystem.
The old API that was used before Magnolia 5.1 has not been discarded. In some cases such as template labels you still have to use old i18n mechanism since the new mechanism does not cover all use cases. The classes of the old API are part of the Magnolia core module. The base package is info.magnolia.cms.i18n.
| New API | Old API | |
|---|---|---|
| Magnolia version | 5.1+ | 5.0.4 and earlier |
| Maven module | magnolia-i18n | core |
| Base package | info.magnolia.i18nsystem | info.magnolia.cms.i18n |
| Bundle location | mgnl-i18n | mgnl-i18n or another folder |
| Basename | Not needed | Mandatory |
Message bundles
You can use the new and the old API to access resources from message bundles. However, use the new API whenever possible.
Bundle location
New: Store your message bundles in the /mgnl-i18n folder in your project. Within the Maven project structure this folder is in <module name>/src/main/resources/mgnl-i18n.
Old: Bundles can be stored in many locations. Some Magnolia modules still store message bundles outside the mgnl-i18n folder. The most prominent example is the Standard Templating Kit bundle with basename info.magnolia.module.templatingkit.messages. You can store bundles in other locations. The old mechanism still works. You must use the old API in internationalization of texts in Freemarker and JSP template scripts.
Whenever you use old i18n API and basenames, put your message files outside the /mgnl-i18n/ folder in a location that reflects the meaning of the message bundle in your project.
Example: src/main/resources/info/magnolia/module/templatingkit/
Bundle loading
New: Message bundles are loaded in the same order as modules. The new i18n mechanism loads bundles automatically during module startup as long they are in the mgnl-i18n directory. All bundles that reside in mgnl-i18n folder from all modules are virtually merged into one big bundle which is used by the new i18n API.
Keys in message files in the mgnl-i18n folder must be unique throughout all files in that directory. Organize your bundles and keys in a way that does not rely on the bundle loading order.
Old:
Make sure that message keys within one bundle are unique. Bundles were not merged into a big virtual bundle in the old API, they were independent. So you could have identical keys in two different bundles.
Basename
New: When accessing messages from bundles in mgnl-i18n with the new API you do not have to provide a basename in configuration or Java code. This is a pattern you find across the system.
Old: The old i18n API requires that you provide a basename.
Overview
Content Tools