159 lines
5.6 KiB
Plaintext
159 lines
5.6 KiB
Plaintext
|
|
I18N: Pnetlib Internationalization Framework Libary
|
|
===================================================
|
|
|
|
Using the library
|
|
-----------------
|
|
|
|
This library provides plug-in i18n module support for C# base class
|
|
libraries such as pnetlib's "runtime". The base class library uses
|
|
it as follows:
|
|
|
|
- Load the "I18N.dll" assembly using "System.Reflection.Assembly.Load".
|
|
|
|
- Obtain the value of the static "PrimaryManager" property within the
|
|
"I18N.Common.Manager" class using "System.Reflection" facilities.
|
|
|
|
- Invoke methods on the manager class to obtain i18n-sensitive
|
|
objects such as "CultureInfo" and "Encoding" instances.
|
|
|
|
- The "I18N.Common.Manager" class loads the requested i18n object
|
|
and returns it to the base class library, which can then use it
|
|
in the usual fashion.
|
|
|
|
A more detailed example is given in a later section.
|
|
|
|
I18N handlers
|
|
-------------
|
|
|
|
Because there are so many i18n-sensitive cases to be handled, the culture
|
|
information has been split across several region-specific assemblies:
|
|
|
|
I18N.CJK.dll
|
|
I18N.MidEast.dll
|
|
I18N.Other.dll
|
|
I18N.Rare.dll
|
|
I18N.West.dll
|
|
|
|
The "I18N.dll" assembly only loads those region-specific assemblies that
|
|
it needs, based on the user's requests.
|
|
|
|
I18N handlers within these assemblies use the naming convention
|
|
"I18N.<Region>.<Prefix><Value>" where:
|
|
|
|
<Region>
|
|
The region handler. e.g. "West", "CJK", "India", etc.
|
|
|
|
<Prefix>
|
|
The prefix for the handler type.
|
|
|
|
<Value>
|
|
The identifier value which is supplied by the caller.
|
|
e.g. a culture identifier, an encoding name, etc.
|
|
|
|
The following prefixes are supported:
|
|
|
|
CP
|
|
Code page handler. e.g. "CP1252".
|
|
|
|
ENC
|
|
Web encoding handler. e.g. "ENCiso_8869_8".
|
|
|
|
CID
|
|
Culture, based on identifier. e.g. "CID2c01".
|
|
|
|
CIDO
|
|
|
|
Culture, based on identifier, with user overrides. e.g. "CIDO2c01".
|
|
Falls back to the "CID" handler if no override handler.
|
|
|
|
CN
|
|
Culture, based on name. e.g. "CNar_jo".
|
|
|
|
CNO
|
|
Culture, based on name, with user overrides. e.g. "CNOar_jo".
|
|
Falls back to the "CN" handler if no override handler.
|
|
|
|
Handlers that are based on name will normalize the name to be in all
|
|
lower case, with all instances of '-' replaced with '_'.
|
|
|
|
The "I18N.dll" assembly knows which region assembly to load from the
|
|
"I18N-handlers.def" file. This file is automatically generated during
|
|
the build process and contains a list of all I18N handler classes.
|
|
It must reside in the same directory as "I18N.dll".
|
|
|
|
Example
|
|
-------
|
|
|
|
As an example of the I18N loading process, we will describe what happens
|
|
when code page 932 is requested:
|
|
|
|
- The user's code calls "System.Text.Encoding.GetEncoding(932)".
|
|
|
|
- The "Encoding" class loads "I18N.dll" using reflection.
|
|
|
|
- The "Encoding" class accesses the "PrimaryManager" property via
|
|
reflection to get an instance of "I18N.Common.Manager".
|
|
|
|
- The "Encoding" class calls the "GetEncoding(int)" method on
|
|
the "I18N.Common.Manager" instance using reflection.
|
|
|
|
- "I18N.Common.Manager" constructs the name of the handler class - "CP932".
|
|
|
|
- The file "I18N-handlers.def" is consulted to determine the full
|
|
namespace and name of the "CP932" class - "I18N.CJK.CP932".
|
|
|
|
- The region assembly "I18N.CJK.dll" is loaded using reflection.
|
|
|
|
- An instance of the class "I18N.CJK.CP923" in the loaded assembly
|
|
is constructed and returned to the caller.
|
|
|
|
The results of previous requests are cached to smooth overall performance
|
|
of the system.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
This section describes the facilities that must be available from the
|
|
base class library to make the I18N framework function.
|
|
|
|
The framework makes heavy use of facilities from "System.Reflection"
|
|
to load assemblies and to access their contents.
|
|
|
|
String resources are assumed to be embedded as manifest string resources,
|
|
based on tag names. The "I18N.Common.Strings" class takes care of the
|
|
resource needs of all of the I18N assemblies. It relies upon a working
|
|
implementation of "ResourceManager", that can load and process manifest
|
|
string resources.
|
|
|
|
It is assumed that the base class library contains its own implementation
|
|
of the invariant culture. i.e. the invariant culture cannot be loaded
|
|
dynamically.
|
|
|
|
The "I18N.CJK.dll" assembly contains a single "InternalCall" method in
|
|
the "I18N.CJK.CodeTable" class if the "__PNET__" symbol is defined when
|
|
the assembly is compiled. This gives more efficient access to conversion
|
|
CJK tables when running on the Portable.NET runtime engine. If the
|
|
"__PNET__" symbol is not defined, then the implementation will fall back
|
|
to a less efficient way of loading the tables.
|
|
|
|
The method "System.Reflection.Assembly.GetFile(String)" is assumed to
|
|
have slightly different semantics to the .NET Framework SDK. Normally,
|
|
this method accesses a file that is listed in the assembly manifest.
|
|
We have extended it so that it can also access files in the same directory
|
|
as the assembly, even if not mentioned in the manifest.
|
|
|
|
The altered semantics is necessary to access the "I18N-handlers.def" file,
|
|
which defines which assembly contains which I18N handler. This file can
|
|
be altered by third parties to install new handler assemblies.
|
|
|
|
If the runtime engine does not implement the altered "GetFile" semantics,
|
|
the library will fall back to an internal list that must be maintained
|
|
internally and which cannot be dynamically extended by third parties.
|
|
|
|
Security considerations
|
|
-----------------------
|
|
|
|
The "GetAddress" and "GetFile" methods need to be implemented carefully
|
|
to prevent arbitrary applications using them to circumvent system security.
|