View source for Adding Language strings as resources

{{PageAuthor|CancerFace}}
NSIS forum [http://forums.winamp.com/showthread.php?s=&threadid=247680 thread]


== Description ==
This is a small tutorial that will help you add to an NSIS installer a Message Table resource with text strings that can be called and displayed from within the installer. Message Tables can contain multiple languages and can be edited using tools such as [http://www.angusj.com/resourcehacker/ Resource Hacker] without the need to recompile the installer. The advantage is that the end user can choose to alter the language table according to their own preferences/needs and add the strings they want in their own language.


== Procedure ==
The easiest way to achieve this is by first adding a Message Table to an existing version of the installer. A handy tool for that purpose is [http://www.wilsonc.demon.co.uk/d10resourceeditor.htm XN Resource Editor]. Note that the installer will not be usable once you add the new resource so it is a good idea/practice to have a backup.
=== Step 1 ===
Open the installer EXE file and from the Resource menu select Add Resource and then Message Table. Populate the table with as many strings as you like and then save the changes to the installer. Open the new installer file that contains the Message Table with Resource Hacker, select the newly created message table and from the Action menu select Save resource as a *res file. RES files are binary and cannot be easily edited, however once they are imported into an EXE using Resource hacker they can be readily manipulated.
=== Step 2 ===
Assuming that the RES file is called 'Lang_EN.res' and is located in a subfolder called 'Lang' inside your project's directory, add the following code to you NSIS script in order to add the Message table to the NSIS header when compiling your script:
<highlight-nsis>
CRCCheck off
!packhdr "$%TEMP%\exehead.dat" 'header.cmd'
</highlight-nsis>
=== Step 3 ===
Now generate the file header.cmd and place it inside your project directory. It should contain the following:
<highlight-nsis>
echo Adding Message Table resources
@echo off
"%ProgramFiles%\Resource Hacker\ResHacker.exe" -add "%TEMP%\exehead.dat", "%TEMP%\exehead.dat", "%~dps0Lang\Lang_EN.res" , MESSAGETABLE,,
echo.
echo Compressing the header with UPX (optional)
echo.
upx --best --compress-icons=0 "%TEMP%\exehead.dat"
echo.
</highlight-nsis>
I am using [http://upx.sourceforge.net/ upx] to compress the header but this optional (ignore the upx line).
=== Step 4 ===
Create a macro that will get the strings out of the Message Table and will store them in a string  for immediate use:
<highlight-nsis>
!macro GetMessage MESSAGE_ID VAR
   System::Call 'kernel32::GetModuleHandleA(i n)i .R1'
   System::Call 'kernel32::GetSystemDefaultLangID(i v)i .R2'
   System::Call 'kernel32::FormatMessageW(i 2559, i R1, i "${MESSAGE_ID}", i R2, *w .R3, i 0, i n) i .R4'
   StrCpy ${VAR} $R3
   System::Free $R1
!macroend
</highlight-nsis>
Call the macro when needed using the String ID that you want to extract from the Message table and use the string:
<highlight-nsis>
!insertmacro GetMessage 2 $R9
MessageBox MB_OK|MB_ICONINFORMATION "$R9"
</highlight-nsis>
=== Step 5 ===
Compile your installer :o)

== Adding New Language Tables ==
The main advantage of the above method is that you can add new language tables to your installer without having to recompile it. Simply open the installer with Resource Hacker, change the language ID of the Message Table to anything then use the Action/Add a new Resource option of Resource Hacker to add another RES file. Edit the resulting Message table changing the language ID of the new entry and adjust the included strings accordingly ([http://img73.imageshack.us/my.php?image=messagetables9yo.jpg screenshot])


== Notes ==
* It is a good idea to add an entry to your Message Table using 0 as the language (the equivalent of {LANG_NEUTRAL,SUBLANG_NEUTRAL}). This will ensure that if the language ID of a system is not found in the Message Table then the default strings will be used (those stored in the table with ID 0 as shown on this [http://img73.imageshack.us/my.php?image=messagetables9yo.jpg screenshot])

* If you don't add the 'CRCCheck off' directive in your script the installer will fail to run once you manually edit the Message Tables after compiling it


== Resources and Links ==
* NSIS forum [http://forums.winamp.com/showthread.php?s=&threadid=247680 thread]
* [http://www.angusj.com/resourcehacker/ Resource Hacker]
* [http://www.wilsonc.demon.co.uk/d10resourceeditor.htm XN Resource Editor]
* [http://upx.sourceforge.net/ UPX]
The above macro is using API calls to
* [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getmodulefilename.asp GetModuleFileName]
* [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getmodulehandle.asp GetModuleHandle]
* [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/intl/nls_4ppg.asp GetSystemDefaultLangID]
* [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/formatmessage.asp FormatMessage].

[[Category:Code Examples]]



[[User:CancerFace|CancerFace]] 13:05, 4 June 2006 (PDT)