View source for DevTools:Locale Files

A locale file is stored in the '''locales.d''' folder under the Sword path. <br>
The file name is generally the language code with extension .conf <br>
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code.<br>
Other encodings are allowed, but the encoding should always be specified in the Meta section.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

 [Meta]
 Name=de
 Description=German
 Encoding=ISO8859-1

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.

=== Text ===
 
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
translated.

 [Text]
 Genesis=1. Mose
 Exodus=2. Mose
 Leviticus=3. Mose
 
 # <snipped rest of book names>

=== Abbreviations ===
 
 [Book Abbrevs]
 1 C=1Cor
 1 CHRONICLES=1Chr
 1 CORINTHIANS=1Cor
 1 JN=1Jn

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: 1Cor (which is the OSIS book id for 1 Corinthians)
has precedence up through "1 C", any character beyond that will
disambiguate the entry anyway, so the default 1 CHRONICLES or 1
CORINTHIANS entries would take over from there. 

English abbreviations are no longer required to 
be in the abbreviations section as they are in there by default; 
in the example above they are in there for demonstration purposes.

'''IMPORTANT''':

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.

Following are the REQUIRED entries from our excerpt book names above.
 1. MOSE=Gen
 2. MOSE=Ex
 3. MOSE=Lev

That's it for requirements.  Tuning your locale can be important for the 
user experience.  Many [Book Abbrevs] entries may be added to assign 
precedence 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 precedence, but might want Matthew or Mark). 
In this case, you would put in an entry MA=Matt or MA=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.

Note that other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.
 
Submissions should be sent to sword-support@crosswire.org

== Related Sword utilities ==
The following utilities make use of Sword locale files:
* vs2osisref - parse verse reference to OSISRef markup
* vs2osisreftext
The former is called by Perl scripts xrefmake.pl and xrefadd.pl that are available in CrossWire utilities.

== Maintained locale files ==
Locale files are not automatically installed with any of the front-end applications.<br>
On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt><br>
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]