See also: INTL FAQ and How to purchase INTL.

Contents

• Instancing INTL
• Localizing forms
• Automatic form localizaton
• Localizing menus
• Changing languages
• Changing languages on the fly
• Configuring INTL objects
• Configuring INTLs strategies
• Updating resource files automatically
• Localizing reports
• Localizing strings
• Localizing fonts
• Localizing data sources
• Localizing images
• Localizing currencies
• Localizing for right-to-left writing systems
• Customizing strategies
• Ignoring a particular object
• How to work with locales
• How to Configure Your Main INTL Object
• File placement
• Distributing INTL files

How to Correctly Place Your INTL Files

The important thing is for VFP to find INTLs files as needed. Heres where to put your INTL files so they are available to your development environment:

How to Instantiate an INTL Object

In order to use INTL, your application must instantiate an INTL object. There are many ways to do this, the best being to add it to _SCREEN, like this:

*-- Anywhere, anytime:
*-- Instantiate INTL in _SCREEN
*-- or anywhere you like.
SET PROCEDURE TO INTL ADDITIVE
_SCREEN.AddObject( "oINTL", "INTL" )

How To Localize Forms

Forms (and any other container) can be localized by passing it to the oINTL.Localize() method. Localize forms by passing their object references to the Localize() method of an INTL class object.

*-- Configure oINTL to another language
_SCREEN.oINTL.SetLanguage( "French" )
*-- Instantiate a form. If the form calls INTL in
*-- its INIT() method, then the form
*-- appears in French...
DO FORM MyForm Name MyForm

*-- ...or you can localize the form on the fly.
_SCREEN.oINTL.Localize( MyForm )

How to Get Automatic Form Localization

Place a call to oINTL in your Form.Init() hierarchy. To make your forms localize themselves automatically call the oINTL.Localize() method in your form class hierarchy. To do so, place the following code in the INIT() method of your form class definition.

*-- Don't forget to call the ParentClass!
DODEFAULT()
IF TYPE( "_SCREEN.oINTL" ) == "O"
_SCREEN.oINTL.Localize( This )
ENDIF

How to Localize Menus

A GENMENUX driver is used to localize menus. To activate GENMENUX and its INTL.PRG driver, put the following lines in your CONFIG.FPW:

* Add these lines to CONFIG.FPW.
*-- Configuring for INTL menus.
_GENMENU=GENMENUX.PRG
_MNXDRV2=INTL.PRG
*-- End of configuration for INTL menus.

Some of these changes require a VFP restart.

This change will take effect the next time you start Visual FoxPro. To avoid restarting FoxPro at this time, issue the following command in the command window:

_GENMENU=HOME()+"GENMENUX.PRG"

This is all you need to change in your development environment to localize menus. Henceforth generate menus as usual.

Note: GENMENUX does not replace Visual FoxPro's native menu generator. Since GENMENUX calls GENMENU.PRG, your code is generated by Visual FoxPro as usual. The INTL Toolkit uses GENMENUX as a pre-processor. GENMENUX is a rich program. Please see the GENMENUX section in the Appendix.

How to Change the Current Language

The structure of STRINGS.DBF determines which languages you support. Use the SetLanguage() method to change INTLs language.

INTL comes with a table named STRINGS.DBF which contains a variety of fields, one of which is cOriginal, and it may contain other fields for different languages, for example cFrench, cGerman, cSpanish, and so on.

The languages you support is determined by the structure of the STRINGS.DBF table. To add a new language, just change the structure of STRINGS.DBF.

To change the current localization language, use the SetLanguage() method. Say we want a form to be in French. First set the language, then we localize the form:

_SCREEN.oINTL.SetLanguage( "French" )
_SCREEN.oINTL.Localize( _SCREEN.ActiveForm )

How to Swap Languages on the Fly

Nothing demos better than swapping the display language on the fly. To swap languages on the fly, which is always a success in a demo ( do it even if it isn't required it's so easy ), create a mechanism in your application to configure the INTL object with SetLanguage(), as follows.

_SCREEN.oINTL.SetLanguage( "German" )
FOR i=1 TO ALEN( _SCREEN.Forms ) && Localize active forms
	_SCREEN.oINTL.Localize( _SCREEN.Forms[i] )
ENDFOR
DO MAIN.MPR && Refresh the menu too!

How To Work With Locales

To change your application's locale-based personality, I suggest you subclass INTL to work as you need. Here is an example of an INTL subclass that works for me in a variety of locales.

In this example, I've subclassed the INTL class to change all the locale-specific settings at one go. Subclassing INTL for your own needs is a great way to meet locale demands with a minimum of code and fuss.

DEFINE CLASS MyINTL AS INTL
FUNCTION SetLocale( tcLocale )

IF EMPTY( tcLocale )
	tcLocale=this.GetLocale()
ENDIF

IF DODEFAULT( @tcLocale )

	DO CASE
	CASE PROPER( tcLocale )= "Usa"
		SET CURRENCY TO "$"
		SET CURRENCY LEFT
		SET POINT TO "."
		SET SEPARATOR TO ","
		SET DATE TO American
		SET MARK TO "/"
		this.SetConversion( "Usa", 1.33 )
		this.SetLanguage( "USEnglish" )

	CASE PROPER( tcLocale )= "France"
		SET CURRENCY TO " F"
		SET CURRENCY RIGHT
		SET POINT TO ","
		SET SEPARATOR TO "."
		SET DATE TO DMY
		SET MARK TO "/"
		this.SetConversion( "France", 0.28 )
		this.SetLanguage( "French" )

	CASE PROPER( tcLocale )= "Uk"
		SET CURRENCY TO ""
		SET CURRENCY LEFT
		SET POINT TO ","
		SET SEPARATOR TO "."
		SET DATE TO British
		SET MARK TO "/"
		this.SetConversion( "Uk", 2.05 )
		this.SetLanguage( "BritEng" )

	CASE PROPER( tcLocale )= "Germany"
		SET CURRENCY TO " DM"
		SET CURRENCY RIGHT
		SET POINT TO ","
		SET SEPARATOR TO "."
		SET DATE TO DMY
		SET MARK TO "/"
		this.SetConversion( "Germany", 0.28 )
		this.SetLanguage( "German" )
	ENDCASE

ENDIF
ENDDEFINE

How to Configure Your Main INTL Object

I recommend making a main INTL object named _SCREEN.oINTL. It's possible to have several separate INTL objects co-exist together. Each INTL object is itself an amalgam of other INTL objects called hooks or strategies. Your main INTL object is the master INTL object in your environment, and whichever it happens to be, I assume here that it's called _SCREEN.oINTL.

Use the SetConfig( n ) method to configure your main INTL object. You configure INTL with a _SCREEN.oINTL.SetConfig( n ) method, where n is a bitwise integer value with the following interpretation:

Configuration integers for the .SetConfig() method for the various INTL classes.

Example: create an INTL object that localizes strings and fonts

*-- create an INTL object
_SCREEN.AddObject( "oINTL", "INTL" )
*-- Load the strings and font strategies.
_SCREEN.oINTL.SetConfig( 1+ 2 )

The operative language and locale of the main INTL object are configured with the SetLanguage() and SetLocale() methods.

How to Configure Strategies

Strategies are bitwise configured. Configuring individual strategies is easy. Simply get a reference to the strategy, then configure it. Here are the configuration meanings for each configurable strategy.

Configuration integers for the SetConfig() method for the various INTL classes.

To get a handle on a loaded strategy, use the ::GetStrategy() method. Thereafter, use the handle's SetConfig() method to configure the strategy.

Example: create an INTL object that localizes strings but not Tooltips. Use the oINTL.GetStrategy() method to get an object reference, then use its SetConfig() method to configure it.

*-- create an INTL object
_SCREEN.AddObject( "oINTL" "INTL" )

*-- Load the strings and font strategies.
_SCREEN.oINTL.SetConfig( 3 )

*-- Configure Strings to NOT localize ToolTips
LOCAL loTempHandle
loTempHandle= _SCREEN.oINTL.GetStrategy( "String" )

*-- For the string strategy, the configuration
*-- for Caption and StatusBarText is 5
loTempHandle.SetConfig( 1 + 4 )

Example: create an INTL object that localizes only strings and InputMasks.

*-- create an INTL object
_SCREEN.AddObject( "oINTL","INTL" )
*-- Load the strings and data strategies.
_SCREEN.oINTL.SetConfig( 5 )

*-- now modify the data strategy from its default.
LOCAL oTemp
oTemp= _SCREEN.oINTL.GetStrategy( "Data" )
*-- Input masks only.

oTemp.SetConfig( 16 )

How To Localize Strings

Interface strings are usually the first things that come to mind when we think of translating software. This table lists the configuration bits for INTL. These configuration bits decide which strategy is loaded. By default, only the String strategy is loaded, which is to say that strings are automatically localized by INTL by default.

So activate the string strategy as follows:

*-- cINTLString is loaded by default.
*-- So theres usually no need to do this
_SCREEN.oINTL.SetStrategy( "String", "cINTLString" )

Another more cryptic way to load the String strategy is:

*-- Set configuration bit 2^0 "ON"
_SCREEN.oINTL.SetConfing( BITSET( oINTL.GetConfing(),0))

So there are two ways to do it.

Strings can be localized by providing translations in STRINGS.DBF.

Configure the String Strategy with its SetConfig() method. The INTL String strategy, like all strategies, is bitwise-configured. You can control the string strategy object as follows:

Example: to disable font processing for the ToolTipText property:

*-- Get a handle on the string strategy:
oString= _SCREEN.oINTL.GetStrategy( "String" )

*-- We want Caption ( 1 ) and StatusbarText ( 4 ) only
oString.SetConfing( 5 )

How To Localize Fonts

Fonts can be locale-specific. Fonts like Arial, Times New Roman, MS Sans Serif might not be suitable in some languages. This matters; we may need a way to change fonts when we change locales.

The following table lists the configuration bits for the INTL object to load the Font strategy, and the configuration integers to configure the Font strategy:

So activate the font strategy as follows:

*-- cINTLFont is the Font strategy class.
_SCREEN.oINTL.SetStrategy( "Font", "cINTLFont" )

Another more cryptic way to load the Font strategy is:

*-- Set configuration bit 2^1 "ON"
_SCREEN.oINTL.SetConfing( BITSET( oINTL.GetConfing(),1))

So there are two ways to do it.

Fonts can be localized by providing translations in STRINGS.DBF. Font specifications are prefixed with the identifier "((Font))", like for example:

Configure the Font Strategy with its SetConfig() method. The INTL Font strategy, like all strategies, is bitwise-configured. You can control the font strategy object as follows:

Example: to disable font processing for DynamicFont and DynamicFontSize, which will slightly improve the font strategy performance:

*-- Set Font localization on
oINTL.SetConfing( BITSET( oINTL.GetConfing(), 1))
*-- Get a handle on the font strategy:
oFont= _SCREEN.oINTL.GetStrategy( "Font" )
*-- We want Font and FontSize and to disable DynamicFont
*-- and DynamicFontSize
oFont.SetConfing( 1 )

How To Localize Data Sources

Data can be locale-specific. Sometimes it is the data itself that needs to be localized. INTL allows you to present different fields for different locales. The Data strategy works just like the other strategies. The following table lists the configuration bits for the INTL object to load the Picture strategy, and the configuration integers to configure the Picture strategy.

So activate the data strategy as follows:

*-- cINTLData is the Graphics strategy class.
_SCREEN.oINTL.SetStrategy( "Data", "cINTLData" )

Another more cryptic way to load the Data strategy is:

*-- Set configuration bit 2^2 "ON"
_SCREEN.oINTL.SetConfing( BITSET( oINTL.GetConfing(),2))

So there are two ways to do it.

Data elements can be localized by providing translations in STRINGS.DBF. Data specifications are prefixed with the identifier "((Data))", like for example:

Configure the Data Strategy with its SetConfig() method. The INTL data strategy, like all strategies, is bitwise-configured. You can control the picture strategy object as follows:

Example: Localize ControlSource properties.

*-- Set Data localization on
*-- Set 2^2 "ON"
oINTL.SetConfing( BITSET( oINTL.GetConfing(), 2))
*-- Get a handle on the font strategy:
oData= _SCREEN.oINTL.GetStrategy( "Data" )
*-- We want ControlSource ( 2 )
*-- property localized.
oPicture.SetConfing( 2 )

How To Localize Images

Images can be locale-specific. Some of the icons and images we use every day may not be appropriate in other locales. INTL provides a way to change the displayed images when we change locales. The Picture strategy works just like the other strategies. The following table lists the configuration bits for the INTL object to load the Picture strategy, and the configuration integers to configure the Picture strategy.

So activate the picture strategy as follows:

*-- cINTLPicture is the Graphics strategy class.
_SCREEN.oINTL.SetStrategy( "Picture", "cINTLPicture" )

Another more cryptic way to load the Picture strategy is:

*-- Set configuration bit 2^3 "ON"
_SCREEN.oINTL.SetConfing( BITSET( oINTL.GetConfing(),3))

So there are two ways to do it.

Images can be localized by providing translations in STRINGS.DBF. Picture specifications are prefixed with the identifier "((Picture))", like for example:

Configure the Picture Strategy with its SetConfig() method. The INTL picture strategy, like all strategies, is bitwise-configured. You can control the picture strategy object as follows:

Example: Localize Picture, DownPicture, and Icon properties.

*-- Set Picture localization on
*-- Set 2^3 "ON"
oINTL.SetConfing( BITSET( oINTL.GetConfing(), 3))
*-- Get a handle on the font strategy:
oPicture= _SCREEN.oINTL.GetStrategy( "Picture" )
*-- We want Picture (1), DownPicture(2) and Icon (4)
*-- properties localized. 1+2+4= 7
oPicture.SetConfing( 7 )

How To Localize Currencies

INTL enables you to endow your application with a simple multi-currency capability. This architecture is flexible, and by subclassing the cINTLCurrency class you can probably implement almost any multi-currency scheme you need. At the heart of it all, the INTL Currency strategy works only on fields having a format property of "$".

Recall that INTL strategies are bitwise-configured according to the following table.

So activate the currency strategy as follows:

Use oINTL.SetConfig() or oINTL.SetStrategy() to load the Currency strategy.

oINTL= _SCREEN.oINTL
oINTL.SetStratrgy( "Currency", "cINTLCurrency" )

An alternate ( and more cryptic ) way is to use INTL's SetConfig() method to make INTL invoke the currencystrategy as follows:

OINTL= _SCREEN.oINTL
*-- Set bit 2^4 "ON"
oINTL.SetConfing( BITSET( oINTL.GetConfing(), 4))

So there are two ways to do it.

The Curremcy strategy is not like the others. The INTL toolkit currency strategy is a little different from other strategies in three important respects:

• Currencies are locale-specific, not language-specific.
• Class cINTLCurrency does not use class cINTLString services, and
• Class cINTLCurrency makes many input fields read-only when the data is in a converted state.

The default exchange rate for all currencies is 1.00

With the cINTLCurrency class you assign currency conversion factors to different currencies. By default the conversion factor used by the Currency strategy is 1.00.

If you need time-dependent currency conversions, you can subclass class cINTLCurrency to do anything you need it to do, such as lookups.

Let's configure INTL for the following currencies: Canadian dollar, German Mark, and US dollar. Assume that our data is based in Canadian dollars.

oINTL.SetConversion() sets the exchange rate between the original and other locales.

Use SetLocale() to change the currency locale.

Localize as usual.

oINTL= _SCREEN.oINTL
*-- Load the currency strategy
*-- Set 2^4 "ON"
oINTL.SetConfing( BITSET( oINTL.GetConfing(), 4))
*-- Define a few locales and currencies
oINTL.SetConversion( "Canada", 1 )
oINTL.SetConversion( "Germany", 0.96 )
oINTL.SetConversion( "USA", 1.33 )
*-- Lets assume we want to see it in US dollars
oINTL.SetLocale( "USA" )
*-- Localize the current form
oINTL.Localize( _SCREEN.ActiveForm )

How to Get Right-To-Left Localization

Most of the world does not read from left to right. Both the Oriental and Mid-Eastern writing systems read from right to left. INTL allows you to create applications whose interfaces can display from right to left.

Recall that INTL strategies are bitwise-configured according to the following table.

So activate the right-to-left strategy as follows:

Use oINTL.SetConfig() or oINTL.SetStrategy() to load the right-to-left strategy.

oINTL= _SCREEN.oINTL
oINTL.SetStratrgy( "RightToLeft", "cINTLRightToLeft" )

An alternate ( and more cryptic ) way is to use INTL's SetConfig() method to make INTL invoke the right-to-left strategy as follows:

OINTL= _SCREEN.oINTL
*-- Set bit 2^5 "ON"
oINTL.SetConfing( BITSET( oINTL.GetConfing(), 5 ))

So there are two ways to do it. When the right-to-left strategy is loaded, all your UI elements will be repositioned relative to their UI containers. The object captions will read right-to-left if their rightToLeft properties are true, and if you are using a Middle Eastern or Oriental version of Windows.

How to Create Your Own Generic Strategy

Just like you can subclass an existing strategy, you can create your own strategy and use INTL to automatically invoke it. Just make your new strategy a subclass of the cINTLStrategy class ( so you'll have the properties and methods INTL expects ) and then run with it!

Just as in the case of subclassing an existing strategy, use the SetStrategy() method to load your strategy into INTL.

How to Make INTL Ignore an Object

Three ways:

• You can make INTL ignore an object or a container object by placing the string "INTL Ignore" in the object's comment property. This string is not case sensitive.
• If you can, give your object's class an INTL property, and assign it logical .F.
• If you can, give your object's class an INTL property, and assign it a numeric value of less than 0.

How To Batch-Update Strings.DBF

INTL ships with iterator and visitor classes designed to recur VFP structures and, among other things, load all the string interface elements into the STRINGS.DBF.

How To Localize Reports

VFP report structures are not generated or compiled; they are bound into your application "as-is". Reports must therefore be transformed before the .APP or .EXE is created. INTL has tools to do this automatically.

The transformation process turns your report labels into report expressions containing a call to INTL's I() function. For example the report label "Name:" becomes expression I( "Name:" ).

How to Distribute INTL Files

For run time localization, you need to distribute the following files:

For the STRINGS and MSGSVC tables and files, if you include them in your APP or EXE then they will, of course, be read-only.

Purchase INTL