Subversion Repositories SvarDOS

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
597 mateuszvis 1
 
599 mateuszvis 2
              SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY
597 mateuszvis 3
 
4
 
599 mateuszvis 5
SvarLANG is a library and tooling for enabling SvarDOS applications to easily
6
support multiple languages.
597 mateuszvis 7
 
599 mateuszvis 8
 
9
### PREPARING TRANSLATION FILES ###
10
 
11
The translation files must be CATS-style text files in the usual format:
12
 
13
1.1:Hello, World!
14
1.2:Help screen
15
2.0:Type /? for more options
16
 
17
The files must be named as EN.TXT, DE.TXT, FR.TXT, etc. Then, they must be
18
"compiled" into SvarLANG's binary format using the TLUMACZ tool:
19
 
20
tlumacz en fr pl (...)
21
 
22
The first language provided in the command line is the reference language and
23
is used both as the default (embedded in the application) language, as well as
24
to substitute messages missing in other languages.
25
 
26
TLUMACZ computes two files:
27
 
28
 * OUT.LNG   - the binary file that contains all translations
29
 * DEFLANG.C - the default translations that will be embedded into the program
30
 
31
Then, DEFLANG.C must be compiled and linked to your program along with
32
SVARLNGx.LIB. From there, you will be able to use the following calls:
33
 
34
/* loads translations for program PROGNAME, language LANG, in the path NLSPATH.
35
 * returns 0 on success. */
36
int svarlang_load(const char *progname, const char *lang, const char *nlspath);
37
 
38
/* same as svarlang_load(), but relies on getenv() to pull LANG and NLSPATH. */
39
int svarlang_autoload(const char *progname);
40
 
41
/* Returns a pointer to the string "id". Does not require svalang_load() to be
42
 * executed, but then it will only return the reference language strings.
43
 * a string id is the concatenation of the CATS-style identifiers, for example
44
 * string 1,0 becomes 0x0100, string 2.10 is 0x020A, etc. */
45
const char *svarlang_strid(unsigned short id);
46
 
47
/* a convenience definition to fetch strings by their CATS-style pairs instead
48
 * of the 16-bit id. */
49
#define svarlang_str(x, y) svarlang_strid((x << 8) | y)
50
 
51
 
52
### ENVIRONMENT ###
53
 
54
All translations files should be placed in the %NLSPATH% directory and should
55
be named the same as the program's name, with the LNG extension (for example
56
"INSTALL.LNG" if the program is named "INSTALL").
57
 
58
The %LANG% environment variable defines what language should be loaded.
59
 
60
 
61
### WHY IS IT BETTER THAN CATS? ###
62
 
63
The CATS library is heavier and slower, as it embeds a text-file parser.
64
Translations also take more disk space since each file is in a separate file
65
leading to cluster waste. Finally, CATS requires default strings to be part of
66
the application's source code, while SvarLANG keeps all strings in TXT files
67
and embedds the default one inside the application in an automated way at
68
compile time.
69
 
620 mateuszvis 70
There is also a licensing issue: CATS/Kitten libraries are published under the
71
terms of a viral license. SvarLANG, on the other hand, is published under a
72
truly free, liberal license (MIT).
599 mateuszvis 73
 
620 mateuszvis 74
 
599 mateuszvis 75
======================================================================= EOF ===