Blog

Luis Majano

January 19, 2021

Spread the word


Share your thoughts

After many many months of development, testing and waiting, we are finally able to release a major major update to our localization and internationalization library for ColdBox: cbi18n version 2.x. This release is a huuuge advancement for building localized applications and websites and partly thanks to Mr Wil de Bruin (shiftinsert.nl). This release introduces the ability to use json resource bundles, multiple bundles per module, cbStorages for tracking locales, property inheritance and so much more! There are a few compatiblity issues, so make sure you read them to upgrade to version 2.x if not you can easily update using CommandBox:

install cbi18n
update cbi18n

What About cbValidation?

cbValidation 2.x does have a dependency on cbi18n version 1.x and that will remain coupled to the 1.x series. However, cbValidation 3.x is now under development and it will be bumped to support cbi18n 2.x.

Whats New With 2.0.0

Compatibility Updates

CFML Engines

Compatibility with Adobe ColdFusion 11 and Lucee 4.5 have been dropped.

Module Configuration Settings

You will need to move the i18n configuration structure in your config/ColdBox.cfc to the moduleSettings struct and rename it to cbi18n to standardize it to module settings.

moduleSettings = {

		cbi18n = {
			// The default resource to load and aliased as `default`
			"defaultResourceBundle" : "includes/i18n/main",
			// The locale to use when none defined
			"defaultLocale"         : "en_US",
			// The default storage for the locale
			"localeStorage"         : "cookieStorage@cbstorages",
			// What to emit to via the resource methods if a translation is not found
			"unknownTranslation"    : "**NOT FOUND**",
			// If true, we will log to LogBox the missing translations
			"logUnknownTranslation" : true,
			// A-la-carte resources to load by name
			"resourceBundles"       : {},
			// You can override the ResourceService with your own, just add the WireBox ID
			"customResourceService" : ""
		}
		
};

ColdBox Module Settings

Every ColdBox module has the i18n capabilities available to them as well. They can use it to register their own resource bundles. The previous version allowed for a setting called i18n this is now called cbi18n to comply with the same global naming convention. Just update your key root in your Moduleconfig.cfc

```javascript
cbi18n = {
		defaultLocale = "es_SV",
		resourceBundles = {
			"module@test1" = "#moduleMapping#/includes/module"
		}
};

Locale Storage Options

  • localeStorage will use a cbstorages compatible service now. This means you have to specify the WireBox ID now, e.g CookieStorage@cbstorages , SessionStorage@cbstorages etc

Major updates

JSON Resources

cbi18n v1 already had java resource bundles. v2 added support for JSON resource bundles. Both flat and nested JSON bundles are supported.

Flat

{
    "sub.IntroMessage": "Normal JSON"
}
{
    "sub.IntroMessage": "JSON Normal"
}

Nested

{
    "sub": {
        "IntroMessage": "Nested JSON"
    }
}
{
    "sub": {
        "IntroMessage": "JSON Incrustado"
    }
}

Locale Storage

The locale storage has now moved to leveraging a cbStorages compliant driver. This way you can leverage any of the cbStorages drivers or anything custom you would like.

  • applicationStorage@cbstorages
  • cacheStorage@cbstorages
  • clientStorage@cbstorages
  • cookieStorage@cbstorages (default)
  • requestStorage@cbstorages
  • sessionStorage@cbstorages

Property Inheritance

In this version we introduced the concept of property inheritance. It means that key-values pairs included in less specific files are inherited by those which are higher in the inheritance tree. For example: Let's assume you are using a en_US locale. if you have key-values in a generic myResource.properties file, you can override them in a myResource_en.properties and an even more specific myResource_en_US.properties file. This opens up the possibility to define a generic language resource and define country specific translations in a more specific resource file.

The order of lookup is:

  • myBundle_en_US_somevariant.(properties|json)
  • myBundle_en_US.(properties|json)
  • myBundle_en.(properties|json)
  • myBundle.(properties|json)

New Mixin Helpers

You get some brand new helpers in this release:

/**
 * Get i18n Model
 */
function i18n()

/**
 * Get the resource service model
 */
function resourceService()

Unknown Translation Interception

The event onUnknownTranslation is emitted via an interception when a translation is not found. You will receive the following interception data packet:

{ 
    resource 	= ..., 
    locale 		= ... , 
    bundle  	= ... 
}

Add Your Comment

Recent Entries

Must-See ITB 2025 Sessions for TestBox Users!

Must-See ITB 2025 Sessions for TestBox Users!

Are you a fan of TestBox or looking to level up your testing game in 2025? Whether you're just getting started with unit testing or you're already building advanced specs for ColdBox and BoxLang apps, Into the Box 2025 has an exciting lineup tailored just for you. Into the Box 2025 has an exciting lineup tailored just for you. With the recent launch of TestBox 6.3.0 we have amazing new tools, features and tips and tricks to get your testing experience to the next level, review our sessions and test like a pro efficiently and easy!

From hands-on testing strategies to BoxLang innovations, here are the sessions you won’t want to miss this May — and why they matter to you as a TestBox user.

Maria Jose Herrera
Maria Jose Herrera
April 17, 2025
The Into the Box 2025 Agenda is LIVE and Done!

The Into the Box 2025 Agenda is LIVE and Done!

The wait is over! The official Into the Box 2025 agenda is now live — and it's packed with high-impact sessions designed for modern CFML and BoxLang developers. Whether you’re building APIs, modernizing legacy apps, diving into serverless, or exploring AI integrations, this is the conference you’ve been waiting for.

Here’s a look at what you can expect — categorized by key topics to help you plan your learning journey, there’s something for everyone covering modern CFML tools and BoxLang:

Maria Jose Herrera
Maria Jose Herrera
April 15, 2025
Only 2 Days Left to Lock In Early Bird Pricing for Into the Box 2025!

Only 2 Days Left to Lock In Early Bird Pricing for Into the Box 2025!

The countdown is on. You have just two days left to secure your Early Bird ticket  for just $199 to Into the Box 2025 before prices increase on April 16.

We are proud to offer an engaging and high-value online experience for developers around the world. With a virtual ticket, you get more than just access — you get ongoing value that supports your growth long after the conference ends.

Maria Jose Herrera
Maria Jose Herrera
April 14, 2025