### Example Java Properties Resource Bundle

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

This snippet provides an example of a `.properties` file, `includes/i18n/main_en_US.properties`, which serves as a Java resource bundle for translations. It shows simple key-value pairs for internationalization.

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

--------------------------------

### Localization Examples with cbi18n

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/overview.md

Provides practical examples of using cbi18n for string localization, showing how to retrieve localized text, apply dynamic replacements using arrays or structs, and manage the user's locale. It highlights common patterns for integrating i18n features into ColdBox views and controllers.

```ColdFusion
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' );
}
```

--------------------------------

### Install cbi18n Module using CommandBox

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/installation.md

Commands to install the `cbi18n` module into a ColdBox application using CommandBox, including the latest stable version and the bleeding edge version.

```bash
# Latest version
install cbi18n

# Bleeding Edge
install cbi18n@be
```

--------------------------------

### JSON Flat Format Example (English)

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Demonstrates a simple, flat JSON structure for internationalization resource bundles, showing a single key-value pair for an English message.

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

--------------------------------

### JSON Flat Format Example (Spanish)

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Illustrates a simple, flat JSON structure for internationalization resource bundles, showing a single key-value pair for a Spanish message.

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

--------------------------------

### JSON Nested Format Example (English)

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Shows a nested JSON structure for internationalization resource bundles, demonstrating how messages can be organized under parent keys for English.

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

--------------------------------

### JSON Nested Format Example (Spanish)

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Illustrates a nested JSON structure for internationalization resource bundles, demonstrating how messages can be organized under parent keys for Spanish.

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

--------------------------------

### Use Resourceful Delegate in ColdFusion Components

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/installation.md

Example of how to use the `Resourceful@cbi18n` delegate in a ColdFusion component to gain access to resource-related methods like `getResource()`.

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

   // Then just use the getResource() method
}
```

--------------------------------

### cbi18n Module WireBox Models and Mixin Helper Methods

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/installation.md

Details the models registered by the `cbi18n` module in WireBox and the helper methods it registers for use in handlers, interceptors, layouts, and views.

```APIDOC
WireBox Models:
  i18n@cbi18n: Helper with all kinds of methods for localization
  resourceService@cbi18n: Service to interact with language resource bundles

Mixin Helper Methods:
  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
```

--------------------------------

### ColdFusion i18n Resource and Locale Management Examples

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/README.md

This snippet illustrates how to use the `getResource` function for localized strings, including dynamic replacements using both array and struct syntax. It also shows how to change the framework locale programmatically.

```ColdFusion
Your locale is #getFwLocale()#!

// localized button
#html.submitButton( value=getResource( '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( getResource(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
#getResource( 'common.ok@cbcore' )#

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

--------------------------------

### ColdFusion i18n Service Utility Method Access

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/README.md

This example demonstrates how to access various internationalization and localization utility methods available through the `prc.i18n` service. It showcases retrieval of locale, language, country, time zone, and version information.

```ColdFusion
<cfoutput >
<strong>Locale:</strong> <br />#prc.i18n.getFWLocale()#<br />
<strong>Language:</strong> <br />#prc.i18n.getFWLanguage()#<br />
<strong>Language Code:</strong> <br />#prc.i18n.getFWLanguageCode()#<br />
<strong>Language ISO3 Code:</strong> <br />#prc.i18n.getFWISO3LanguageCode()#<br />


<strong>Country:</strong> <br />#prc.i18n.getFWCountry()#<br />
<strong>Country Code:</strong> <br />#prc.i18n.getFWCountryCode()#<br />
<strong>Country ISO3 Code3:</strong> <br />#prc.i18n.getFWISO3CountryCode()#<br />


<strong>TimeZone:</strong> <br />#prc.i18n.getServerTZ()#<br />
<strong>i18nDateFormat:</strong> <br />#prc.i18n.i18nDateFormat(prc.i18n.toEpoch(now()),1)#<br />
<strong>i18nTimeFormat:</strong> <br />#prc.i18n.i18nTimeFormat(prc.i18n.toEpoch(now()),2)#<br />
<hr>
<strong>I18NUtilVersion:</strong> <br />#prc.i18n.getVersion().I18NUtilVersion#<br>
<strong>I18NUtilDate:</strong> <br />#prc.i18n.dateLocaleFormat(prc.i18n.getVersion().I18NUtilDate)#<br>
<strong>Java version:</strong> <br />#prc.i18n.getVersion().javaVersion#<br>
</cfoutput>
```

--------------------------------

### i18n Mixin Helper Methods for Handlers, Layouts, Views, and Interceptors

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/README.md

These methods are registered as runtime mixins, providing convenient access to i18n functionalities directly within handlers, layouts, views, and interceptors. They allow getting and setting locales, retrieving localized resources, and accessing i18n services.

```javascript
/**
* 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,
    defaultValue,
    locale,
    values,
    bundle,
)

// Alias to getResource
function $r()

/**
 * Get Access to the i18n Model
 */
function i18n()

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

--------------------------------

### Change Locale using injected i18n service setFWLocale()

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/how-do-i-change-locales.md

This example shows how to inject the `i18n` service into a component and then use its `setFWLocale()` method to programmatically change the locale to 'en_US'. This approach is suitable for service-oriented architectures.

```javascript
component{

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

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

}
```

--------------------------------

### Using Bundle Aliases with getResource() Method

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/README.md

Demonstrates how to specify a resource bundle when retrieving resources using the `getResource()` method, either directly via the `bundle` argument or through the `@bundle` convention for cleaner syntax. It also shows how to reference the default bundle.

```javascript
// Direct
#getResource( resource="common.ok", bundle="cbcore" )#

// Convention
#getResource( "common.ok@cbcore")#

#getResource( "some.resource@default")#
// OR
#getResource( "some.resource")#
```

--------------------------------

### Accessing cbi18n Services

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/overview.md

Demonstrates various methods to access the `i18n` and `ResourceService` models, including mixin helpers, WireBox injection, and ColdBox Delegates. These services provide core internationalization and localization functionalities within ColdBox applications.

```ColdFusion
// 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' )#";
 ...
}
```

--------------------------------

### ColdBox cbi18n Module Global Configuration

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

This JavaScript snippet demonstrates how to configure the `cbi18n` module within the `moduleSettings` structure of your `config/Coldbox.cfc` file. It sets up the default resource bundle, locale, storage mechanism, and behavior for unknown translations.

```javascript
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" : ""
		}
		
};
```

--------------------------------

### cbi18n Module Configuration Keys API Reference

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

This API documentation outlines the available configuration keys for the `cbi18n` module, detailing their types, whether they are required, default values, and a description of their purpose. These settings are defined within the `cbi18n` key of the `moduleSettings` struct.

```APIDOC
cbi18n Configuration Object:
  defaultResourceBundle:
    Type: string
    Required: no
    Default: ""
    Description: Path for a resource bundle treated as the default, aliased as 'default'. Path must NOT include language or variants.
  resourceBundles:
    Type: struct
    Required: no
    Default: {}
    Description: Key-value struct of resource alias name and bundle path (without lang_COUNTRY.(properties|json) part).
  defaultLocale:
    Type: string
    Required: no
    Default: "en_US"
    Description: The default locale to use.
  localeStorage:
    Type: string
    Required: no
    Default: "cookieStorage@cbstorages"
    Description: The cbstorages service where the current locale is stored.
  unknownTranslation:
    Type: string
    Required: no
    Default: ""
    Description: The string value to emit via resource methods if a translation is not found.
  logUnknownTranslation:
    Type: boolean
    Required: no
    Default: false
    Description: If true, missing translations will be logged to LogBox.
```

--------------------------------

### ColdBox i18n Configuration Without Resource Bundles

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Illustrates how to configure i18n in ColdBox to track user locales (default locale and storage mechanism) without loading any resource bundles, optimizing for cases where only locale tracking is needed.

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

--------------------------------

### Accessing i18n Resources with Bundle Identifier

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Demonstrates two ways to retrieve translated resources using the `i18n.getResource` method, either by appending the bundle identifier with `@` or by passing it as a separate argument.

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

--------------------------------

### ColdBox Module i18n Configuration

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/getting-started/configuration.md

Configures internationalization capabilities within a ColdBox module, specifying resource bundles and their mapping paths. This uses the updated `cbi18n` key for compliance with global naming conventions.

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

--------------------------------

### Define a Custom cbi18n Resource Service in CFML

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/custom-resource-services.md

This ColdFusion code snippet demonstrates how to define a custom resource service by extending `cbi18n.models.ResourceService`. It sets up a singleton component with injected `coldbox` Controller and `wirebox` Wirebox instances, providing the foundational structure for custom i18n resource handling.

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

}
```

--------------------------------

### Override loadBundle Method to Fetch i18n Resources from Database in CFML

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/custom-resource-services.md

This CFML function shows how to override the `loadBundle` method within a custom resource service. It retrieves i18n resource bundles from a database table (`customI18nTable`) based on the provided locale, caching the query results for 6 hours. The loaded bundle is then stored in the ColdBox controller's settings.

```cfml
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;
}
```

--------------------------------

### WireBox Mapped i18n Models

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/README.md

This section lists the i18n-related models registered in WireBox, providing access to helper methods for localization and a service for interacting with language resource bundles.

```APIDOC
i18n@cbi18n : Helper with all kinds of methods for localization
resourceService@cbi18n : Service to interact with language resource bundles
```

--------------------------------

### Change Locale using i18n mixin method setfwLocale()

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/how-do-i-change-locales.md

This JavaScript function demonstrates how to change the application's locale using the `setFWLocale()` mixin method, typically called from a UI event. It then redirects the user to the home page after the locale change.

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

--------------------------------

### Semantic Versioning Format

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/README.md

The cbi18n module follows Semantic Versioning guidelines. This format specifies how version numbers are structured and incremented based on the type of changes introduced, where <major> indicates breaking changes, <minor> indicates new features, and <patch> indicates bug fixes.

```Text
<major>.<minor>.<patch>
```

--------------------------------

### Override getResource Method for Advanced i18n Metadata Handling in CFML

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/coding-for-i18n/custom-resource-services.md

This ColdFusion function illustrates how to override the `getResource` method to support complex i18n resource metadata, such as a 'published' flag for draft content. It fetches resources from the loaded bundle, checks for publication status, and allows administrators to view unpublished content. The method also handles default values and string replacements, returning an unknown translation message if the resource is not found.

```cfml
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 );
    }
}
```

--------------------------------

### Set Page Encoding with cfprocessingdirective

Source: https://github.com/ortus-docs/cbi18n-docs/blob/v3.x/usage/best-practices.md

Demonstrates how to explicitly set the page encoding to UTF-8 using the `cfprocessingdirective` tag in ColdFusion. This practice ensures consistent character handling and prevents issues with special characters in files.

```ColdFusion
<cfprocessingdirective pageencoding="utf-8">
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.