Revision as of 01:14, 19 August 2007

Documentation

Locale file layout

Locales require a few things. Let's step thru the German locale:

excerpts from /sword/locales/de.conf:

[Meta]
Name=de
Description=German

The above information is used to define the locale. They should be fairly obvious. Name should be taken from a standard abbrev, probably returned from echo $LANG. Please understand that this, and all entries are case sensitive.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible. Other things might be option name, value, tip, translations, or any text returned from the engine. It may not work right now, but if it doesn't, please post a message that you found a constant string in the engine not being tranlated.

[Text]
Genesis=1. Mose
Exodus=2. Mose
Leviticus=3. Mose

# <snipped rest of book names>

[Book Abbrevs]
1 C=46
1 CHRONICLES=13
1 CORINTHIANS=46
1 JN=62

These are the abbreviations for each book and are REQUIRED for the locale to work correctly in the engine. They are actually more than just abbreviations; they tell the parser how to incrementally parse versekey text. Notice that 1 Chronicles would come, alphabetically before 1 corinthians. The above entries say: book 46 (1 Corinthians) has precidence up thru "1 C", any character beyond that will unabiguate the entry anyway, so the default 1 CHRONICLES or 1 CORINTHIANS entries would take over from there.

IMPORTANT:

1) There MUST be at least 1 abbreviation entry for each book name comprised of a toupper (uppercase function) of the entire string EXACTLY as you have translated it in the [Text] section.

2) The English abbreviation entries MUST remain in the locale. The precidence entries may be tweeked, especially if you find them interferring with your precidence entries, but the entire book name-- as stated in the first requirement above, must remain for English book names.

Following are the REQUIRED entries from our excerpt book names above.

GENESIS=1
EXODUS=2
LEVITICUS=3

# <snip rest of english abbrevs>

1. MOSE=1
2. MOSE=2
3. MOSE=3

That's it for requirements. Tuning your locale can be important for the user experience. Many [Book Abbrevs] entries may be added to assign precidence if, for example, you find you are getting taken to the wrong entries from text like: "Ma 1:1" (would be Malachi by default because of alphabetical precidence, but might want Matthew or Mark).

You can test your locale with the sword/tests/parsekey test program (this program is in the sword source along with several other programs that are used to validate the configuration files) and try different strings to see how they parse. --- Submissions should be sent to scribe@crosswire.org