This document will explain in a few steps how to create and manage a project with vbLocalization Manager alpha.

Before starting to create your own project, you should go through these steps with the sample project provided in the download archive and read the issues listed below.

Remarks / Alpha Issues

Don't use the build-in editor unless you have a backup of your files!

Options dialog is in construction.

User Controls are not supported for source processing. To translate user controls all string resources should be exposed as public properties.

Save the vbLM project as often as possible to prevent data loss on runtime errors.

Source files are provided only as samples. Feel free to change source files to fit your needs. If you think that the changes you made are a benefit for all vbLM users, you might send me the changed files or suggestions and I will post them for download.

Please send bug reports, improvement suggestions or support requests by using the contact form on the VBX Homepage

Unicode Issues

Language files are saved in true Unicode (DBCS), meaning that natively all Unicode languages are supported by vbLM.

A problem is Cross-Codepaging, as VB6 does not support this feature: you won't be able to edit and display languages that use double byte non-ANSI characters on systems that don't have this specific codepage set as default. This is a VB 6.0 related problem, which is very difficult to solve on the various platforms (95 to XP).

Unicode language support for non-ANSI characters can be enabled only on NT Systems (NT, 2000, XP, 2003) and just for one specific language at a time.
Windows 2003 Server:
° Open Start -> Control Panel -> Regional and Language Options -> Advanced -> choose the language. You will have to reboot your machine.

Source Files

All source files needed for vbLM integration are located in the InstallDir\Source\Translation Kit folder. You can access the folder with the Source link in the programs start menu.

Don't add the original files to your project as they will change with every new vbLM version and are deleted on uninstall.
Always copy the source files into your VB project folder after checking the source changes history.

How to create a vbLM project

cLocalization class

Add the cLocalization class to your VB project (cLocalization.cls) and make sure that fso is declared on global level as Scripting.FileSystemObject (add the Microsoft Scripting Runtime reference).
Declare and initialize the cLocalization class once in a form or class module for event catching (optional) and once in a public module for global availability and quick access (use a short, easy to type name like lc). Please make sure that the variables are pointing to the same object; do not make two different instances of the cLocalization class.

See also: cLocalization - general, cLocalization - reference

Base class or main form:
Public WithEvents Localizer As cLocalization

Module:
Public lc As cLocalization
Public fso As Scripting.FileSystemObject

Public Sub Main()
    Set fso = New Scripting.FileSystemObject
    Set MyBaseClass.Localizer = New cLocalization
    Set lc = MyBaseClass.Localizer
End Sub

Preparing strings for implementation

All strings (excluding static control properties) needing translation must be passed to the cLocalization instance on runtime.
Static control localization will be done by a generated module, which you will have to add to your project. This issue will be discussed later on.

MsgBox lc("Translate this text")
lblInfo.Caption = lc("My name is %1", strName)
strInfo = lc("I live in %1", strCity)

Creating the vbLM project

When handling source files in vbLM, it's recommended to close the VB IDE, although files are not modified unless you use the build in editor.
Open vbLM and add the VB project file(s) or each source file individually to the vbLM project by using Project -> Add VB files... or dragging the files into the tree view.

Strings are automatically extracted from source files and added to the strings list.

Ignoring unwanted strings

Go to View -> Ignore lists -> Called procedures (Inclusion) and add a new element with the name of your global cLocalization instance (e.g. lc).
You will see that all strings that are not passed to the cLocalization object (excluding control properties) are automatically ignored.

Click on strings looking suspicious, ignore them by value, control, property or procedure with a right click on the element.
You should always ignore sub-controls like Font, properties like Key, LinkTopic etc globally by name or class name. This is very important, otherwise your app will crash if read only or logical values are changed on runtime.
In further versions these ignore elements will be automatically added on demand.

Static control localization

This feature enables runtime control localization.

Go to Project -> Control localization. Click the star button to add a new control localization module. Add a localization module for each individual VB project.
This one should be saved where all other VB source files are located.
Assign all forms that you want to translate with this module (checkboxes) and generate the module.

Save the project (recommended in the folder where the VB project is located), close vbLM and reopen the VB project.
Add the control localization module(s) to the project and make sure the main procedure is called whenever the user switches the language and for all opened forms.

The localization module template is located under InstallDir\Data\modCL.cmp and can be customized to fit your needs.

Note: localization modules are not processed when loading a VB project into vbLM, as they contain only redundant strings.

Private Sub Form_Load()
    SetFormLanguage Me
    ...
End Sub

Private Sub mnuLanguage_Click(Index As Integer)
    If Index = 0 Then
        'standard language
        lc.ClearTranslation
    Else
        'load the choosen language
        lc.Load mnuLanguage(Index).Caption
    End If
    SetFormLanguage Me
    ...
End Sub

Dynamic control localization

This feature is not supported by vbLM and must be individually programmed.
Dynamic controls are either created and loaded during runtime, so they are not existing in build time and can not be tracked from source code, or their string properties are changed in runtime according to dynamic settings.

Control properties or entire controls with dynamic string values must be added to the ignore lists, otherwise the properties will be overwritten with wrong values when languages are switched on runtime.

It is recommended to use a private form procedure that handles dynamic controls, which is called each time the user switches languages.

Private Sub SetDynFormLanguage()
    mnuActions(0).Caption = lc("Edit")
    mnuActions(1).Caption = lc("Delete")
    ...
End Sub

Preparing string resources for translation

Switch to Show ignored only filter and check if you have missed to pass a string to the cLocalization instance. You can easily edit the source file using the build-in editor (double click on the string list item).

Save the translation file (vbt) in the folder, your language files will be placed later. This file includes all relevant (not ignored) strings, some source information and is used as resource for third party translation. Language and translation files should be placed in a sub-folder of the main executable folder. (recommended: YourAppInstallDir\languages)

To enable third party translation, you can deliver the translation file (vbt) with the Translation Kit (vbLT.exe) or include the translation form in your application.

You can customize the Translation Kit as well as the translation form to fit your needs, although it is not recommended, as you will encounter difficulties while upgrading.

How to enable build in translation functionality

If you intend to provide build in translation functionality, please go through the following steps:

Add frmLocalization.frm (include frmLocalization.frx on copy) and cCommonDialog.cls to your project.

Take a look at the sample project provided in the installation.

The form must be initialized by passing the path of the translation file and the extension of language files. Language files are loaded only from the folder where the translation file is saved.

Dim froTranslation As frmTranslation
Set froTranslation = New frmTranslation
With froTranslation
    .Initialize App.Path & "\languages\myApp.vbt", "lng"
    .Show vbModal
End With

The user will now be able to edit and translate your app in any desired language.

Don't forget to provide the user with a menu or option panel to select one of the available language files.

Needed Runtimes

Following runtimes are needed while adding source files to your application. Please make sure to provide these runtimes in your installation package.

cLocalization: Microsoft® Scripting Runtimes 5.5 or above

frmTranslation: Microsoft® Common Dialog Control 6.0, Microsoft® Windows Common Controls 6.0