# Configuration

## Global Configuration

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

{% code title="config/Coldbox.cfc" %}

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

{% endcode %}

<table data-header-hidden><thead><tr><th width="275">Key</th><th>Type</th><th width="105">Required</th><th width="98">Default</th><th>Description</th></tr></thead><tbody><tr><td>Key</td><td>Type</td><td>Required</td><td>Default</td><td>Description</td></tr><tr><td><code>defaultResourceBundle</code></td><td>string</td><td>no</td><td></td><td>This is the path for a resource bundle that will be treated as the default resource bundle with an alias of <code>default</code> . The path must NOT include language or variants, just the name of path prefix<code>includes/i18n/main_en_US.properties</code> should be specified as <code>includes/i18n/main</code></td></tr><tr><td><code>resourceBundles</code></td><td>struct</td><td>no</td><td><code>{}</code></td><td>key-value struct of resource alias name and bundle path <strong>without</strong> the lang_COUNTRY.(properties|json) part.</td></tr><tr><td><code>defaultLocale</code></td><td>string</td><td>no</td><td><code>en_US</code></td><td>default locale </td></tr><tr><td><code>localeStorage</code></td><td>string</td><td>no</td><td><code>cookieStorage@cbstorages</code></td><td>cbstorages service where current locale is  stored</td></tr><tr><td><code>unknownTranslation</code></td><td>string</td><td>no</td><td></td><td>if no unknowTranslation is set getResource will fail on unknown resourceKeys</td></tr><tr><td><code>logUnknownTranslation</code></td><td>boolean</td><td>no</td><td>false</td><td>will log unknown translations to logbox</td></tr></tbody></table>

{% hint style="warning" %}
**WARNING**

When specifying resources in a MODULE, you should **never** specify a `defaultResourceBundle`, because it will conflict with your main settings. \
If you specify additional `resourceBundles` it is wise to choose an `aliasname` which will not conflict with other modules or your main settings
{% endhint %}

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.

{% hint style="info" %}
ColdBox will auto-detect the extension of the resource bundle and deal with it appropriately.  The supported extension types are:&#x20;

* `.properties` - Java resource bundle
* `.json` - JSON resource bundle (flat or nested)
  {% endhint %}

**Java Properties**

{% code title="includes/i18n/main\_en\_US.properties" %}

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

{% endcode %}

#### JSON Flat

{% code title="includes/i18n/jsontest\_en\_US.json" %}

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

{% endcode %}

{% code title="includes/i18n/jsontest\_es\_SV.json" %}

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

{% endcode %}

#### JSON Nested

{% code title="includes/i18n/nested\_en\_US.json" %}

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

{% endcode %}

{% code title="includes/i18n/nested\_es\_SV.json" %}

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

{% endcode %}

## 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.`

{% code title="ModuleConfig.cfc" %}

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

{% endcode %}

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

```javascript
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

```javascript
//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.

{% hint style="danger" %}
**IMPORTANT** \
\
All language resource bundles are stored in the configuration structure of your application and are lazy loaded in. So if a language is not used, then it does not get loaded. This is separate from where the user's locale information is stored.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coldbox-i18n.ortusbooks.com/v3.x-5/getting-started/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.