Language Files

The MITREid Connect server uses a language internationalization system for handling nearly all display strings throughout the application.

How it works

The core language files are found in the openid-connect-server-webapp project, under the src/main/webapp/js/locale directory structure. The directories beneath this are language codes, so the English translation lives under en and the Swedish translation lives under sv, and so on. The only officially supported translation is English, while other languages are community contributions. The language is set on the system's ConfigurationPropertiesBean object's locale property.

Within each language code folder is a set of JSON files, with the default named messages.json. These files include all of the display strings for the server as described below. The language files are loaded and used by both the server-side Java framework (through the Spring Messages mechanism) and through the JavaScript front end (through the i18n.js library). These systems look to the system's ConfigurationPropertiesBean object's languageNamespaces property to determine which files in the directory to load, and in which order they are checked.

Message construction

Messages are arranged in a hierarchical JSON object structure. The keys are composed to allow access to the strings found in the values. For example, given a structure like this:

{
   "foo": {
      "bar": {
         "baz": "This is one"
      },
      "quux": "This is another"
}

There are two values. The first is indexed by foo.bar.baz and has the string value "This is one". The second is indexed by foo.quux and has the string value "This is another". Additional values can be added to the foo.bar or foo objects by extending the objects with more key-value pairs, and sub-objects can be created by assigning an object to a new key.

If the system cannot find a given key in the file, it checks the next language namespace file (as specified above) for the same key. If the system exhausts all the configured language namespaces, and it's using a language other than en, it falls back to the default English translation.

JSON numbers, booleans, and arrays are not used by this structure in any form.

Customization

Customizing this system is supported through a variety of mechanisms, making use of the locale and language namespace configuration properties. While overlays could simply replace the existing messages.json file with a custom version, it is recommended that instead overlays create their own version in a new namespace.

For example, let's say we wanted to create a custom application and used the custom language namespace in English. In our overlay, we would create a file named src/main/webapp/js/locale/en/custom.json which would contain our own strings. We copy over the subset of the JSON object structure from messages.json and make our edits there. Note that we don't copy the entire file, as we want the system to fall back to the upstream project's message strings unless we've explicitly overridden them. Next, we configure our ConfigurationPropertiesBean object's languageNamespaces property to hold the list of both custom and the default messages. In XML configuration it looks like this:

		<property name="languageNamespaces">
			<list>
				<value>custom</value>
				<value>messages</value>
			</list>
		</property>

Note that the custom namespace is listed first, which means it will be checked first for any values, allowing it to override any display values in the defaults.

Now both the Java and JavaScript portions of the server application will display custom messages.