9.3 Updating the string tables

Having compiled a program with resourcestrings is not enough to internationalize your program. At run-time, the program must initialize the string tables with the correct values for the anguage that the user selected. By default no such initialization is performed. All strings are initialized with their declared values.

The objpas unit provides the mechanism to correctly initialize the string tables. There is no need to include this unit in a uses clause, since it is automatically loaded when a program or unit is compiled in Delphi or objfpc mode. Since this is required to use resource strings, the unit is always loaded when needed.

The resource strings are stored in tables, one per unit, and one for the program, if it contains a resourcestring section as well. Each resourcestring is stored with it's name, hash value, default value, and the current value, all as AnsiStrings.

The objpas unit oers methods to retrieve the number of resourcestring tables, the number of strings per table, and the above information for each string. It also oers a method to set the current value of the strings.

Here are the declarations of all the functions:

Function ResourceStringTableCount : Longint;
Function ResourceStringCount(TableIndex : longint) : longint;
Function GetResourceStringName(TableIndex,
                               StringIndex : Longint) : Ansistring;
Function GetResourceStringHash(TableIndex,
                               StringIndex : Longint) : Longint;
Function GetResourceStringDefaultValue(TableIndex,
                                       StringIndex : Longint) : AnsiString;
Function GetResourceStringCurrentValue(TableIndex,
                                       StringIndex : Longint) : AnsiString;
Function SetResourceStringValue(TableIndex,
                                StringIndex : longint;
                                Value : Ansistring) : Boolean;
Procedure SetResourceStrings (SetFunction :  TResourceIterator);

Two other function exist, for convenience only:

Function Hash(S : AnsiString) : longint;
Procedure ResetResourceTables;

Here is a short explanation of what each function does. A more detailed explanation of the functions can be found in the Reference guide.

ResourceStringTableCount: returns the number of resource string tables in the program.
ResourceStringCount: returns the number of resource string entries in a given table (tables are denoted by a zero-based index).
GetResourceStringName: returns the name of a resource string in a resource table. This is the name of the unit, a dot (.) and the name of the string constant, all in lowercase. The strings are denoted by index, also zero-based.
GetResourceStringHash: returns the hash value of a resource string, as calculated by the compiler with the Hash function.
GetResourceStringDefaultValue: returns the default value of a resource string, i.e. the value that appears in the resource string declaration, and that is stored in the binary.
GetResourceStringCurrentValue: returns the current value of a resource string, i.e. the value set by the initialization (the default value), or the value set by some previous internationalization routine.
SetResourceStringValue: sets the current value of a resource string. This function must be called to initialize all strings.
SetResourceStrings: giving this function a callback will cause the calback to be called for all resource strings, one by one, and set the value of the string to the return value of the callback.

Two other functions exist, for convenience only:

Hash: can be used to calculate the hash value of a string. The hash value stored in the tables is the result of this function, applied on the default value. That value is calculated at compile time by the compiler.
ResetResourceTables: will reset all the resource strings to their default values. It is called by the initialization code of the objpas unit.

Given some Translate function, the following code would initialize all resource strings:

Var I,J : Longint;
    S : AnsiString;

begin
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      begin
      S:=Translate(GetResourceStringDefaultValue(I,J));
      SetResourceStringValue(I,J,S);
      end;
end;

Other methods are of course possible, and the Translate function can be implemented in a variety of ways.

[next] [prev] [prev-tail] [front] [up]