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.
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.
- Run LangAgent Workshop (la.exe) and setup project in the existing directory.
This step is described in the next section (LangAgent Workshop reference).
- Add #include "/common/lagentRTL.h" to the stdafx.h
- 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.
- 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.
- Add the post build step to the release config:
la.exe $(ProjDir)\LANGAGENTPROJECTNAME /all
- 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
- 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.
- Implement the lang selection menu as above if necessary (see below).
That's all! Don't forget to include two new files: lartl.dll or
lartlu.dll into your product's distribution
packages if your application is UNICODE, and the message file (<yourproject>.la)
How to implement the language selection menu:
- Create the Language submenu with a single item in it.
- Allocate the block of 30 menu IDs starting from ID of the item in the Language
submenu
_APS_NEXT_COMMAND_VALUE resource.h
- 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
- Declare the OnLanguageRange and OnUpdateLanguageRange functions:
afx_msg void OnLanguageRange(UINT);
afx_msg void OnUpdateLanguageRange(CCmdUI* pCmdUI);
- 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!
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.
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:
- Setup the main application as described above.
- 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");
- Implement the language selection in the main program only.
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
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.
|