Using LangAgent in your projects

You should use the LSTR macro with all text messages you want to localize. Mind, that not every string should be localized. For example, file names or registry key names normally should not be translated. So, you have to review every string.

Mind, that the source files scanner is very simple in the current version and does not allow you to use strings that span over two or more lines with the LSTR macro. Thus, the LSTR macro should be located on a single line. A line may contain multiple LSTR macros. Avoid using ambigious phrases in the LSTR macros which can be translated in several ways. Keep in mind, that some languages have declinations and conjugations. The endings of adjectives can depend on the gender of a noun.

Here are the instructions how to integrate LangAgent into your project. We recommend you to review the sample projects that come with LangAgent. 

Standalone MFC Application

MFC DLL/COM/ActiveX

Complex product that consists of several projects inside (EXE and DLLs)

Non-MFC application

Advanced techniques

Standalone MFC Application

Here is the information how to integrate LangAgent into your application. Please, note that we provide a LangAgent Add-in for Developer Studio 6.0 that automates this process.

1. run LangAgent Workshop (la.exe) and setup project in the existing directory. This step is described in the next section (LangAgent Workshop reference).
   
2. add #include "/common/lagentRTL.h" to the stdafx.h
   
3. edit your application's InitInstance function in the following way:
   - move SetRegistryKey to the first line (if you use it)
   - put the LaInit() call to the second line
   
4. define the LANGAGENT symbol for all the configurations where you want to use LangAgent. you may not want to define this macro for the debug configuration. If LANGAGENT is not defined, the LSTR macro does not have any effect and LangAgent will be inactive.
   
5. add the post build step to the release config:
   la.exe $(ProjDir)\LANGAGENTPROJECTNAME /all
   
6. add the call to 
   LaUpdateWndMenu(pMainFrame->m_hWnd); to the bottom of the InitInstance
   you can skip this step if your APP is MDI and a child frame is 
   created in the InitInstance
   
7. add the call 
   LaUpdateWndMenu(m_hWnd); to every non-frame window with a menu (if any)
   However, you do not need to call this function for dialog boxes with a menu.
   
8. implement the lang selection menu as above if necessary (see below)
   

How to implement the language selection menu:

1. Create the Language submenu with a single item in it.
   
2. Allocate the block of 30 menu IDs starting from ID of the item in the Language submenu 
   _APS_NEXT_COMMAND_VALUE resource.h
   
3. add two lines into MESSAGE_MAP where the menu is being handled (your Application class):
   ON_COMMAND_RANGE(ID_LANGUAGE_FIRST, ID_LANGUAGE_FIRST+30, OnLanguageRange)
   ON_UPDATE_COMMAND_UI_RANGE(ID_LANGUAGE_ENGLISH, ID_LANGUAGE_ENGLISH+30, OnUpdateLanguageRange)
   where ID_LANGUAGE_FIRST - is an ID of the item in the Language submenu 
   
4. declare the OnLanguageRange and OnUpdateLanguageRange functions:
   afx_msg void OnLanguageRange(UINT);
   afx_msg void OnUpdateLanguageRange(CCmdUI* pCmdUI);
   
5. implement them in the following way:
   void CMyApp::OnLanguageRange(UINT nID)
   {
   LaOnLangSelCmdRange(nID-ID_LANGUAGE_ENGLISH);
   }
   void CMyApp::OnUpdateLanguageRange(CCmdUI* pCmdUI) 
   {
   LaOnUpdateLangSelRange(pCmdUI, ID_LANGUAGE_ENGLISH);
   }
   

That's all!

MFC DLL/COM/ActiveX

In general do the same as above. However, since DLL has no standard user interface, you should implement the language selection manually. Use the LaSetCurrentLang, LaGetLangCount, LaGetLangName and LaGetLang functions. If you are going to use the resulting DLL/COM/ActiveX together with an application that also uses LangAgent, please review the following section carefully. 

Complex product that consists of several projects inside (EXE and DLLs)

If your software product consists of several subprojects (the main program and one or several .DLL/.OCX) and you are going to use LangAgent in two or more subprojects, you are to:

1. Setup the main application as described above.
   
2. Setup all other projects in the same way, but adjust the call to LaInit to specify the message file (which is shared between all subprojects). Normally, message files have exatly the same name as the EXE program and .la file extension. Thus, the call to LaInit looks like:
   LaInit("MyExeName.la");
   
3. Implement the language selection in the main program only.
   

Non-MFC application

You can use LangAgent in a non-MFC application. You should manually implement the Language selection menu (use the LaSetCurrentLang, LaGetLangCount, LaGetLangName and LaGetLang functions). Mind, that you have to pay special attention to the resource strings. LangAgent can only translate the resource strings loaded using the MFC AfxLoadString function. In a non-MFC application you should handle them as follows:

LoadString(hInst, ID_MYSTRING, StrBuffer, sizeof StrBuffer);

LPCTSTR translatedStr = LaGetStr(StrBuffer);

// use translatedStr

Advanced techniques

You can adjust the LangAgent behavior using the LaInit function parameters. For instance, you can disable some languages in the application, specify the desired language order, use the message file encryption and so forth. Please, refer to the Run-time reference for more details.

LangAgent translates string resources, menus and dialogs only. Other resources are left untranslated. So if your application use language-specific icons, bitmaps, toolbars, WAVs, AVIs you should handle them manually. Please, bare in mind, that the current LangAgent version does not handle the HTML files (the support for HTML is being developed).