Guide - Locales, Tax Data, Currencies and Exchange Rates

1 Introduction

This guide outlines configuration and administration options with respect to locales, tax data, currencies and exchange rates. This document is addressed to system administrators or DevOps who configure and maintain Intershop Commerce Management instances.

Info

Prior to Intershop version 7.7 the information provided in this document were part of the Administration and Configuration Guide that can be found in the Knowledge Base.

In Intershop Commerce Management, locales, tax data, currencies and exchange rates are configured centrally by the system administrator, using a set of *.properties files. The system checks these configurations on application server startup. In case new configurations are detected, or changes to existing ones, the system automatically triggers the necessary updates, inserts, or deletions in the database.

Note

All relevant setup options are to be configured in advance via dedicated deployment script files, before actually executing the deployment. So be aware that if you modify the Intershop Commerce Management configuration after it is deployed, the next deployment will override all changes with the settings specified for your deployment.

1.1 Glossary

ConceptDescription
localeLocale refers to a set of parameters that defines the user's language, country and any special variant preferences that users expect to see in their user interface.
localization

Localization is the process of adapting internationalized software for a specific region or language by adding locale-specific components and translating text. Localization (which is potentially performed multiple times, for different locales) uses the infrastructure or flexibility provided by internationalization.

internationalization

Internationalization is the process of designing a software application so that it can potentially be adapted to various languages and regions without engineering changes. It is an integral part of ongoing development.

Internationalization must consider different languages and writing systems, different numeral systems, punctuation etc., as well as different economic conventions, including variations in number formats, address formats, currencies, systems of measurement, etc.

1.2 References

You should be familiar with the main concepts of the Intershop Commerce Management infrastructure. Refer to Overview - Infrastructure, Scaling and Performance.

For development-related information about locales and currencies, refer to Cookbook - Locales and Currencies.

2 Server Start Pipeline

The update mechanism for locales, tax data, currencies and exchange rates is based on a set of pipelines which are executed on server startup. The initial pipeline to start the update mechanism is configured in the <IS.INSTANCE.SHARE>/system/config/cluster/appserver.properties, using the following entry:

appserver.properties
intershop.pipelines.ExecuteUponServerStart = DefaultServerStartPipeline-Start

In a standard installation, this pipeline is already configured.

3 Prepare Locales

3.1 Locale Configuration Files

To add one or more locales and/or to set a new lead locale, you must create

  • the file localization.properties that lists the new locales
  • for every new locale, a formats configuration file <ISOLanguageCode>_<ISOCountryCode>.properties (such as en_US.properties.)

The files are stored in <IS.INSTANCE.SHARE>/system/config/cluster/.

Check the example files in <IS.INSTANCE.SHARE>/system/config/cluster/, including localization.properties.example, de_DE.properties.example, en_GB.properties.example and en_US.properties.example.

For the changes to become effective, the server must be restarted.

3.1.1 Add Locale

The configuration file localization.properties lists the locales to be added to the system in the following syntax

localization.properties
key = <ISOLanguageCode> <ISOCountryCode> <ISOCurrencyCode> <usedAsLeadLocale>

for example,

localization.properties
japanese = ja JP JPY false

3.1.2 Set Lead Locale

To set a new lead locale, use the last argument usedAsLeadLocale of the locale key, as defined in localization.properties, setting it true. Following the example above, use the following key to set Japanese as the new lead locale:

localization.properties
japanese = ja JP JPY true

3.1.3 Delete Locale

To delete existing locales, use the key deleteLocales in localization.properties. Each locale to be deleted must be identified by its ISOLanguageCode and ISOCountryCode joined by an underscore.

To delete Japanese and German, for example, use

localization.properties
deleteLocales = ja_JP de_DE

3.1.4 Set Locale-Specific Patterns

The configuration files <ISOLanguageCode>_<ISOCountryCode>.properties list format patterns for numbers, date, etc. to be used in the corresponding locale. The syntax of the patterns is identical to that documented in the JDK API specification for the classes DecimalFormat and SimpleDateFormat.

When adding a locale, adjust the patterns according to this locale and save the file as, for example, ru_RU.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.

Note

Do not alter the grouping character and decimal separator in the *Pattern keys. To define the characters to be displayed, use the *GroupingCharacter and *DecimalSeparator keys. In addition, escape non-ASCII characters with their UCN entities.

A locale configuration file for Russian may look, accordingly, like this:

ru_RU.properties
decimalNegativePattern = - #,##0.0#########
decimalPositivePattern = #,##0.0#########
decimalGroupingCharacter = \u0020
decimalDecimalSeparator = ,
shortCurrencyNegativePattern = - #,##0.00########
shortCurrencyPositivePattern = #,##0.00########
# currency symbol
longCurrencyNegativePattern = - #,##0.00######## *
longCurrencyPositivePattern = #,##0.00######## *
# currency ISO code mnemonic
# longCurrencyNegativePattern = - #,##0.00######## M
# longCurrencyPositivePattern = #,##0.00######## M
currencyGroupingCharacter = \u0020
currencyDecimalSeparator = ,
longDatePattern = dd.MM.yyyy
shortDatePattern = dd.MM.yyyy
timePattern = HH:mm:ss
dateTimeAMString =
dateTimePMString =
integerNegativePattern = -#,##0
integerPositivePattern = #,##0
integerGroupingCharacter = \u0020
integerDecimalCharacter = ,
shortQuantityNegativePattern = - #,##0.##########
shortQuantityPositivePattern = #,##0.##########
longQuantityNegativePattern = - #,##0.########## *
longQuantityPositivePattern = #,##0.########## *
quantityGroupingCharacter = \u0020
quantityDecimalCharacter = ,
inputDecimalNegativePattern = -#,##0.0#########
inputDecimalPositivePattern = #,##0.0#########
inputCurrencyNegativePattern = -#,##0.00########
inputCurrencyPositivePattern = #,##0.00########
inputDatePattern = dd.MM.yyyy
inputTimePattern = HH:mm
inputDateTimePattern = dd.MM.yyyy HH:mm
inputIntegerNegativePattern = -#,##0
inputIntegerPositivePattern = #,##0
inputQuantityNegativePattern = -#,##0.##########
inputQuantityPositivePattern = #,##0.##########
inputDatePatternUserHint = \u0434\u0434.\u043c\u043c.\u0433\u0433\u0433\u0433
inputTimePatternUserHint = \u0447\u0447:\u043c\u043c
impexDateTimePattern = dd.MM.yyyy HH:mm:ss

3.2 Locale Update Process

Upon adding a new locale, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/localization.lastupdate. This file records the "last modified" time and a backup of the actual configuration file for comparison at the next server start. If localization.properties is changed, the database will be updated again; if, however, the comparison does not indicate any changes, no action will be taken.

4 Prepare Tax Data Sets

Tax data sets can be configured for one or more channels or organizations, and define tax jurisdictions, tax jurisdiction mappings to countries and states, tax classes, a tax rate matrix and tax data set sharing relationships.

Note

Any existing items belonging to the configured channel or organization which do not appear in the tax data set are deleted from the database.

4.1 Tax Data Configuration Files

To update tax data in the database at server start, you must create the file taxdataset.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.

Check the example file taxdataset.properties.example contained in <IS.INSTANCE.SHARE>/system/config/cluster/.

This file comprises five sections: channel/organization specification, tax jurisdictions and country/state mappings, tax classes, tax rates, and tax sharing relationships.

The syntax is described below.

4.1.1 Channel/Organization Specification

Key

Description

Default.channel

Default.organization

Used to specify either the default channel or the default organization to which the tax data belong (optional). If not specified, each jurisdiction and tax class must be specifically assigned to a channel or organization.

4.1.2 Tax Jurisdiction and Country/State Mappings

<jid> is an identifier to group the attributes for one tax jurisdiction.

Key

Description

Jurisdiction.<jid>.name

Specifies the name for the tax jurisdiction

Jurisdiction.<jid>.channel
Jurisdiction.<jid>. organization

Specifies either the channel to which the tax jurisdiction belongs

If different from Default.channel or the organization to which the tax jurisdiction belongs if different from Default.organization (optional).

Jurisdiction.<jid>.default

Specifies whether this is the default jurisdiction, false if not specified (optional)

Jurisdiction.<jid>.mapping.<n>.country

Specifies a jurisdiction-country assignment

Make sure to specify all relevant names, identifiers etc. that may occur in your system for each country, like Germany and DE for Germany.

Jurisdiction.<jid>.mapping.<n>.state

Specifies a jurisdiction-state assignment (optional)

4.1.3 Tax Classes

<cid> serves as tax class ID. It is also used as an identifier to group the attributes for a tax class.

Key

Description

Class.<cid>.code

Specifies the tax class code

Class.<cid>.name

Specifies the name of the tax class

Class.<cid>.channel
Class.<cid>.organization

Specifies either the channel to which the tax class belongs

If different from Default.channel or the organization to which the tax class belongs if different from Default.organization (optional).

Class.<cid>.description

Specifies a short description of the tax class.

Class.<cid>.default

Specifies whether this is the default tax class, false if not specified (optional).

4.1.4 Tax Rates

Key

Description

Rate.<jid>.<cid>.value

Specifies the tax rate in the format xx.yyy, e.g., for 7.5%, set 0.075

Rate.<jid>.<cid>.validfrom

Specifies a valid-from date in the dd.mm.yyyy, e.g., 16.01.2004

Optional when .previous rate becomes invalid and .value becomes valid.

Rate.<jid>.<cid>.previous

Specifies an optional tax rate valid previous to .validfrom (format xx.yyy)

4.1.5 Tax Data Sharing

Each relationship needs to define:

  • The channel or organization from which the data is shared, and
  • The channel or organization to which the data is being shared.

Sharing the same tax data set with more than one channel(s)/organization(s) requires the definition of multiple relationships.

Note

Note that an identifier (<id>) is used to group sharing relationships.

Key

Description

Sharing.<id>.from.channel
Sharing.<id>.from.organization

Specifies either the channel or the organization that provides its tax data set to other channels/organizations

Sharing.<id>.to.channel
Sharing.<id>.to.organization

Specifies either the channel or the organization that uses the tax data set provided by other channels/organizations

Sharing.<id>.relationDefinitionName

Specifies the relation definition name, either TAX_CLASS or TAX_JURISDICTION

4.1.6 Example Configuration File

The following lines illustrate the tax data settings using one of Intershop Commerce Management's demo channels as an example.

# ### 1. Domain specification #######
Default.channel=PrimeTech-PrimeTechSpecials
# ### 2. Tax Jurisdictions ##########
Jurisdiction.GERMANY.name=Germany
Jurisdiction.GERMANY.default=true
Jurisdiction.GERMANY.mapping.1.country=Germany
Jurisdiction.GERMANY.mapping.2.country=DE
Jurisdiction.OTHER.name=Outside Germany
# ### 3. Tax Classes ################
Class.NORMAL.name=FullTax
Class.NORMAL.description=Full Tax charged
Class.NORMAL.default=true
Class.REDUCED.name=ReducedTax
Class.REDUCED.description=Reduced Tax charged
Class.ZERO.name=NoTax
Class.ZERO.description=No Tax charged
# ### 4. Tax Rates ##################
Rate.GERMANY.NORMAL.value=0.19
Rate.GERMANY.REDUCED.value=0.07
Rate.GERMANY.ZERO.value=0.0
Rate.OTHER.NORMAL.value=0.0
# ### 5. Sharing tax data sets ######
Sharing.1.from.channel=PrimeTech-PrimeTechSpecials
Sharing.1.to.channel=PrimeTech-ResellerChannel

4.2 Tax Data Update Process

Upon setting new tax data for a domain, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/taxdataset.lastupdate. This file records the "last modified" time and a backup of the current configuration file for comparison at the next server start. If taxdataset.properties is changed, the database will be updated again. If, however, the comparison does not indicate any changes, no action will be taken.

5 Prepare Currencies

The currency configuration file lists those currencies that should be enabled in the server, and, optionally, names a currency to be set as the lead currency.

Currencies not listed in the configuration file are disabled in the database. If the current lead currency is not listed as an active currency and no other currency is named as the lead currency, then the lead currency is not disabled.

5.1 Currency Configuration File

To update currency information in the database at server start, you must create the file activecurrencies.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.

Check the example file activecurrencies.properties.example contained in <IS.INSTANCE.SHARE>/system/config/cluster/.

This file lists the enabled currencies in the following syntax:

ActiveCurrency.<n>=<ISOCurrencyCode>

To enable a new lead currency, set

LeadCurrency=<ISOCurrencyCode>

A complete currency configuration file could look like this:

# Specifies which currencies should be set active
LeadCurrency=EUR
ActiveCurrency.1=GBP
ActiveCurrency.2=EUR

Applying this file to a standard Intershop Commerce Management installation, the currency EUR would replace USD as lead currency and USD would be no longer be listed as an active currency in the system.

5.2 Currency Update Process

Upon setting new currencies, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/activecurrencies.lastupdate. This file records the "last modified" time and a backup of the actual configuration file for comparison at the next server start. If activecurrencies.properties is changed, the database will be updated again; if, however, the comparison does not indicate any changes, no action will be taken.

5.3 Back-Office Currency Precision Configuration

The price display precision in the back office is configurable for each used currency. It is set via DBInit with the PrepareCurrencies preparer of the core cartridge, which reads the required values from the file currencies.resource, located in core/javasource/com/intershop/beehive/core/dbinit/data/currency.

This file contains comma-separated entries for each currency, and the last value specifies the rounding and display precision.

978;EUR;\u20AC;\u20AC;Euro;c;Cent;100;0.01;2;

The default precision value set for EUR is 2, so a value of 10.124, for example, is automatically rounded and displayed in the back office as 10.12.

6 Prepare Exchange Rates

The exchange rate configuration file lists those exchange rates that should be enabled in the server. The items listed in the file are inserted into or updated in the database as appropriate.

Exchange rates not listed in the configuration file are deleted from the database.

6.1 Exchange Rate Configuration File

To update exchange rates in the database at server start, you must create the file exchangerates.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.

Check the example file exchangerates.properties.example contained in <IS.INSTANCE.SHARE>/system/config/cluster/.

This file lists the enabled exchange rates in the following syntax:

ExchangeRate.<n>.From=<ISOCurrencyCode>
ExchangeRate.<n>.To =<ISOCurrencyCode>
ExchangeRate.<n>.Rate=a.b

where a.b is the from-to exchange rate with a dot (.) as decimal separator. For example, the following file

ExchangeRate.1.From=EUR
ExchangeRate.1.To =GBP
ExchangeRate.1.Rate=0.67

would delete all existing exchange rates apart from EUR to GBP and change the existing EUR-GBP rate to 0.67 (1 EUR is worth 0.67 GBP).

6.2 Exchange Rate Update Process

Upon setting new exchange rates, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/exchangerates.lastupdate. This file records the "last modified" time and a backup of the actual configuration file for comparison at the next server start. If exchangerates.properties is changed, the database will be updated again; if, however, the comparison does not indicate any changes, no action will be taken.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets