Advanced Unblu Server i18n Configuration

1. Introduction 

The information on this page assumes you have already read Unblu Server i18n Configuration.

In addition to the standard localized text settings mechanisms described in Unblu Server i18n Configuration, unblu has a set of additional localized text settings features that allow for more complex and dynamic setups.

2. Dynamic reconfiguration

The unblu server has the ability to dynamically reload configuration while the server is running.

Dynamic reconfiguration must be triggered explicitly by calling the /sys-unblu/rest/propertyCascade/reload rest service. If your server is running on localhost on port 8080, you need to request http://localhost:8080/sys-unblu/rest/propertyCascade/reload to trigger dynamic reconfiguration. CAUTION: make sure the /sys-unblu path is properly protected (see security considerations).

Dynamic reconfiguration also works for configuration settings (see Unblu Server Configuration and Advanced Unblu Server Configuration).

3. Using multiple localized text files

Instead of using a single localized text file, it is also possible to split localized text in multiple files. Multiple localized text files are specified using a coma separated list of file path or urls in the "com.unblu.textoverlay" configuration setting instead of a single value (see using localized text configuration files).

# example for using multiple i18n properties files (extract from a configuration properties file)
com.unblu.textoverlay=http://configurationserver/unblu/unblu-text.properties,/etc/unblu/unblu-text.properties"	

This example specifies two localized text files: http://configurationserver/unblu/unblu-text.com and /opt/unblu/unblu-text.properties.

When using multiple localized text files, the ones that are defined later will always win over the ones defined earlier.

In the example above this means that properties defined in /opt/unblu/unblu-text.properties will win over properties defined in http://configurationserver/unblu/unblu-text.properties.

Using multiple localized text files can make sense for instance in an unblu cluster where servers share some but not all of the settings. A second scenario for using multiple localized text files is when there are multiple environments (i.e. prod, stage, development) that share most of the localized text settings but still need some individual configuration.

 

4. Scope specific localized texts

Usually localized properties are global to the unblu server, this means that a localized text property is always applied.

In addition to global configuration properties, unblu also provides a number of other scopes for localized text properties. Scoped localized text properties are only applied in a certain context, i.e. for a specific user or for a specific domain.

Scope specific configuration is only supported if xml (see XMLConfigurationFiles below) files are used (instead of java properties files).

The available configuration scopes are described below.

4.1. "global" scope

The global scope is the default scope. If using properties files for configuration, the scope is always global. Globally scoped properties are effective for whole unblu server.

4.2. "domain" scope

The domain scope is defined by the origin (schema + fully qualified domain) of the (web-) page the user is currently visiting. If an unblu installation is shared for multiple domains (i.e. http://trading.bank.com and http://www.bank.com), then domain scoped configuration can be used to apply individual configuration settings for the "trading" and the "www" part of the site.

4.3. "user" scope

The user scope is defined by the currently executing authenticated user. Using user scoped configuration settings, you can specify individual configuration for users.

5. XML Localized Text Files

In addition to java properties files, unblu also supports an xml based localized text file format. Certain localized text features (such as scope specific localized text, see above) are only supported in the xml based format.

The xml based format has the following general format.

 <?xml version="1.0" encoding="UTF-8"?>
<!-- this is a generic example of an unblu xml localized text file... SECTION1 and SECTION2 must be replaced by valid section elements (global, domain or user)
 <localizedText>
 	<SECTION1>
 		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
 	</SECTION1>
 	
 	<SECTION2>
 		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
 	</SECTION2> 
 </localizedText>

The xml file must be a valid xml file starting with a <?xml version="1.0" encoding="<character-encoding>"?> line. We recommend using UTF-8 (like in the sample above) but all other character encodings supported by the java virtual machine in use are also supported.

The document element MUST be named "localizedText".

The document element can contain any number of sections where every section must be a valid section as described below and must be unique within the file.

Every section can contain any number of property elements but MUST NOT contain more than one property element using the same key.

Everly property element MUST define a "key" attribute.

The value of the property is the text contents of the property element.

Section elements must conform with one of the section types described below.

5.1. Section Type "global"

The "global" section type defines properties that are valid globally (for the whole unblu server).

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of an xml localized text file with a global section -->
<localizedText>
	<global>
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</global>
</localizedText>

The "global" section type does not have any attributes and MUST not be declared more than once in a localized text file.

5.2. Section Type "domain"

The "domain" section type defines properties that are valid for a certain domain (fully qualified domain with protocol, <protocol>://<fqdn>:<optionalport>, i.e. http://www.unblu.com)

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of an xml localized text file with a domain section -->
<localizedText>
	<domain origin="http://www.unblu.com">
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</domain>
</localizedText>

The "domain" section type MUST declare an "origin" attribute holding the origin of the domain (fully qualified domain with protocol, no path, no trailing slash, i.e. http://www.unblu.com)

A localized text file MUST NOT contain more than one domain section with the same "origin" attribute.

5.3. Section Type "user"

The "user" section type defines properties that are valid for a certain authenticated user.

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of an xml localized text file with a user section -->
<localizedText>
	<user id="123456">
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</user>
</localizedText>

The "user" section type MUST declare an "id" attribute holding the id of the user the section is valid for.

A localized text file MUST NOT contain more than one user section with the same "id" attribute.

5.4. Example XML configuration file

Example of a valid xml localized text file. Property key must be valid keys (see Unblu Server i18n Configuration) for real life files.

<?xml version="1.0" encoding="UTF-8"?>
<localizedText>
	<global>
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</global>
	
	<domain origin="http://www.unblu.com">
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</domain>
	
	<domain origin="http://www.unblu.com">
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</domain>	
	
	
	<user id="12345">
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>
	</user>
	
	<user id="abcde">
		<property key="key1.en">value 1 english</property>
 		<property key="key1.de">value 1 german</property>
 		<property key="key2.en">value 2 english</property>
 		<property key="key2.de">value 2 german</property>	
	</user>	
</localizedText>



 

 


 

How can we help?

Chat with us and we will take you through our site!

Read about how we use cookies and how you can control them by clicking "Cookie Settings." If you continue to use this site, you consent to our use of cookies.