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


 
 
              SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY
 
                   Copyright (C) 2021-2023 Mateusz Viste
 
 
 
SvarLANG is a library and toolset for enabling SvarDOS applications to easily
support multiple languages. It is part of the SvarDOS project.
 
Homepage: http://svardos.org/svarlang/
 
 
### 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
converted 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 SvarLANG calls, like this
very basic example:
 
  svarlang_load("myprogram.lng", "pl");  /* load PL lang from myprogram.lng */
  puts(svarlang_str(2, 0));              /* display the string with id 2.0 */
 
A more practical, real-world example would probably be this one:
 
  svarlang_autoload_exepath(argv[0], getenv("LANG"));
  puts(svarlang_str(2, 0));
 
Read svarlang.h for more information about available functions.
 
 
### ESCAPED CHARACTERS ########################################################
 
Translation strings may contain some escaped characters. At this time only the
following escaped characters are supported: \e \r \n \t and \\
 
 
### DIRTY STRINGS #############################################################
 
In the CATS-style source translation, lines may be prefixed with a '?' sign:
 
?1.1:Hello, World!
 
Such string is used by tlumacz like any other, but it is also reported on the
command-line with a warning about the line being "dirty" (that is, requiring
to be reviewed by a translator).
 
 
### ENVIRONMENT ###############################################################
 
The program translation file should be named "PROGNAME.LNG", where PROGNAME
is the program's name. This file should be placed in a well-known location,
typically the program's own directory.
 
 
The %LANG% environment variable usually defines what language should be loaded,
albeit the program can just as well provide its own controls for language
selection and pass this information to svarlang_load() accordingly.
 
 
### 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 language is stored 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, corrosive license. SvarLANG, on the other hand, is published
under a truly free, liberal MIT license.
 
 
### FILE FORMAT ###############################################################
 
File =
    magic         : Char[4] := "SvL\x1a" (ie. "SvL" followed with a 0x1a char)
                  ; 0x1a is an end-of-file marker that prevents TYPE garbage
    num_strings   : U16
    languages     : array[num_languages] of Language
 
Language =
    lang_id       : Char[2]
    len_strings   : U16 := SizeOf(strings)
    dictionary    : StringDict
    strings       : array[File.num_strings] of StringZ
 
StringDict =
    elements : array[File.num_strings] of DictEntry
             ; sorted by DictEntry.Id
 
DictEntry =
    id     : U16
    offset : U16
           ; relative to Language.strings[0]
 
StringZ = array[?] of Char ; zero-terminated string
 
 
NOTE: All numeric values are stored in x86 (little endian) order.
 
 
####################################################################### EOF ###
 

Subversion Repositories SvarDOS

(root)/svarlang.lib/trunk/svarlang.txt – Rev 1297 → 1367

Rev 1297		Rev 1367
1		1
2		2
3	`SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY`	3	`SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY`
4		4
5	`Copyright (C) 2021-2023 Mateusz Viste`	5	`Copyright (C) 2021-2023 Mateusz Viste`
6		6
7		7
8		8
9	`SvarLANG is a library and toolset for enabling SvarDOS applications to easily`	9	`SvarLANG is a library and toolset for enabling SvarDOS applications to easily`
10	`support multiple languages. It is part of the SvarDOS project.`	10	`support multiple languages. It is part of the SvarDOS project.`
11		11
12	`Homepage: http://svardos.org/svarlang/`	12	`Homepage: http://svardos.org/svarlang/`
13		13
14		14
15	`### PREPARING TRANSLATION FILES ###############################################`	15	`### PREPARING TRANSLATION FILES ###############################################`
16		16
17	`The translation files must be CATS-style text files in the usual format:`	17	`The translation files must be CATS-style text files in the usual format:`
18		18
19	`1.1:Hello, World!`	19	`1.1:Hello, World!`
20	`1.2:Help screen`	20	`1.2:Help screen`
21	`2.0:Type /? for more options`	21	`2.0:Type /? for more options`
22		22
23	`The files must be named as EN.TXT, DE.TXT, FR.TXT, etc. Then, they must be`	23	`The files must be named as EN.TXT, DE.TXT, FR.TXT, etc. Then, they must be`
24	`converted into SvarLANG's binary format using the TLUMACZ tool:`	24	`converted into SvarLANG's binary format using the TLUMACZ tool:`
25		25
26	`tlumacz en fr pl (...)`	26	`tlumacz en fr pl (...)`
27		27
28	`The first language provided in the command line is the reference language and`	28	`The first language provided in the command line is the reference language and`
29	`is used both as the default (embedded in the application) language, as well as`	29	`is used both as the default (embedded in the application) language, as well as`
30	`to substitute messages missing in other languages.`	30	`to substitute messages missing in other languages.`
31		31
32	`TLUMACZ computes two files:`	32	`TLUMACZ computes two files:`
33		33
34	`* OUT.LNG - the binary file that contains all translations`	34	`* OUT.LNG - the binary file that contains all translations`
35	`* DEFLANG.C - the default translations that will be embedded into the program`	35	`* DEFLANG.C - the default translations that will be embedded into the program`
36		36
37	`Then, DEFLANG.C must be compiled and linked to your program along with`	37	`Then, DEFLANG.C must be compiled and linked to your program along with`
38	`SVARLNGx.LIB. From there you will be able to use SvarLANG calls, typically:`	38	`SVARLNGx.LIB. From there you will be able to use SvarLANG calls, like this`
-		39	`very basic example:`
39		40
40	`svarlang_load("myprogram.lng", "pl"); /* load PL lang from myprogram.lng */`	41	`svarlang_load("myprogram.lng", "pl"); /* load PL lang from myprogram.lng */`
41	`puts(svarlang_str(2, 0)); /* display the string with id 2.0 */`	42	`puts(svarlang_str(2, 0)); /* display the string with id 2.0 */`
42		43
-		44	`A more practical, real-world example would probably be this one:`
-		45
-		46	`svarlang_autoload_exepath(argv[0], getenv("LANG"));`
-		47	`puts(svarlang_str(2, 0));`
-		48
43	`Read svarlang.h for more information about available functions.`	49	`Read svarlang.h for more information about available functions.`
44		50
45		51
46	`### ESCAPED CHARACTERS ########################################################`	52	`### ESCAPED CHARACTERS ########################################################`
47		53
48	`Translation strings may contain some escaped characters. At this time only the`	54	`Translation strings may contain some escaped characters. At this time only the`
49	`following escaped characters are supported: \e \r \n \t and \\`	55	`following escaped characters are supported: \e \r \n \t and \\`
50		56
51		57
52	`### DIRTY STRINGS #############################################################`	58	`### DIRTY STRINGS #############################################################`
53		59
54	`In the CATS-style source translation, lines may be prefixed with a '?' sign:`	60	`In the CATS-style source translation, lines may be prefixed with a '?' sign:`
55		61
56	`?1.1:Hello, World!`	62	`?1.1:Hello, World!`
57		63
58	`Such string is used by tlumacz like any other, but it is also reported on the`	64	`Such string is used by tlumacz like any other, but it is also reported on the`
59	`command-line with a warning about the line being "dirty" (that is, requiring`	65	`command-line with a warning about the line being "dirty" (that is, requiring`
60	`to be reviewed by a translator).`	66	`to be reviewed by a translator).`
61		67
62		68
63	`### ENVIRONMENT ###############################################################`	69	`### ENVIRONMENT ###############################################################`
64		70
65	`The program translation file should be named "PROGNAME.LNG", where PROGNAME`	71	`The program translation file should be named "PROGNAME.LNG", where PROGNAME`
66	`is the program's name. This file should be placed in a well-known location,`	72	`is the program's name. This file should be placed in a well-known location,`
67	`typically the program's own directory. An exception are SvarDOS "CORE" programs`	73	`typically the program's own directory.`
68	`that store their translation files in a directory pointed out by %NLSPATH%.`	-
69		74
70	`The %LANG% environment variable usually defines what language should be loaded,`	75	`The %LANG% environment variable usually defines what language should be loaded,`
71	`albeit the program can just as well provide its own controls for language`	76	`albeit the program can just as well provide its own controls for language`
72	`selection and pass this information to svarlang_load() accordingly.`	77	`selection and pass this information to svarlang_load() accordingly.`
73		78
74		79
75	`### WHY IS IT BETTER THAN CATS? ###############################################`	80	`### WHY IS IT BETTER THAN CATS? ###############################################`
76		81
77	`The CATS library is heavier and slower, as it embeds a text-file parser.`	82	`The CATS library is heavier and slower, as it embeds a text-file parser.`
78	`Translations also take more disk space since each language is stored in a`	83	`Translations also take more disk space since each language is stored in a`
79	`separate file, leading to cluster waste. Finally, CATS requires default strings`	84	`separate file, leading to cluster waste. Finally, CATS requires default strings`
80	`to be part of the application's source code, while SvarLANG keeps all strings`	85	`to be part of the application's source code, while SvarLANG keeps all strings`
81	`in TXT files and embedds the default one inside the application in an automated`	86	`in TXT files and embedds the default one inside the application in an automated`
82	`way at compile time.`	87	`way at compile time.`
83		88
84	`There is also a licensing issue: CATS/Kitten libraries are published under the`	89	`There is also a licensing issue: CATS/Kitten libraries are published under the`
85	`terms of a viral, corrosive license. SvarLANG, on the other hand, is published`	90	`terms of a viral, corrosive license. SvarLANG, on the other hand, is published`
86	`under a truly free, liberal MIT license.`	91	`under a truly free, liberal MIT license.`
87		92
88		93
89	`### FILE FORMAT ###############################################################`	94	`### FILE FORMAT ###############################################################`
90		95
91	`File =`	96	`File =`
92	`magic : Char[4] := "SvL\x1a" (ie. "SvL" followed with a 0x1a char)`	97	`magic : Char[4] := "SvL\x1a" (ie. "SvL" followed with a 0x1a char)`
93	`; 0x1a is an end-of-file marker that prevents TYPE garbage`	98	`; 0x1a is an end-of-file marker that prevents TYPE garbage`
94	`num_strings : U16`	99	`num_strings : U16`
95	`languages : array[num_languages] of Language`	100	`languages : array[num_languages] of Language`
96		101
97	`Language =`	102	`Language =`
98	`lang_id : Char[2]`	103	`lang_id : Char[2]`
99	`len_strings : U16 := SizeOf(strings)`	104	`len_strings : U16 := SizeOf(strings)`
100	`dictionary : StringDict`	105	`dictionary : StringDict`
101	`strings : array[File.num_strings] of StringZ`	106	`strings : array[File.num_strings] of StringZ`
102		107
103	`StringDict =`	108	`StringDict =`
104	`elements : array[File.num_strings] of DictEntry`	109	`elements : array[File.num_strings] of DictEntry`
105	`; sorted by DictEntry.Id`	110	`; sorted by DictEntry.Id`
106		111
107	`DictEntry =`	112	`DictEntry =`
108	`id : U16`	113	`id : U16`
109	`offset : U16`	114	`offset : U16`
110	`; relative to Language.strings[0]`	115	`; relative to Language.strings[0]`
111		116
112	`StringZ = array[?] of Char ; zero-terminated string`	117	`StringZ = array[?] of Char ; zero-terminated string`
113		118
114		119
115	`NOTE: All numeric values are stored in x86 (little endian) order.`	120	`NOTE: All numeric values are stored in x86 (little endian) order.`
116		121
117		122
118	`####################################################################### EOF ###`	123	`####################################################################### EOF ###`
119		124