Powerful localization tool for software developers

LangAgent runtime and API reference

Predefined macros

LANGAGENT_T or LANGAGENT
You should define either the LANGAGENT_T or LANGAGENT symbol in your project's configuration to make LangAgent active. If neither the LANGAGENT_T, nor LANGAGENT is defined, LangAgent will be inactive. In the inactive mode LangAgent does not perform any translation.

LSTR
LSTR is a key macro for LangAgent. Use it with any string in your project you want to translate. For example:
AfxMessageBox(LSTR("Text message goes here."));

The core functions

void LaInit(LPCTSTR langFileName=NULL, LPCTSTR password=NULL, LANGID defLang=0, LANGID *pGoodLangs=NULL, DWORD flags=0)

Initialize the LangAgent run-time engine. All parameters are optional and may be omitted.

LPCTSTR langFileName
Full name (including path) to the message file. If NULL, LangAgent will try to locate the message file as follows:
    - Check the current directory for <exename>.la
    - Check for the <exename>.la file in the folder where EXE file resides.
If the message file is not found, LangAgent will switch to the inactive mode.

LPCTSTR password
Password for the message file. The message file is encrypted with a password. You should set the password in the project configuration. The password passed to the LaInit function must match the password specified in the project configuration. The password protection feature is designed to make the unauthorized messages reading or/and modification difficult. However, please mind, that the encryption makes it difficult but does not make it impossible. LangAgent Runtime reads and decrypts messages, so a hacker may intercept them. However, it is much more difficult than a plain text editing. The default password is LangAgent.

LANGID defLang
By default LangAgent saves the last selected language.
However if no information about a previously selected language is available (for example when the user runs the program for the first time) OR if the LA_FLG_DONT_PERSIST_CURLANG flag is specified, LangAgent will switch to defLang. If defLang is zero (or unavailable), LangAgent will try to switch to the user system language. If it is unavailable either, LangAgent will switch to the first available language (the first language specified by the pGoodLangs parameter; if pGoodLangs is NULL, English is assumed).

LANGID *pGoodLangs
A pointer to the array of valid LANGIDs. This array should contain all supported LANGIDs followed by zero element. There are two reasons to use pGoodLangs. First, you may want to disable some languages. For example, your project is configured to support English, German and Spanish, however, you want to build the application with the support for English and German only (for example, translation into Spanish has not been completed yet). You simply pass a pointer to the array that contains LANGIDs for English and German only. The second reason to use the pGoodLangs parameter is to specify the language order. By default (if pGoodLangs is NULL), English is assigned to be the first language, all other languages are sorted alphabetically (according to their English names). If pGoodLangs is not NULL, LangAgent will handle languages in the specified order. Mind, that the first language has a special meaning. Under the certain circumstances it is used in the LaInit and in LaSetCurrentLang functions as a default language. Besides, the language order is used to fill the language selection menu. 

DWORD flags
Bitmask for flags. The following flags may be combined using the bitwise OR operator:

LA_FLG_NO_MENU_TRANSLATION
Do not translate menus on the fly.

LA_FLG_NO_STRING_TRANSLATION
Do not translate the resource string loaded by AfxLoadString on the fly.

LA_FLG_NO_DIALOG_TRANSLATION
Do not translate dialog boxes on the fly.

LA_FLG_NO_RESOURCE_TRANSLATION
Combination of the LA_FLG_NO_MENU_TRANSLATION, LA_FLG_NO_STRING_TRANSLATION and LA_FLG_NO_DIALOG_TRANSLATION flags. In other words, this flag fully suppresses the resource localization.

LA_FLG_DONT_PERSIST_CURLANG
By default LangAgent stores the user selected language in the registry. If the LA_FLG_DONT_PERSIST_CURLANG flag is specified, LangAgent does not track the user selection. Specify the language to use in the defLang parameter.

LPCTSTR LaGetStr(LPCTSTR lpcszStr);

Translate the given string into the currently selected language. Normally, you should not call this function directly. Use the LSTR macro instead.

BOOL LaSetCurrentLang(LANGID wLangId, BOOL FailIfNotAvailable);

Switch to the specified language. If the specified language is not available and the FailIfNotAvailable parameter is TRUE, the function does not change the current languages and returns FALSE. If the specified language is not available and the FailIfNotAvailable parameter is TRUE, the function switches to the first available language (normally English).

BOOL LaIsLangAvailable(LANGID lid);

Check if the specified language is available. Returns TRUE if yes. 

LANGID LaGetCurrentLang();

Returns the currently selected language.

Informational functions

int LaGetLangCount();

Returns the number of available languages.

LANGID LaGetLang(int i);

Returns LANGID for the language specified by the given zero-based index.  

LPCTSTR LaGetLangName(int i, LPTSTR buffer);

Get the language name (in English) by the given zero-based index. The language name is copied into the specified buffer (it must be large enough). If the buffer is NULL, the function uses the internal static buffer (and returns a pointer to the buffer). In this case the subsequent call overwrites the previous result. In this mode the function is not thread safe. 

Helper functions

void LaUpdateWndMenu(HWND); 

Call this function to translate the menu assigned to the specified window. You should call this function in your application's InitInstance function for the main window. Also, you should call it in every non-frame (and non-dialog) window in your application that has a menu. However, you do not need to call this function for the dialog boxes with a menu.

void LaOnUpdateLangSelRange(CCmdUI* pCmdUI, UINT firstID)
void LaOnLangSelCmdRange(int id);

The helper functions for the language selection menu implementation. Refer to the "How to implement language selection menu" section in the Using LangAgent chapter.

LPCTSTR LangToString(LANGID id, LPTSTR buffer);

Get the language name by its langid. It is the same as the call to the WinAPI GetLocaleInfo function with the LOCALE_SENGLANGUAGE flag. The language name is copied into the specified buffer (it must be large enough). If the buffer is NULL, the function uses the internal static buffer (and returns a pointer to the buffer). In this case the subsequent call overwrites the previous result. In this mode the function is not thread safe.  

Advanced functions

void LaSetupDlg(HWND hw);

Localizes the specified dialog box (and all its controls). This function is called automatically, normally you should not call this function.

BOOL LaSetupMenu(HMENU);

Localizes the specified menu. This function is called automatically, normally you should not call this function.