9.2 The resource string file

When a unit is compiled that contains a resourcestring section, the compiler does 2 things:

  1. It generates a table that contains the value of the strings as declared in the sources.
  2. It generates a resource string file that contains the names of all strings, together with their declared values.

This approach has 2 advantages: first of all, the value of the string is always present in the program. If the programmer doesn’t care to translate the strings, the default values are always present in the binary. This also avoids having to provide a file containing the strings. Secondly, having all strings together in a compiler generated file ensures that all strings are together (you can have multiple resourcestring sections in 1 unit or program) and having this file in a fixed format, allows the programmer to choose his way of internationalization.

For each unit that is compiled and that contains a resourcestring section, the compiler generates a file that has the name of the unit, and an extension .rst. The format of this file is as follows:

  1. An empty line.
  2. A line starting with a hash sign (#) and the hash value of the string, preceded by the text hash value =.
  3. A third line, containing the name of the resource string in the format unitname.constantname, all lowercase, followed by an equal sign, and the string value, in a format equal to the pascal representation of this string. The line may be continued on the next line, in that case it reads as a pascal string expression with a plus sign in it.
  4. Another empty line.

If the unit contains no resourcestring section, no file is generated.

For example, the following unit:

unit rsdemo;  
{$mode delphi}  
  First = ’First’;  
  Second = ’A Second very long string that should cover more than 1 line’;  

Will result in the following resource string file:

# hash value = 5048740  
# hash value = 171989989  
rsdemo.second=’A Second very long string that should cover more than 1 li’+  

The hash value is calculated with the function Hash. It is present in the objpas unit. The value is the same value that the GNU gettext mechanism uses. It is in no way unique, and can only be used to speed up searches.

The rstconv utility that comes with the Free Pascal compiler allows manipulation of these resource string files. At the moment, it can only be used to make a .po file that can be fed to the GNU msgfmt program. If someone wishes to have another format (Win32 resource files spring to mind), one can enhance the rstconv program so it can generate other types of files as well. GNU gettext was chosen because it is available on all platforms, and is already widely used in the Unix and free software community. Since the Free Pascal team doesn’t want to restrict the use of resource strings, the .rst format was chosen to provide a neutral method, not restricted to any tool.

If you use resource strings in your units, and you want people to be able to translate the strings, you must provide the resource string file. Currently, there is no way to extract them from the unit file, though this is in principle possible. It is not required to do this, the program can be compiled without it, but then the translation of the strings isn’t possible.