This document describes the language database mechanism implemented by version 0.1 of the jldb package. This document focusses on the use of language databases by the jstools applications, which require Tk, but the jldb package itself does not require Tk, so this mechanism can be used for non-graphical applications as well.
Assuming the application used the jldb mechanism consistently for displaying strings to the user, this database can be provided by the author or distributor of the application, by the person who installed it at your site, or by you, the end user of the application. Moreover, if you already have a database that has most of what you want, but you want to make a few changes in it, you don't need to create an entirely new database, you can just create one that has the changes you want in it and inherit most of your strings from the `parent' database. (You could handle differences between Australian and US English this way - or you could just change a few strings to match terminology used at your site, or to make them more concise or more descriptive.)
The least specific form of a language database name is just the official ISO 639 two-letter abbreviation for a language, such as en for English or fr for French. Optionally, a two-letter country abbreviation can be appended, separated by a period, such as es.ar for Argentine Spanish or la.fr for Latin as spoken in Gaul. (The country abbreviation is the same as a two-letter top-level Internet domain name, which mostly agrees with the ISO 3166 standard, except for uk instead of gb for Great Britain.) This can optionally be followed by another period and an arbitrary string to identify a more specific language practise, such as en.us.mit for English as used at the Massachusetts Institute of Technology. The process of tacking on more specific identifiers can continue indefinitely, so in theory you could specify US English as spoken by the President as en.us.dc.whitehouse.president, but in practise I suspect three levels - language, country, and perhaps an additional specifier for an organisation, a region within a country, or an individual - will be enough for most people.
When an application starts, it tries to read in your preferred language database, and all more general `parent' databases, starting with the most general database. For instance, if your preferred database is en.uk.susan, then the application will first try to read in the en database, then the en.uk database, and finally the en.uk.susan database. That way, strings specified in en.uk override strings in en, and strings in en.uk.susan override strings in either en or en.uk. Only those strings which differ between UK English and other varieties of English need be specified in en.uk, and Susan only needs to specify those strings she wants to change in en.uk.susan.
It's perfectly fine for not all language databases in the hierarchy to exist. For instance, if Sam's language preference is en.us.mit.sam and the are language databases called en and en.us.mit.sam for a particular application, but no databases called en.us or en.us.mit, then both existing databases will be read, and strings in en.us.mit.sam will override definitions in en.
If no language database at all is found for an application, it will use defaults specified by the application's author.
The directory path above is searched for each database (e.g., for de and then again for de.ch), but when a particular database is found in one of these directories, it is used, and the remaining directories are skipped for this database (although they may be searched again for a more specific database). An example will make this clearer:
For instance, if you wanted to translate the strings used in jdoc into Welsh, you would copy the provided English-language database from (perhaps) /usr/local/lib/jstools/jldb/jdoc/en to /usr/local/lib/jstools/jldb/jdoc/cy (because cy is the two-letter code for Welsh in ISO 639) and replace the English strings with Welsh ones. (Alternatively, you can copy it to ~/.tk/jldb/jdoc/cy, in case you don't have write permission under /usr/local.) You'd also need to copy and modify the jstools library database, (e.g.) /usr/local/lib/jstools/jldb/jstools/en, unless you'd already done so for a different application.
For details of the syntax used in language databases, you should see the documentation for the ::jldb::set_strings procedure in the jldb package. To summarise, however, the bulk of the database file consists of a series of entries, where each entry starts with a key. The key is fixed and should not be changed, even if it looks like a natural-language string, because it's how the application looks things up in the database. The second element of an entry is a string, which is the natural-language expression corresponding to the key in this particular language. (The string can contain embedded references to Tcl variables or Tcl commands, which will be substituted before the string is used.)
Some keys have up to three additional values as well as the string: a numeric underline position in the string (used to indicate an Alt-key shortcut in a menu entry), a Tk event specification used to create an accelerator binding (not necessarily involving the Alt key), and a short string to indicate the accelerator binding in a menu entry. All of these are optional. Again, for more details, see the documentation for the jldb package.
If you translate strings for any of the jstools applications (or the library) into any other languages, I would be very grateful to receive copies, so I can incorporate support for languages other than English into future releases.
{tires {Tires}} {hood {Hood}} {seats {Seats}} {paint {Paint Job}} {windows {Windows}} {radio {Radio}} {red {Red}} {black {Black}} {silver {Silver}} {gray {Gray}} {gold {Gold}} {yellow {Yellow}}and create a new database en.uk specifying just those strings you want to change:
{tires {Tyres}} {hood {Bonnet}} {gray {Grey}}Now, assuming your new database is installed system-wide, anyone whose language preference is en (or en.us, assuming there isn't a separate en.us database - or en.za, for that matter) will see the original strings in the database distributed with the application, but anyone whose language preference is en.uk will see the modified versions of those strings that differ.