Last updated Jul 8, 2024

I18N architecture

This document sheds some light on how Confluence looks up a message text from one of the resource bundles.

Loading of Resources

Currently the only implementation of the I18NBean interface is the DefaultI18NBean. When it is instantiated, it attempts to load resources from the following locations:

  1. Load /com/atlassian/confluence/core/ and / and create a CombinedResourceBundle containing both of them.

  2. Load all language pack resources which match the current user's locale, which would be:

    • /com/atlassian/confluence/core/ConfluenceActionSupport_<lang_country_variant>.properties

    • /com/atlassian/confluence/core/ConfluenceActionSupport_<lang_country>.properties

    • /com/atlassian/confluence/core/ConfluenceActionSupport_<lang>.properties


    The files are only loaded if a language pack for the specific locale is installed.

  3. Load all resources of type 'i18n' which match the current user's locale:

    • <resource location>_<lang_country_variant>.properties
    • <resource location>_<lang_country>.properties
    • <resource location>_<lang>.properties
    • <resource location>.properties

Resource Bundle Structure

DefaultI18NBean internally creates a list of CombinedResourceBundles per locale, combining resource bundles from language packs and i18n resources of the same locale. When you call one of the DefaultI18NBean.getText() methods it will go through the bundles in the following order:

  1. lang_country_variant
  2. lang_country
  3. lang
  4. default

On a lookup of a combined resource bundle, the last occurrence of a given key takes precedence during the lookup, which results in the following lookup order:

  1. i18n resource
  2. language pack

The order within i18n resources and language packs with the same locale is not defined, as they are loaded from the plugins which are loaded in an arbitrary order. This is not an issue in most cases, as you usually have no overlapping keys between your resources anyway.


Given the following situation:

  • The current user's locale is 'de_DE_foo'
  • There are language packs installed for the locales 'de_DE_foo', 'de_DE' and 'de'
  • There is one resource of type 'i18n' available from one of the plugins. The location for that resource is 'com.example.resources'

Lookups will always happen from top to bottom until a message for a given key is found.

Confluence Internals

Rate this page: