Localization in the Preferences Framework makes use of message bundles: JSON files containing the strings that are to be used in the interface. The Preferences Framework combines any message bundles into a single bundle and makes that bundle available to the components that need to use the strings.
Message bundles are JSON files containing key/value pairs representing the message key and the localized text associated with it. Each set of localized text should be contained in its own message bundle.
Message bundles cannot contain arrays. Instead a namespace should be used to group message keys together. This will require extra processing when using the messages. (See Using Message Bundles below). Note that the namespace should not include ".", which is used for path parsing.
Understanding how to access message bundles is helped by understanding the general structure of the components of a preferences editor. The diagram below illustrates this structure and shows where the messages can be accessed. The rest of this page provides specific details about how to specify message bundles and how to retrieve strings.
All versions of preferences editors (separated panel, full page with preview and full page without preview) are instances of a "PrefsEditorLoader" components. The PrefsEditorLoader coordinates the work of its three subcomponents: MessageLoader, TemplateLoader and PrefsEditor. In particular, the PrefsEditorLoader
To access the message bundle from other components on the IoC tree, use
PrefsEditor is the host component that holds all the actual panel (or adjuster) components as subcomponents. By default, the message bundle is not passed down to PrefsEditor. If your PrefsEditor component will need direct access to the message bundle, provide it at the instantiation of any PrefsEditor instance, as shown in the following example:
If the message bundle is provided to PrefsEditor this way, access it within the PrefsEditor component using
The message bundle is attached to each panel component as the
parentBundle option. To access it from within a panel, use
Message bundles can be specified in one of two ways:
messageLoader(if grades are being used).
The Preferences Framework will load and combine all of the Message Bundles into a single Message Bundle which is bound to the
prefsEditorLoader component at the
msgResolver property (as described above).
Any panel that has the grade
"fluid.prefs.defaultPanel" will have access to the combined Message Bundle at its
parentBundle option (as described above). When using the auxiliary schema, all panels are assigned the grade
"fluid.prefs.defaultPanel" by the Framework.
Strings from the Message Bundles are rendered into the templates through the protoTrees, using the
messagekey, the name of the string in the bundle:
Message Bundles can also be resolved directly through an IoC reference making use of the
msgLookup property, which is automatically created for any panel component. This process is quite similar to how IoC references to selectors are resolved.
There are other, more complex cases where an array of strings is required (for example, for a set of radio buttons or a drop-down). In these cases, a
stringArrayIndex in the components options needs to be specified. This defines both
It is accessed the same way that an individual string is referenced, except that reference should point to the key in the
stringArrayIndex instead of a single string name. In the example below, the
stringArrayIndex is used on line 4 to define the
theme string bundle, and the
theme string bundle is referenced on line 15:
The strings can also be accessed directly, outside of the context of IoC references or renderer protoTrees (for example, in an invoker function), by making function calls to the internal string bundle