In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 3.0

Dropped support for Adobe 2016, migration to new modules template, and integrations with ColdBox 7 features.

Version 2.0

The module has been rewritten in CFScript.

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

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.

Version 1.0

A ( very old ) initial release.

The cbi18n module was built to provide localization and internationalization features to any ColdBox application. It will not only allow you to represent resources in multiple languages, but will also track the user's locale for you. It has a plethora of utilities for localizing strings, dates, currencies and much more.

There are two main models that are registered for you with the following WireBox Id's:

• i18n@cbi18n : Service that tracks user's locale, changing of locales, and a plethora of localized functions. It also bootstraps the resource bundles used in the application.

• ResourceService@cbi18n In charge of retrieving language keys from locale specific resource bundles, whether they are Java property files or JSON bundles.

They can either be injected, called via our mixin helpers or added via our ColdBox Delegates:

// Mixins
i18n()
resourceService()

// Injection
property name="i18n" inject="i18n@cbi18n";
property name="resourceService" inject="resourceService@cbi18n"

// Delegates
component delegates="Resourceful@cbi18n"{
 
 ...
    return "Hello + #getResource( 'myResource' )#";
 ...
}

Once you have access to those objects you can leverage their methods to your ❤️'s content.

Your locale is #getFwLocale()#!

// localized button
#html.submitButton( $r( 'btn.submit' ) )#

// Localized string with replacements via arrays
#html.h2( $r(resource="txt.hello", values=[ "Luis", "Majano" ] ) )#

// txt.hello resource
txt.hello="Hello Mr {1} {2}! I hope you have an awesome day Mr. {2}!"

// Localized string with replacements via structs
#html.h2( $r( resource="txt.hello", values={ name="Luis", age="35" } ) )#

// txt.hello resource
txt.hello="Hello Mr {name}! You are {age} years old today!"

// Localized string from a bundle, notice the @cbcore alias
#$r( 'common.ok@cbcore' )#

// function change a user's locale
function changeLocale(event,rc,prc){
	setFwlocale( rc.locale );
	relocate( 'home' );
}

Please see the API docs for the latest methods available to you:

Author

Luis Fernando Majano Lainez

Luis has a passion for Jesus, tennis, golf, volleyball, and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit are something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, microcontrollers, and overall embedded systems.

• He has of late (during old age) become a fan of organic gardening.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Contributors

Wil de Bruin

Wil de Bruin is a Software and System Engineer who has been developing software systems since 1990. He was born in The Netherlands in the '60s and lives in Wageningen, the Netherlands.

He built his own wood-fired oven where he bakes the best pizzas in town. He is the administrator of the Dutch bread-baking forum, and bakes lots of bread for family, friends, neighbors, and parties.

The cbi18n module will enhance your ColdBox applications with i18n capabilities, resource bundles, and localization.

Some Features

• Switching locales on the fly, stored in cookies, sessions or any other cbstorages provider

• Resource bundles: java properties files or JSON (nested or flat)

• Inherited resource bundles e.g main.properties, main_en.properties ormain_en_US.properties.

• Many locale-specific functions: date and time formats and parsing, country codes, currency symbols

• Custom resource services

• ColdBox 7 Delegates

Versioning

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

Apache License, Version 2.0.

Important links

System requirements

• Lucee 5+

• Adobe ColdFusion 2018+

Discussion & Help

The Box products community for further discussion and help can be found here:

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's 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." Romans 5:5

• The majority of code examples in this book are done in cfscript.

• All ColdFusion examples are designed to run on the open-source Lucee Platform or Adobe ColdFusion 11+

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software, and resources described in it.

Contributing

Charitable Proceeds

Shalom Children's Home

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education, and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador who either have no families or have been abandoned. This is a good earth to seed and plant.

Leverage CommandBox to install into your ColdBox application:

# Latest version
install cbi18n

# Bleeding Edge
install cbi18n@be

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

Mixins Helper methods

This module will register the following methods in your handlers/interceptors/layouts/views

• getFWLocale() gets the users currently set locale (or default locale)

• setFWLocale() set the locale for a specific user

• getResource() retrieve a resource from a resource bundle with replacements

• $r() shortcut/alias to getResource()

• i18n() gets the i18n Model

• resourceService() gets the Resource Service

Delegates

You can use the Resourceful@cbi18n delegate to add resource traits to your objects and access to the getResource() method.

component name="SecurityService" delegates="Resourceful@cbi18n" {

   // Then just use the getResource() method
}

System requirements

• Lucee 5+

• Adobe ColdFusion 2018+

Added

• New module template updates

Changed

• Dropped 2016 Support

Global Configuration

The module can be configured by adding a cbi18n key in the moduleSettings structure within the config/Coldbox.cfc

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"       : {},
			// Your own CFC instantiation path
			"customResourceService" : ""
		}
		
};

A resource bundle can be a .properties file containing your translations (java resources) OR a .json file. For instance, using the default settings above, you would need to create a includes/i18n/main_en_US.properties file with your translations. If you want to use JSON files, you should use an includes/i18n/main_en_US.json file.

Java Properties

main.readthedocs=Read The Docs!
greeting=Hello {name}

JSON Flat

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

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

JSON Nested

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

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

Module Configuration

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.

cbi18n = {
  resourceBundles = {
     "bundleIdentifier" = "#moduleMapping#/includes/module"
  }
};

The keys in the resourceBundles struct represents the bundle that can be passed to getResource or appended on the resource string with an @ sign.

i18n.getResource( "myTranslationKey@bundleIdentifier" );
// same as
i18n.getResource( resource = "myTranslationKey", bundle = "bundleIdentifier" );

Configuration With No Resource Bundles

You can also use the config declaration for just tracking user locales and no resource bundles support

//i18n & Localization
i18n = {
    defaultLocale = "en_es",
    localeStorage = "cookieStorage@cbstorages"
};

You eliminate the resource bundle element or leave it blank. The framework will not load the resource bundles.

For existing projects you probably have existing resource files, probably JSON files or java resources. For new projects you can ask yourself if you would choose JSON or java properties. Here are some pros and cons

• JSON is a simple file format, supported by many editors.

• Many frontend Javascript frameworks also support JSON

• If you use many different locales it can become complex to make sure all keys are entered in all resource bundles. You might need specialized editors to keep track of all translated keys.

• It is not hard to generate your own JSON resource files from a database.

• if you already used cbi18n v1 you probably have java properties files.

• there are very capable (free) resource editors available for java properties.

• Several web based translation facilities provide export to java properties and/or json resources

So let's say I want to provide translations for english and Dutch. Because we want to provide Dutch translations for both Netherlands and Belgium we want to use the following locales: nl_NL(dutch) and nl_BE (flemish). Instead of duplicating the nl_NL resource file myResource_nl_NL.properties to myResource_nl_BE.properties we can create a general myResource_nl.properties file and specify a myResource_nl_BE.properties file which only differs for a few keys. If we retrieve a resource with getResource(resource = "some.key", locale="nl_BE) it will try to lookup this key in the following order

• myResource_nl_BE.(properties|json)

• myResource_nl.(properties|json)

• myResource.(properties|json)

As you can see this lookup order does not stop at myResource.nl.(properties|json). It even goes up to a resource file without language indication. This can be especially useful if you create your app in one language, and only have incomplete translations for other languages. So let's say you create an english language app, you could just create a myResource.(properties|json) file and assume your main language is english. If you want to provide French as a second language but don't have the full translation yet (because it is a community effort for example) you can add myResource.fr.(properties|json) as a resource file, so you can provide a growing number of translated resource keys.

It is even possible to be more specific by adding country variants, e.g myResource.en_GB_someVariant.properties

Now that you have completed the initialization of the i18n settings in the configuration file, you are ready to code for them. There are several methods that are available to all handlers, interceptors, layouts and views that deal with i18n via runtime mixins. You can use these methods directly or go to the services directly if you inject them.

Mapped Models

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

Mixin Helpers

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

Bundle Aliases

You can leverage the getResource() or $r() method to retrieve resources from specific bundles by using the bundle argument or the @bundle convention.

We do like our @bundle convention as it looks prettier and you type a lot less.

Examples

Here are some examples of usage

INFO Please note that the i18N services are singleton objects and lives throughout your entire application span.

You can place the i18n@cbi18n service in the prc scope and then use this utility for i18n specific methods anywhere in your layouts and views, below is a simple example:

INFO There are tons of great utility methods in the i18n service that will allow you to work with localization and internationalization. Please view them via the API Docs for the latest methods and arguments.

Well, it would not make any sense to use i18n for just one locale, would it? That is why you need to be able to change the application's locale programmatically. You can do this in two ways:

1. Using the i18n mixin method setfwLocale().

2. Using the i18n service setfwLocale().

Below you can see an example:

Or use via injection

JSON resource editors

• most code editors can be used for JSON editing, but if you have large resource files or many locales you can probably better use a specialized tool, which keeps track of missing translations

Java resource editors

Below you can see some screenshots of the eclipse resource bundle editor plugin. I really recommend this tool.

INFO Make sure your files are all utf-8 encoding. It's also good i18n practice to liberally use cfprocessingdirective

If you elect not to use property files for your resource bundles, or need to expand your i18n implementation to include content pulled from other sources, the module allows for the specification of a customResourceService in the configuration.

To begin, create a custom resource service which extends the core i18n resource service:

To override the resource bundle used, you would declare a new loadResourceBundle method. To override the implementation of the getResource( i18nResourceLabel ) you would declare a new getResource method. An example, using your database to retrieve an i18n resource bundle:

Lets say we want to account for a more complex metadata structure in our resource bundles. For example, allow a draft value to allow for administrators to see which items in our bundle are pending review but display the default value to the public. We might also want to add any new resource requests containing a default value as drafts in the system (which we won't cover here). For special circumstances, such as these, we would need to change the implementation of the getResource method to account for this draft functionality:

The ability to extend and implement custom resource services provides you with a great deal of flexibility in your internationalization efforts. Use cases might include database-driven i18n resources, distributed caching implementations, and variable bundle formats used in third-party tools and plugins.

• Eclipse (not CFEclipse or CFBuilder) doesn't add a BOM to UTF-8 encoded files, make sure you utf-8 as the default encoding for files.

• Always use cfprocessingdirective

<cfprocessingdirective pageencoding="utf-8">

• This module uses the core java resource bundle flavor so you have to use a proper resource bundle tool to manage these.