# TIP 399: Dynamic Locale Changing for msgcat
	Author:         Harald Oehlmann <harald.oehlmann@elmicron.de>
	State:          Accepted
	Type:           Project
	Vote:           Done
	Created:        27-Mar-2012
	Post-History:   
	Keywords:       Tcl,localization,msgcat
	Tcl-Version:    8.6
	Obsoleted-By:	412
-----

# Abstract

This TIP adds dynamic locale switching capabilities to the **msgcat**
package.

# Rationale

Within a multi-language application like a web-server, one may change the
locale quite frequently, for example if users with different locales are
requesting pages. Unfortunately, this does not fit well with the model adopted
by the **msgcat** package, which assumes that all code follows this
sequence:

 1.
 Set locale list: **mclocale** _locale_

 2.
 Load language files with other package load: **mcload** _msg-folder_

 3.
 Translate strings: **mc** _key args..._

Note that if the locale should be changed after other packages are loaded, one
must restart at step 2.  This requires reloading all packages which is mostly
not practical.
The key issue is that **mcload** only loads language files included in the
current locale \(**mcpreferences**\) and does not load any others.

The aim of this TIP is to extend **mcload** to load additional language
files.  Then **mclocale** may be called to change the locale on runtime
without the need to re-execute **mcload** \(which would normally imply to
reinitialise or reload the package\).

# Specification

This TIP proposes to add a new command:

 > **msgcat::mcconfig -pattern** ?_patternlist_?

This command may get or set package options.
There is currently one option "**-pattern**".

Options may be set using

 > **msgcat::mcconfig** _option value_ ?_option_? ?_value_?

Current option values may be read using:

 > **msgcat::mcconfig** _option_

## Option -pattern

The option **-pattern** consists of a list of language file name patterns
like **fr\***, **\***, or **fr\_ch**.

Any **mcload** command executed after this setting will consider this list _in addition_ to the current locale list.
Files are searched using a **glob** command per element on the specified pattern plus the string ".msg".
If "fr\*" is specified within the pattern list, the file search pattern is "fr\*.msg".

The default option value is the empty list \{\}.
In consequence, only files covered by the current locale list are sourced.

# Example Usage

Imagine an application which supports the current user language and French,
German and English.  An external package **tp** is used.  The package uses
**msgcat** and performes within the **package require tp** call:

	package require msgcat
	msgcat::mcload [file join [file dirname [info script]] msgs]

An implementation of the application with the current msgcat 1.4.4 would
require the following initialisation sequence:

	package require msgcat
	package require np

and the following code to change the locale to French:

	package forget np
	msgcat::mclocale fr
	package require np

Using the extension of this tip, the required code for initialisation is:

	package require msgcat
	msgcat::mcconfig -pattern {fr* de* en*}
	package require np

and to change to french locale:

	msgcat::mclocale fr

Within this modification, locale change is a cheap operation.  Before, it was
computational expensive \(if possible, as many packages are not reloadable or a
reload may disturb current processing, e.g., by forcing the closing of
sockets, etc.\).

# Reference Implementation

See Tcl Feature Request 3511941.
<http://sourceforge.net/support/tracker.php/?aid=3511941> 

# Compatibility

No incompatibilities are introduced.

# Issues

Packages might not be aware of a locale change and may buffer translations outside of **msgcat**.
Packages should not buffer msgcat messages if they are used in a dynamic locale application \(like tklib tooltip does for example\).

# Alternatives

This implementation requires the setting of the pattern before any package
with msgcat is loaded. To avoid this, msgcat must store all paths passed by
any **mcload** call. When a locale change happens, any currently missing
files are loaded. This requires much more housekeeping and may lead to side
effects, especially if packages are not aware of the fact that their package
files are loaded outside of the **mcload** command.

# Copyright

This document has been placed in the public domain.

