Added

• New module template updates

Changed

• Dropped 2016 Support

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 Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelor of Science in Computer Engineering at Florida International University. Luis resides in The Woodlands, Texas with his beautiful wife Veronica, daughter Alexia and son Lucas!

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development, and all open-source professional services under the ColdBox, CommandBox, and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, TestBox, LogBox, and anything “BOX”, and contributes to many open-source projects. You can read his blog at www.luismajano.com

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 is CTO of the Dutch hosting company Site4u and is next to providing managed servers for Lucee, ColdFusion, and many other platforms, he develops software and provides consultancy and training. He has been working with ColdFusion since v1.5 and uses Coldbox for the 2.x days.

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 source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyrighted by and cannot be altered or reproduced without the author's consent. All content is provided "As-Is" and can be freely distributed.

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

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL -

• 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

We highly encourage contributions to this book and our open-source software. The source code for this book can be found in our where you can submit pull requests.

Charitable Proceeds

10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - . So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

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.

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.

For locale storage we now use a service from the module.

Version 1.0

A ( very old ) initial release.

Leverage CommandBox to install into your ColdBox application:

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.

System requirements

• Lucee 5+

• Adobe ColdFusion 2018+

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

The ColdBox cbi18n Module is maintained under the guidelines as much as possible. Releases will be numbered in the following format:

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

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.

Global Configuration

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

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

JSON Flat

JSON Nested

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.

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

Configuration With No Resource Bundles

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

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

• 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.

In many languages there are country or region specific words. You wonder if you should provide resource bundles for each country while only a small subset of words is different. For this scenario you can use property inheritance which is nicely explained here.

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

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

A very basic list of resource editors will be discussed in the next paragraph.

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:

function changeLocale( event, rc, prc ){
    setFWLocale( rc.locale );
    relocate('main.home');
}

Or use via injection

component{

    property name="i18n" inject="i18n@cbi18n";

    function changeLocale(){
        i18n.setFWLocale( 'en_US' );
    }

}

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:

component 
  name="MyCustomResourceService" 
  extends="cbi18n.models.ResourceService" 
  singleton=true{
  
  property name="Controller" inject="coldbox";
  property name="Wirebox" inject="wirebox";

}

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:

public void function loadBundle( 
    required string rbLocale=VARIABLES.i18n.getfwLocale() 
){
    var bundles = "";

    // Lazy Load?
    if( NOT VARIABLES.controller.settingExists("RBundles") ){
        VARIABLES.controller.setSetting("RBundles",structnew());
    }

    //set bundles ref
    bundles = VARIABLES.controller.getSetting("RBundles");
    var rb = structNew();

    //cache our resource bundle query
    var qRb = new query( datasource=application, cachedWithin=CreateTimeSpan(0, 6, 0, 0) );
    qRb.addParam( name="locale", value=arguments.rbLocale, cfsqltype="cf_sql_varchar" );
    qRb.setSQL( "SELECT * from customI18nTable WHERE locale=:locale" );
    var rbResult = = qRb.execute().getResult();
    for( var resource in rbResult ){
        rb[ resource.label ] = resource.value;
    }

    bundles[ arguments.rbLocale ] = rb;
}

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:

public string function getResource(
    // The resource (key) to retrieve from the main loaded bundle.
    required any resource,
    //A default value to send back if the resource (key) not found
    any default,
    //Pass in which locale to take the resource from. By default it uses the user's current set locale
    any locale="#VARIABLES.i18n.getfwLocale()#",
    //An array, struct or simple string of value replacements to use on the resource string
    any values,
    //default
    any bundle="default"
){
    //prevent errors via empty label strings from being passed
    if( !len( trim(resource) ) ) return resource;

    //protect from a bad locale value being passed
    if( !len( trim( arguments.locale ) ) ) arguments.locale = VARIABLES.i18n.getfwLocale();

    var thisLocale         = arguments.locale;
    var resourceString = "";

    var rBundles = Controller.getSetting("RBundles");
    var currentUser = Wirebox.getInstance( "SessionService" ).getCurrentUser();

    if( !structKeyExists( rBundles, arguments.locale ) ){
        loadBundle( rbLocale=arguments.locale, rbAlias=arguments.bundle );
    }

    var resourceBundle = rBundles[ arguments.locale ];

    if( structKeyExists( resourceBundle, arguments.resource  ){
        var resource = resourceBundle[ arguments.resource ];
        if( resource.published ){
            return formatResourceObject( resourceObj=resource, args=arguments );
        } else if( !resource.published && currentUser.isAdministrator() ) {
            return formatDraftResource( resourceObj=resource, args=arguments );
        }
    } else if( !isNull( arguments.default ) ) {
        if( !isNull( arguments.values ) ){
            return formatRBString( arguments.default, arguments.values );
        } else {
            return arguments.default;
        }
    } else {
        return renderUnknownTranslation( arguments.resource );
    }
}

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.

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

• BabelEdit is a very capable and affordable resource editor, for both JSON and java properties. It can edit JSON flavours for vue and angular libraries and also has support for other resource bundle formats. However it can not convert between formats. Only conversion between flat and nested JSON files is supported.

Java resource editors

• the Eclipse Resource Bundle Editor plugin is a FANTASTIC editor for eclipse: More info here https://essiembre.github.io/eclipse-rbe/

• Attesoro is another free resource editor, a bit more limited and dated, but still usable.

• BabelEdit is a very capable and affordable resource editor, for both JSON and java properties.

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

• (vista-compatibleUnifier converts a batch of plain text or HTML files in various characters set encoding to Unicode in UTF-16 or UTF-8 encoding)

• : A great Resource Bundles utility.