BoxLang 🚀 A New JVM Dynamic Language Learn More...

ColdBox i18n and Localization

v3.2.0+12 Modules

cbproxies CI


This module will enhance your ColdBox applications with i18n (internationalization) capabilities, resource bundles and localization. It supports traditional Java resource bundles and also modern JSON resource bundles.


Apache License, Version 2.0.


  • Lucee 5+
  • Adobe ColdFusion 2018+


Leverage CommandBox and install it:

box install cbi18n

This module registers the following models in WireBox:

  • i18n@cbi18n : Helper with all kinds of methods for localization
  • resourceService@cbi18n : Service to interact with language resource bundles - You may override this service by providing a customResourceService key in your configuration. More information on custom resource services.


You can add a cbi18n structure of settings to your modulesettings in ColdBox.cfc or to any other module configuration file: ModuleConfig.cfc to configure the module:

// config/ColdBox.cfc
moduleSettings =
	cbi18n = {
		// The base path of the default resource bundle to load
		// base path is path + resource name but excluding
		defaultResourceBundle = "includes/i18n/main",
		// The default locale of the application
		defaultLocale = "en_US",
		// The storage to use for user's locale: any cbstorages service. Please use full wirebox ID
		localeStorage = "CookieStorage@cbstorages",
		// The value to show when a translation is not found
		unknownTranslation = "**NOT FOUND**",
		logUnknownTranslation = true | false,
		// Extra resource bundles to load, specify path up to but not including here
		resourceBundles = {
			alias = "path"
		//Specify a Custom Resource Service, which should implement the methods or extend the base i18n ResourceService ( e.g. - using a database to store i18n )
		customResourceService = ""

Each module in your ColdBox Application can have its own resource bundles that can be loaded by this module as well. Just configure it via the cbi18n key in your ModuleConfig.cfc

function configure(){

	cbi18n = {
		defaultLocale = "es_SV",
		resourceBundles = {
			// Alias => path in module
			"module@test1" = "#moduleMapping#/includes/module"



This module announces an onUnknownTranslation interception. The data announced is a struct with the following format:

	resource 	= ...,
	locale 		= ... ,
	bundle  	= ...

Mixin Helpers

The module registers the following methods for handlers/layouts/views/interceptors:

* Get the user's currently set locale or default locale according to settings
function getFWLocale()

* Set the locale for a specific user
* @locale The locale to set. Must be Java Style Standard: en_US, if empty it will default to the default locale
* @dontLoadRBFlag Flag to load the resource bundle for the specified locale (If not already loaded)
* @return i18n Service
function setFWLocale( string locale="", boolean dontloadRBFlag=false )

* Retrieve a resource from a resource bundle with replacements or auto-loading
* @resource The resource (key) to retrieve from the main loaded bundle.
* @defaultValue A default value to send back if the resource (key) not found
* @locale Pass in which locale to take the resource from. By default it uses the user's current set locale
* @values An array, struct or simple string of value replacements to use on the resource string
* @bundle The bundle alias to use to get the resource from when using multiple resource bundles. By default the bundle name used is 'default'
function getResource(
    required resource,

// Alias to getResource
function $r()

 * Get Access to the i18n Model
function i18n()

 * Get the resource service model
function resourceService()

You can read more about this module here:

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp | |


Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5


"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[3.2.0] => 2022-NOV-16


  • Updated to use latest cb7 announce()

[3.1.0] => 2022-NOV-15


  • New ColdBox 7 delegate: Resourceful@cbi18n

[3.0.0] => 2022-OCT-10


  • New module template updates


  • Dropped 2016 Support

[2.2.0] => 2022-JAN-11


  • Migration to github actions
  • CFFormatting


  • Currently each time ColdBox framework gets reinited (?fwreinit=1) or server restarted, user-selected locale gets reset to the default locale.

[2.1.0] => 2021-JAN-20


  • Missing cbStorages dependency on the box.json causes failures upon installation


  • Added a shortcut compatiblity layer so v1 apps don't crash on choosing localeStorage. Basically, we map the incoming locale storage from the old approach: session,client,cookie,request to the cbStorages equivalent

[2.0.0] => 2021-JAN-19


  • ACF2016, ACF2018 Support
  • Complete migration to script thanks to @wpdebruin
  • Fallback mechanism for resource selection from base, to language, to country variants thanks to @wpdebruin
  • Migration to leverage cbStorages for locale storage thanks to @wpdebruin
  • Interceptor for missing translations onUnknownTranslation thanks to @wpdebruin
  • CookieStorage is now used as the default for storing locales
  • Support for flat or embedded JSON resource bundles as well as Java resource bundles via extension detection properties json thanks to @wpdebruin
  • New i18n() mixin helper to get easy access to i18n methods
  • New resoureService() mixin helper to get easy access to the resource service model
  • The extension of the file (.properties, .json) is what determines the resource type to use
  • Github autopublishing of changelogs
  • New CI procedures based on new ColdBox modules
  • More formatting goodness and watchers


  • Old approach to top level i18n settings. You know will use the normal moduleSettings with a cbi18n key for settings
  • On modules, you will use also the cbi18n top level key for configuration for each module
  • ACF11, Lucee 4.5 Support
  • DefaultLocale in storage now renamed to CurrentLocale
  • dontloadRBFlag removed as it was never used anymore.


  • Lots of fixes on localization methods using old Java classes that didn't exist anymore
  • Lots of fixes on streamlining the java classes used for localization


  • Improvement : Updated to new template style
  • Improvement : ColdBox 5 updates
  • Improvement : Moved i18n listener to afterAspectsLoad to avoid module loading collisions
  • Bug : Invalid instance scope usage in models


  • Few docuementation fixes
  • Fix implementation of getTZoffset() thanks to Seb Duggan
  • CCM-47 Case sensitivity resolved for resource service thanks to @wpdebruin
  • Updated TestBox version


  • Unified workbench
  • Encapsulation of module bundle resources


  • Varscoping fixes
  • Travis updates


  • Implements the ability to add a custom Resource Service for distributed i18n
  • Fixes issues with non-ISO characters in properties files


  • New configuration setting for logging when no translation is found logUnknownTranslation
  • Adding Travis CI support


  • Updated build process
  • Updated docs and instructions


  • Fixes on getRBKeys() and getRBString() to load correct file paths.


  • production ignore lists
  • Unloading of helpers


  • Create first module version

$ box install cbi18n

No collaborators yet.
  • {{ getFullDate("2014-05-09T21:24:51Z") }}
  • {{ getFullDate("2022-11-16T20:04:16Z") }}
  • 13,491
  • 461,826