WebSVN – SvarDOS – Diff – /svarlang.lib/svarlang.txt


 
              SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY
 
 
SvarLANG is a library and tooling for enabling SvarDOS applications to easily
support multiple languages.
 
 
### PREPARING TRANSLATION FILES ###
 
The translation files must be CATS-style text files in the usual format:
 
1.1:Hello, World!
1.2:Help screen
2.0:Type /? for more options
 
The files must be named as EN.TXT, DE.TXT, FR.TXT, etc. Then, they must be
"compiled" into SvarLANG's binary format using the TLUMACZ tool:
 
tlumacz en fr pl (...)
 
The first language provided in the command line is the reference language and
is used both as the default (embedded in the application) language, as well as
to substitute messages missing in other languages.
 
TLUMACZ computes two files:
 
 * OUT.LNG   - the binary file that contains all translations
 * DEFLANG.C - the default translations that will be embedded into the program
 
Then, DEFLANG.C must be compiled and linked to your program along with
SVARLNGx.LIB. From there, you will be able to use the following calls:
 
/* loads translations for program PROGNAME, language LANG, in the path NLSPATH.
 * returns 0 on success. */
int svarlang_load(const char *progname, const char *lang, const char *nlspath);
 
/* same as svarlang_load(), but relies on getenv() to pull LANG and NLSPATH. */
int svarlang_autoload(const char *progname);
 
/* Returns a pointer to the string "id". Does not require svalang_load() to be
 * executed, but then it will only return the reference language strings.
 * a string id is the concatenation of the CATS-style identifiers, for example
 * string 1,0 becomes 0x0100, string 2.10 is 0x020A, etc. */
const char *svarlang_strid(unsigned short id);
 
/* a convenience definition to fetch strings by their CATS-style pairs instead
 * of the 16-bit id. */
#define svarlang_str(x, y) svarlang_strid((x << 8) | y)
 
 
### ENVIRONMENT ###
 
All translations files should be placed in the %NLSPATH% directory and should
be named the same as the program's name, with the LNG extension (for example
"INSTALL.LNG" if the program is named "INSTALL").
 
The %LANG% environment variable defines what language should be loaded.
 
 
### WHY IS IT BETTER THAN CATS? ###
 
The CATS library is heavier and slower, as it embeds a text-file parser.
Translations also take more disk space since each file is in a separate file
leading to cluster waste. Finally, CATS requires default strings to be part of
the application's source code, while SvarLANG keeps all strings in TXT files
and embedds the default one inside the application in an automated way at
compile time.
 
There is also a licensing issue: CATS/Kitten libraries are published under the
terms of a viral license. SvarLANG, on the other hand, is published under a
truly free, liberal license (MIT).
 
 
======================================================================= EOF ===
 

Subversion Repositories SvarDOS

(root)/svarlang.lib/svarlang.txt – Rev 599 → 620

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