Skip to content

Creating or Updating a Language

If your language is not yet supported or you need to change to a different supported language, you need to read this section. Most developers will not need to make these types of changes. Translations, at this level, will normally be made by Data Access partners and then included in the standard product installation.

To make DataFlex ready for a different language, you will need to:

  • Create a df_Collate.cfg with the correct collating order of your language.
  • Convert the database error files to your language.
  • Convert the include files which contain all text used in the packages.
  • Convert any tool bar, status bar, and menus that you use that might contain text.
  • Convert template files to contain the desired menu items and include files.
  • Register your language in LanguageText.pkg.

Here is a list of all files that you need to change:

  1. The collate file must be created for your language:

  2. df_collate.cfg

  3. These error files must be translated:

  4. flexerrs.dat

  5. dferr001.dat

  6. This file must be updated with new language names:

  7. LanguageText.pkg

  8. These files must be renamed and translated:

  9. Language_English.inc
  10. Language_DD_English.inc
  11. Language_Winprint_English.inc
  12. DefaultToolbar.pkg
  13. DfStdBtn.pkg
  14. File_pm.inc
  15. Help_pm.inc
  16. Helpa_pm.inc
  17. Navi_pm.inc

  18. Win_pm.inc

  19. These files must be translated and have their #include and use commands adjusted:

  20. DefaultCommandBarSystem.tpl
  21. TestWindowsProject.tpl
  22. WindowsProject.tpl
  23. TestWindowsProjectOldMenus.tpl
  24. WindowsProjectOldMenus.tpl

Hopefully, you will not need to create all these files. In many cases, you will be updating these files from a previous version. If this is the case, you will just be updating the changes – a fast process.

These steps are described below in detail.

Create Your df_collate.cfg File

Your translation language may or may not require a special collate config file. If a special collating sequence is not required, you may skip this step and not include a collate file in your language folder.

If a special collating sequence is required, you will need to create a file named df_collate.cfg and place it in your language folder. The method for creating such a file has not changed, so the chances are good that you already have this file. Previous versions of DataFlex gave this file a different name, collate.cfg. The proper name is now df_collate.cfg.

A section at the end of this document titled, "More Information on Creating a Collate File" describes the process for creating the df_collate.cfg file.

The same collate file name, df_collate.cfg, is used for different languages. As you rename, move, and copy this file, be careful. We suggest that you keep copies of this and translated files in a separate language folder. For example, you may wish to keep files in folders named ..\usr\language\**. You will not actually open these files from this folder.

When you have finished working on this file, you should copy them back to your language folder.

Convert the Database Error Files to Your Language of Choice

DataFlex contains several error files that contain the text for all errors. You will want to convert the text to the language of your choice. Since all versions of DataFlex use the same named error files (flexerrs.dat, dferr001.dat, dferr002.dat, etc.), you need to make sure that your program finds the correct version of those files. Normally, those files are found in the \Usr folder.

The same error file names must be used for different languages. As you rename, move, and copy these files, be careful. We suggest that you keep copies of all your translated error files in a separate language folder. For example, you may wish to keep files in folders named ..\Usr\Language\**. You will not actually open these files from this folder.

So, we suggest that you take the current error data files in the \Usr folder and store them somewhere safe. If you have partially translated error files, copy them into \Usr and start with them. If you do not have partially translated files, use the current files.

You can use DataFlex’s Error Maintenance Utility to view and edit error text.

As you translate, you will notice that these error messages are limited to 40 characters. We recognize that this can make translation difficult - just do the best you can with this.

Errors may change with any revision. Be sure to check for changes with each new revision and add or change any translations as needed.

Convert Include Files Which Contain All Text Used in the Packages

You will need to translate the following text include files:

  • Language_**.inc
  • Language_DD_**.inc
  • Language_Winprint_**.inc

As you change the text, note that the parameters (%1, %2, etc.) may be moved around and used however you wish. Also note that you can change the length of the messages to any length required (limit is actually 1024).

These files can be created and maintained in the \pkg folder (as there is no naming conflict with existing files). When finished, you should copy these to your language folder.

Convert Any Tool Bar, Status Bar, and Menus That You Use That Might Contain Text

Normally, developers customize toolbars, status bars, and menus. To do this, they usually use our menu, toolbar, and status bar packages as starting points. Therefore, we want to translate these files so they can be used as examples. However, we do not want to use the text substitution method we used with our class packages as this would be very hard to read and would provide a bad model for developers to follow. Therefore, we need to translate all text directly in the standard toolbars and menus. We need to translate the following files:

  • DefaultToolbar.pkg - Our Basic Toolbar sample
  • DfStdBtn.pkg - Older Toolbar sample (replaced by DefaultToolbar.pkg)
  • File_pm.inc - File menu
  • Help_pm.inc - Help menu without “about” option
  • Helpa_pm.inc - Help menu with “about” option
  • Navi_pm.inc - Navigation Menu
  • Win_pm.inc - Windows menus

Note that our standard status bar, DefaultStatusbar.pkg, does not require translation.

We suggest you use the same file name convention used in the other files. Append the “_” to these files when you translate them. For example, DefaultToolbar.pkg would be named DefaultToolbar_Deutsch.pkg.

These files can be created and maintained in the \pkg folder (as there is no naming conflict with existing files). When finished, you should copy these to your language folder.

You can use any kind of tool you wish to aid in the translation of these files. Keep in mind that there are very few text files, and it is quite easy and fast to work with these within a text editor.

Here is some advice:

The first time you do this translation, you should make copies of the original files, renaming them as required. Load these into an OEM editor (the Studio works well) and translate the text. Try it. This is a fast process.

If you are translating an update (e.g., 8.3), the process is even simpler. We suggest you take the standard (English) files from your new and previous versions and do a file compare. That will generate a list of every line that has changed. We expect that list will be small. Now, load your previous revision translated file and make the changes as needed.

Warning: Remember that all of this text has to be stored in OEM format. Not all editors support OEM. For example, editing these files within Notepad will not give you the desired results. If you edit these files within the Studio, it will always be correct.

Convert Template Files to Contain the Desired Menu Items and Include Files

The two templates used to create new Windows projects (MDIApplication.tpl) and new Windows Test projects (TestWindowsProject.tpl) contain the menu structure of a typical MDI application.

You will need to copy those files from \Pkg\Config into your language folder and translate them, also replacing the included and used files with the name of the files you translated.

The typical code in the English version of those files is:

DFCreate_Menu Main_Menu
#INCLUDE File_pm.inc
DFCreate_Menu "&View" ViewPopupMenu is a ViewPopupMenu
End_Pull_Down
Set Status_Help To "Available Views"
DFCreate_Menu "&Report" ReportPopupMenu is a ViewPopupMenu
End_Pull_Down
Set Status_Help To "Available Reports"
#INCLUDE Navi_pm.inc
#INCLUDE Win_pm.inc
#INCLUDE Helpa_pm.inc
End_Menu  // Main_Menu
Use DefaultToolbar.pkg // Tool-Bar object.
Object oClientArea is a ClientArea
End_Object  // oClientArea
Use DefaultStatusbar.pkg // Status-Bar object.

The above code will need to be adjusted to the desired language in the two templates.

Register Your Language in LanguageText.pkg

You must make sure that your language is supported within LanguageText.pkg. Once defined, you can then select this language or any other supported language by changing the language selection package named Language_Current.pkg.

LanguageText.pkg defines all supported languages and is used to include the appropriate language text in your application. Here is what a typical file will look like:

// Package.pkg
// Generic Language include file.
// List all languages supported
Enumeration_list
define Language$English
define Language$Nederlands
define Language$Svenska
define Language$Deutsch
End_Enumeration_list
#Include Language_Current.inc // this will define Language$Current
#IFSAME Language$Current Language$English
#Include Language_English.inc
#ENDIF
#IFSAME Language$Current Language$Nederlands
#Include Language_Nederlands.inc
#ENDIF
#IFSAME Language$Current Language$Svenska
#Include Language_Svenska.inc
#ENDIF
#IFSAME Language$Current Language$Deutsch
#Include Language_Deutsch.inc
#ENDIF

Notice that this uses the convention of defining a language name with the line:

Define Language$

Then defining all language file names as FileName_**.

These files can be created and maintained in the \pkg folder (as there is no naming conflict with existing files). When finished, you should copy these to your language folder.

You are done.

Important Notes on df_collate.cfg

DataFlex’s collation sequence governs the creation and updating of indexes to database files and the sequencing of entries in various lists, including a number of the utilities. It also governs relative evaluation (greater than, less than) of strings. The file df_collate.cfg controls the precedence of characters for collation both for DataFlex utilities and for programs being run under the runtime system.

Serious disruption, including damage to data, can occur as a result of uninformed or malicious tampering with df_collate.cfg, which is a plain text file. If your system permits protecting the file in any way from being edited or deleted, you should employ such means immediately.

df_collate.cfg defines collating precedence by the order in which it "mentions," or covers, each character in the character set you are using. If you use DataFlex in a language other than English, or have special collation requirements of any kind, you may wish to check and modify df_collate.cfg for your specific requirements. If you ever base indexes on characters in the extended ASCII range (above 127), check the collation sequence carefully, even if your work is done exclusively in English. If you change df_collate.cfg, any database files that were created using a different collation sequence must be reindexed completely before any further use. If this step is not taken, searching the database will be disrupted immediately, and updates to indexes for additions, deletions, and edits will also occur incorrectly, making the searching problem progressively worse.

We strongly recommend that if you modify df_collate.cfg, you: 1. Keep a backup copy of df_collate.cfg in a different folder. 2. Add comments to the file indicating the nature, time, and authorship of the changes. 3. Test the resultant collation sequence carefully using a test program and data before it is used with any data that is in actual use.

df_collate.cfg is a plain text file and may be edited with any text editor. Every non-blank line of it must begin either with one of the three keywords or with a double slash (//), which may be followed by a comment. The keywords, which must be capitalized, are:

  • Single, for specifying the precedence of a single character by use of its ASCII code in decimal. For example, SINGLE 32 refers to the space character.
  • Range, for specifying the precedence of a range of characters by use of their ASCII codes in decimal, separated by a space. For example, RANGE 0 31 refers to the characters from ASCII 0 to ASCII 31, the control characters. Characters within a RANGE will be collated in the order of their ASCII codes.
  • Text, for specifying the precedence of characters by use of the characters themselves, embedded in quotation marks. For example, TEXT "AaBbCc" refers to the first three letters of the alphabet in both upper and lower cases. Characters in a TEXT statement will be collated in the order in which they are listed between the quotation marks and may not include any "white space" characters (space, tab, etc.).

All command lines may be used as many times as desired and should be intermingled so as to be in the order in which you desire the ranges and characters to be collated. Every character in your character set must be specified, and no character may be referred to twice throughout the file. Spaces should not be used except after keywords and between the bounds of a range. Errors of this kind in df_collate.cfg can seriously impair the use of databases, and any changed df_collate.cfg should be tested thoroughly before it is placed into actual use.

This is df_collate.cfg the way Data Access Worldwide ships it with DataFlex. As such, it is a definition of the DataFlex default collating sequence.

//
// Standard DataFlex Collate Table
//
// Control Characters
RANGE 0 31
// Special Characters
RANGE 32 47
RANGE 58 63
RANGE 91 96
RANGE 123 255
// Number
RANGE 48 57
// Alpha Characters
TEXT "@AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz"
// Finished.

See Also

Language Translation Guide