Developing Win32 Multilingual User Interface (MUI) Applications - PDF

Document Sample
Developing Win32 Multilingual User Interface (MUI) Applications - PDF Powered By Docstoc
					Developing Win32
Multilingual User
Interface
(MUI) Applications
Presentation Outline


  Intro to MUI
  MUI Support in Windows Vista
  Developing Win32 MUI Applications
  Q&A



                                      2
Presentation Goals

Attendees should leave this session with:
   An understanding of Windows Vista MUI Support
   Knowledge of how to develop Win32 MUI
   applications

Out of scope: localizability, fonts, keyboards/input, etc.




                                                         3
Assumptions

 Good understanding of the basics of writing
 globalized applications and the concept of UI
 resources.

 Familiarity with Windows Win32 application
 development, including resource loading API‟s.




                                                  4
INTRO TO MUI


               5
What is an MUI application?
A properly globalized Unicode application that:

   Can have multiple languages installed and in use.
   Follows system and user language preferences and
   fallback behavior whenever possible.
   Can be deployed properly on multilingual systems or
   system images.




                                                         6
Windows Vista MUI
Multilingual User Interface (MUI) technology:
  Provides a configuration-driven satellite model for
  resources.
  Supports system, user and application-specific UI
  language fallback for resource loading.

Goal: Reduce complexity and cost of creating,
deploying and maintaining Windows Vista for users
and developers worldwide.


                                                        7
Resource Models
Single-language      Multi-language          Satellite


      Code                Code                   Code


                                         Language neutral file
 Resources (ja-JP)   Resources (en-US)


                     Resources (ja-JP)
                                          Resources (en-US)



                                           Resources (ja-JP)



                                                                 8
Windows Vista Use of MUI

 Truly language-neutral base OS

 Language-specific content for all languages
 packaged as separately installable language packs.

 Multilingual images or distributions possible

 Two localization models
   Fully localized language
   Partial/LIP language

                                                      9
Benefits of Windows Vista MUI
Servicing
A single update package available to users of any
language
Single Worldwide Image
Minimize number of images needed for manufacturing or
deployment
Multilingual Desktop
Multiple users can share a single machine while still using
their own display language preferences
Applications
Windows Vista MUI is also available to application
developers
                                                          12
MUI in Windows Vista vs XP/WS03/W2K

XP/WS03/W2K
  Single-language images
  MUI add-on on top of the English OS
  Applications “on their own”


Windows Vista:
  Multilingual images possible
  Base OS is language neutral
  MUI support for applications


                                        13
MUI SUPPORT IN WINDOWS
VISTA

                         14
MUI Support in Windows Vista

 New UI language settings
 Resource loading and enumeration APIs
 now automatically search in satellite MUI
 files when appropriate.
 New UI management APIs for applications
 Tools to split localizable resources into
 satellite .mui files
 Enablers for other resource technologies:
 console, shell objects, etc.
                                             15
Windows UI Language Settings
 System Default UI Language
 System Preferred UI Language
 User Preferred UI Language
   System & User settings must use installed system
   languages.

 Thread Preferred UI Languages
   Up to 4 application languages.
   Need not be installed as system languages.



                                                      16
UI Language Fallback List

The merged UI Language Fallback list is an ordered
list of languages used by the resource loader to
search for resources.
It is made up of (in the following order):
  Per-thread application UI languages
  User preferred UI languages
  System preferred UI language
  System default UI language
Parent or base UI language inserted for partial and
LIP languages
                                                      17
UI Language Fallback List
Example

                          ar-SA                    ca-ES
     fr-FR,
                                                                       es-ES
     es-ES
                          en-US                    fr-FR
 Thread Preferred      User Preferred         System Preferred       System Default




   fr-FR       es-ES      ar-SA         en-US       ca-ES        fr-FR     es-ES


                       Fully Merged Preferred UI Language List




                                                                                      18
UI Management APIs
System UI Languages


EnumUILanguages
  Enumerates the list of installed system UI languages.


GetUILanguageInfo
  Gets information (e.g. language type, allowed fallback,
  etc) about a single installed system UI language.




                                                            19
UI Management APIs
System UI Language Settings

GetUserPreferredUILanguages
  Gets the user preferred UI languages


GetSystemPreferredUILanguages
  Gets the system preferred UI languages


GetSystemDefaultUILanguage
  Gets the system default UI language


                                           20
UI Management APIs
Application UI Language


Get/SetThreadPreferredUILanguages
  Get or set the application-specific thread preferred UI
  languages.
  Set and reset console filtering
  Get the merged UI language fallback list




                                                            21
UI Management APIs
General Purpose Language Probe

GetFileMUIPath
  Probes for files of any type using the UI language
  fallback list
  Looks in subdirectories using language name (e.g. “de-
  DE\Banner.jpg” for the German version of “Banner.jpg”)
  Returns path of any matching files that exist – does not
  load files or verify contents




                                                         22
UI Management APIs
General Notes


  Language specifications are generally multi-strings
  and must be double-NULL terminated.
  Languages can be specified or returned as either
  language names (e.g. “en-US”) or LCID (e.g.
  “0409”)
  Language names are preferred – not all languages
  have corresponding LCIDs
  Unicode only (no „A‟ or „W‟ variants)


                                                     23
Resource Enumeration APIs
EnumResource*
  Extended in Windows Vista to also search .MUI files
  Ex versions allow more control over enumeration

EnumResourceLanguages/Ex
  Enumerates all of the languages available for a specific
  resource.
  To determine the set of application UI languages that
  are installed, search for an application-specific
  resource.


                                                         24
File Version Info
“File Version” is a single resource but it has
 both neutral and language-specific elements.
  GetFileVersionInfo
    In Windows Vista, combines the neutral portion from
    the main module with the language-specific portion
    from the MUI file. This can affect servicing of MUI
    applications.
  GetFileVersionInfoEx
    Allows caller to specify file version resources from the
    main module, satellite MUI file, or merged.

                                                          25
DEVELOPING WIN32
MUI APPLICATIONS

                   26
Developing Win32 MUI Apps
Considerations

Best user experience: consistent language behavior
across the OS and applications

  Store localizable resources separately from code.
  Load resources according to OS UI Language.
  Package code separately from resources.
  Deploy cleanly on multilingual systems or system
  images.


                                                      27
Resource Technologies
Common resource technologies in Windows include:
  Win32
  Shell strings
  Help files
  Windows Event Log
  Group Policy
  WMI
  MFC resource DLL


Each resource technology has unique requirements

                                                   28
Storing and Installing Win32 Resources

•Store localizable resources in satellite .mui files:
   Use .rc files as before.
   Use the updated RC compiler or MUIRCT to generate .mui
   files.

•Install resource files in language folders using MUI
 naming conventions:
   E.g.      <install_dir>\foo.exe
             <install_dir>\en-US\foo.exe.mui




                                                            29
Loading Win32 Resources
•MUI support is handled transparently by the resource
 loader in Windows Vista:
   Use existing resource loading API calls without specifying
   language.
   Use the language neutral executable as the module name
   (not the .mui file).


•To set application specific languages, use
 SetThreadPreferredUILanguages



                                                                30
Building Win32 Resources
RC compiler, MUIRCT & RC Config

•Use the RC Compiler or MUIRCT to generate MUI
 files:
   At build time from source using RC compiler
   From compiled binaries using MUIRCT


•Use XML Resource Configuration (“RC Config”) file to
 specify which resources are to be stored in the .mui
 file



                                                    31
Building Win32 resources
RC Config Example
<?xml version="1.0" encoding="utf-8"?>
<localization>
 <resources>
        <win32Resources fileType="Application">
        <neutralResources>
          <resourceType typeNameId="#16" />
        </neutralResources>

        <localizedResources>
          <resourceType typeNameId="#2" itemId="5 6 7 8 9 10 11
          12" itemName="HTML PRI" />
          <resourceType typeNameId="#4" />
          <resourceType typeNameId="#16" />
        </localizedResources>
     </win32Resources >
 </resources>
</localization>




                                                                  32
Building Win32 resources
RC Compiler

 Source                 Compiled
            Compiler
  code                  .OBJ file



                                              LN PE file
                                     Linker
                                               (foo.exe)

                       Compiled LN
 .RC file               resources

            RC.exe
RC Config
   file                 Compiled
                                                 MUI file
                        Localized    Linker
                                              (foo.exe.mui)
                        resources




                                                      33
Building Win32 resources
RC Compiler

To split localizable resources into .mui files, use:

    Rc.exe -q <rc config filename> -fm <mui
     resource file name> <.rc file name>

 -q specifies the resource configuration file used to
   split resources
 -fm turns on MUI resource splitting and stores the
   localized resources in the specified file


                                                        34
Building Win32 Resources
MUIRCT



 Source
  code
                                             LN PE file
            Compiler   Executable             (foo.exe)
            & Linker    (foo.exe)
                                    MUIRCT
 .RC file                            .exe

                        RC Config
                                                MUI file
                           file
                                             (foo.exe.mui)




                                                        35
Building Win32 Resources
MUIRCT
To produce the language neutral and MUI files from an
 existing compiled windows binary with MUIRCT,
 execute the following:
   Muirct.exe –q <rc_config_filename> -f
    <source_Filename>
    [language_neutral_filename]
    [mui_filename]

MUIRCT has some additional functionality:
     Displays rc config embedded in an executable
      Muirct.exe –d filename
     Copies the checksum value from file1 into file 2
      Muirct.exe –c file1 –e file2 ()

                                                        36
Localizing Win32 Resources
•MUI files are just resource-only PE files
   Existing mechanisms to localize Win32 resources in an
   executable should work with MUI files.


•Source localization is also possible but is a bit more
 complicated:
   Localize RC files
   Build with RC Compiler
   Use MUIRCT to set compatible checksums




                                                           37
Sample Localization Workflow
Win32 Resources

1. Build executable “normally” with primary language.
2. Use MUIRCT and RC config file to split executable
   into language-neutral binary and primary language
   .mui file.
3. Make a copy of the .mui file and replace the
   original resources with localized resources for
   additional languages.
4. No standard tools for step 3.



                                                    38
Registry Strings
Don‟t store localizable strings in Registry
   Move localizable strings to a resource file
   Replace localizable registry values with a language neutral
   redirection string of the form “@res.dll,-resID”
   Call RegLoadMUIString to parse redirection strings and
   retrieve the specified resource, using consistent fallback
   logic.
   Use instead of RegGetValue
Windows Shell and other system components use
string redirection extensively.
   Follow the conventions for the specific OS technologies

                                                                 39
Shell Shortcuts
  Store Shell shortcut string as indirect strings like
  registry redirection
  Creating Shell shortcuts using:
    Shell APIs
      InfoTip

      IShellLink::SetDescription(“@%systemroot%\system32
      \shell32.dll,-9217”)

      Display Name
        SHSetLocalizedName(“@%systemroot%\system32\shell32.
           dll”, “@%systemroot%\system32\shell32.dll”, -9540)




                                                           40
Shell Shortcuts
  Creating Shell shortcuts using:
    INF File format
       Add the new value DisplayResource under the ProfileItems
        installation sections.
         [CalcInstallItems]
         "Name" = %Calc_DESC%
         "CmdLine" = 11, calc.exe
         "WorkingDir" = 11
         "InfoTip" = "@%systemroot%\system32\shell32.dll,-22531"
         "DisplayResource" =
            "%systemroot%\system32\shell32.dll,-22019"
         [Strings]
         Calc_DESC = “Calculator”




                                                                   41
Shell Shortcuts

To create Shell shortcuts using Windows Installer:
   In the MSI Shortcut table, specify the path as
   "@%systemroot%\system32\shell32.dll,-22531".


To display indirect Shell shortcut strings:
     Call SHLoadIndirectString




                                                     42
Help Files

  Use HTML Help 1.4, not .hlp
  Use Unicode
  Install help files using the folder convention:
     <Path>\mui\<langID>\my.chm
  Load help file using HtmlHelp API using relative
  path. E.g. “my.chm”




                                                     43
Windows Event Log
•Register the message file in the messageFileName
 attribute of the Provider element in the Event Manifest file
 <provider name="Microsoft-Windows-MUI" guid="{a8a1f2f6-
   a13a-45e9-b1fe-3419569e5ef2}" symbol="MUI_ETW_PROVIDER"
   resourceFileName="%SystemRoot%\system32\advapi32.dll"
   messageFileName="%SystemRoot%\system32\advapi32.dll"
   message="$(string.MUIEventProviderName)">

•Every description string for your event should be part of
 the localizable message resource string
 <event value="2000" version="0"
   symbol="MUI_ETW_EVENT_NOTIFY_ERROR"
   template="tid_MUI_ETW_EVENT_NOTIFY_ERROR"
   task="NotifyLanguageChange" opcode="Operation"
   channel="MUI_ETW_CHANNEL_OPERATIONAL"     level="win:Er
   ror"    message="$(string.MUI_ETW_EVENT_NOTIFY_ERROR.Ev
   entMessage)"/>
•Define localizable strings in the <localization> section of
 the instrumentation manifest.

                                                                44
Windows Event Log
•The description string can also contain placeholders for
 event payload fields to be substituted into the message:
 <string
   id="MUI_ETW_EVENT_NOTIFY_ERROR.EventMessage"    valu
   e="MUI notify operation failed with status code %1.
   No callbacks were invoked."/>


•Use MC.exe (message compiler) to generate an .RC file
 with the messages section.

• Then use RC.exe to split the localizable resources into
 .mui files. MC.exe is available in the Windows SDK.


                                                            45
Group Policy (.admx/.adml)
•In Windows Vista, registry-based policies are
 described by XML-based administrative template files,
 aka .ADMX files.
.admx: language neutral file describing the policy
   use reference string of the form "$(string.StringID)“ for
   displayName and explainText attributes
   Place in %windir%\policydefinitions
.adml: language resource file
   Language specific values for StringID
   Place in %windir%\policydefinitions\%lang-dir%


                                                               46
WMI (.mof/.mfl)
•A WMI provider consists of a Managed Object Format
 (MOF) file and DLL for the provider logic.
•Define WMI class for a provider in MOF file
•Mark localizable properties with “Amended” qualifier
•Use MOF compiler to produce:
   The language neutral .mof class information
   The LCID specific .mfl class information
•Specify locale to retrieve localized class information



                                                          47
MFC Resources
• Store localized MFC resources in satellite files with name fooENU.dll,
  fooJPN.dll, etc., and load using Windows‟ merged fallback list:
     Call GetThreadPreferredUILanguages to get fallback list (e.g.
     “ja-JP, es-ES, en-US”)
     Call GetLocaleInfo with LOCALE_SABBREVLANGNAME flag to
     get corresponding 3 letter language names (e.g. JPN, ESN, ENU)
     Construct satellite file name from abbreviated language name and
     search for the first available file according to fallback list (e.g. for
     foo.exe, search for fooJPN.dll followed by fooESN.dll and
     fooENU.dll )
     Use AfxLoadLibrary and AfxSetResourceHandle to bind the
     resource dll
• We plan to publish a helper function to probe for MFC resource
  satellites using MUI fallback rules.

                                                                            48
Storing and Loading Win32 Resources
Pre-Vista OS - XP/Server2003/Win2000


  “Down-level” resource loader does not support
  loading Win32 resources from Vista-compatible
  .mui files (LANGID vs. language names).
  To ensure that resources are loaded consistently
  from .mui files on both Vista and pre-Vista
  platforms, use LoadMUILibrary / FreeMUILibrary.
  Alternatively, build a separate set of binaries for
  pre-Vista platforms.


                                                        49
Console Applications
Console has some display limitations:
   Not Unicode so it can use only the current code page.
   Does not support complex scripts.
Workaround:
   Include bilingual resources for your console apps in an
   “Alternative Language” supported by all code pages.
   Call SetThreadPreferredUILanguages with the
   MUI_CONSOLE_FILTER flag. This will allow the resource
   loader to replace languages the console can not display with
   appropriate fallback languages.
   In most cases the console Alternative Language is English.


                                                              50
Packaging and Installation
Considerations
  Package the language neutral code and the UI
  resources for each language separately:
    Enable user to select the languages packs to install
  Allow independent installation and removal of
  language packs
  Be aware of the installed UI languages on the OS:
    Enable the installation of language packs to match system
    languages
  Be aware of the user‟s UI language preferences:
    Enable the installer to display its UI language according to the
    user‟s UI language preference

                                                                       51
Packaging Using Windows Installer
  Create language neutral MSI + language pack
  MSIs
  Create custom MSI bootstrapper to link the MSI
  packages together according to the OS installed
  languages
  Call EnumUILanguages to find out which system
  UI language packs are installed
  Localize UI resources for the installer into the
  languages supported by the application


                                                     52
Should I convert my existing
applications to MUI?
  Existing localized applications will work on Vista, but:
     Non-satellite resources are hard to deploy and service
     Inconsistent UI language leads to a bad user experience

  If you are using single- our multiple-language resources:
      Consider switching to satellite resource model.

  If you are using some other form of satellite resource model:
      Consider modifying it to use the merged UI language
      fallback list, for consistency with the OS



                                                              53
Q&A




  For more information, please see Michael
    Kaplan‟s blog “Sorting It All Out”, at:
       http://blogs.msdn.com/michkap
                                              54
Thank you



            55