| 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-2024 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, like this
|
38 |
SVARLNGx.LIB. From there you will be able to use SvarLANG calls, like this
|
| 39 |
very basic example:
|
39 |
very basic example:
|
| 40 |
|
40 |
|
| 41 |
svarlang_load("myprogram.lng", "pl"); /* load PL lang from myprogram.lng */
|
41 |
svarlang_load("myprogram.lng", "pl"); /* load PL lang from myprogram.lng */
|
| 42 |
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 */
|
| 43 |
|
43 |
|
| 44 |
A more practical, real-world example would probably be this one:
|
44 |
A more practical, real-world example would probably be this one:
|
| 45 |
|
45 |
|
| 46 |
svarlang_autoload_exepath(argv[0], getenv("LANG"));
|
46 |
svarlang_autoload_exepath(argv[0], getenv("LANG"));
|
| 47 |
puts(svarlang_str(2, 0));
|
47 |
puts(svarlang_str(2, 0));
|
| 48 |
|
48 |
|
| 49 |
Read svarlang.h for more information about available functions.
|
49 |
Read svarlang.h for more information about available functions.
|
| 50 |
|
50 |
|
| 51 |
|
51 |
|
| 52 |
### ESCAPED CHARACTERS ########################################################
|
52 |
### ESCAPED CHARACTERS ########################################################
|
| 53 |
|
53 |
|
| 54 |
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
|
| 55 |
following escaped characters are supported: \e \r \n \t and \\
|
55 |
following escaped characters are supported: \e \r \n \t and \\
|
| 56 |
|
56 |
|
| 57 |
|
57 |
|
| 58 |
### DIRTY STRINGS #############################################################
|
58 |
### DIRTY STRINGS #############################################################
|
| 59 |
|
59 |
|
| 60 |
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:
|
| 61 |
|
61 |
|
| 62 |
?1.1:Hello, World!
|
62 |
?1.1:Hello, World!
|
| 63 |
|
63 |
|
| 64 |
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
|
| 65 |
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
|
| 66 |
to be reviewed by a translator).
|
66 |
to be reviewed by a translator).
|
| 67 |
|
67 |
|
| 68 |
|
68 |
|
| 69 |
### ENVIRONMENT ###############################################################
|
69 |
### ENVIRONMENT ###############################################################
|
| 70 |
|
70 |
|
| 71 |
The program translation file should be named "PROGNAME.LNG", where PROGNAME
|
71 |
The program translation file should be named "PROGNAME.LNG", where PROGNAME
|
| 72 |
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,
|
| 73 |
typically the program's own directory.
|
73 |
typically the program's own directory.
|
| 74 |
|
74 |
|
| 75 |
The %LANG% environment variable usually defines what language should be loaded,
|
75 |
The %LANG% environment variable usually defines what language should be loaded,
|
| 76 |
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
|
| 77 |
selection and pass this information to svarlang_load() accordingly.
|
77 |
selection and pass this information to svarlang_load() accordingly.
|
| 78 |
|
78 |
|
| 79 |
|
79 |
|
| 80 |
### WHY IS IT BETTER THAN CATS? ###############################################
|
80 |
### WHY IS IT BETTER THAN CATS? ###############################################
|
| 81 |
|
81 |
|
| 82 |
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.
|
| 83 |
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
|
| 84 |
separate file, leading to cluster waste. Finally, CATS requires default strings
|
84 |
separate file, leading to cluster waste. Finally, CATS requires default strings
|
| 85 |
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
|
| 86 |
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
|
| 87 |
way at compile time.
|
87 |
way at compile time.
|
| 88 |
|
88 |
|
| 89 |
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
|
| 90 |
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
|
| 91 |
under a truly free, liberal MIT license.
|
91 |
under a truly free, liberal MIT license.
|
| 92 |
|
92 |
|
| 93 |
|
93 |
|
| 94 |
### FILE FORMAT ###############################################################
|
94 |
### FILE FORMAT ###############################################################
|
| 95 |
|
95 |
|
| 96 |
File =
|
96 |
File =
|
| 97 |
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)
|
| 98 |
; 0x1a is an end-of-file marker that prevents TYPE garbage
|
98 |
; 0x1a is an end-of-file marker that prevents TYPE garbage
|
| 99 |
num_strings : U16
|
99 |
num_strings : U16
|
| 100 |
languages : array[num_languages] of Language
|
100 |
languages : array[num_languages] of Language
|
| 101 |
|
101 |
|
| 102 |
Language =
|
102 |
Language =
|
| 103 |
lang_id : Char[2]
|
103 |
lang_id : Char[2]
|
| 104 |
len_strings : U16 := SizeOf(strings)
|
104 |
len_strings : U16 := SizeOf(strings)
|
| 105 |
dictionary : StringDict
|
105 |
dictionary : StringDict
|
| 106 |
strings : array[File.num_strings] of StringZ
|
106 |
strings : array[File.num_strings] of StringZ
|
| 107 |
|
107 |
|
| 108 |
StringDict =
|
108 |
StringDict =
|
| 109 |
elements : array[File.num_strings] of DictEntry
|
109 |
elements : array[File.num_strings] of DictEntry
|
| 110 |
; sorted by DictEntry.Id
|
110 |
; sorted by DictEntry.Id
|
| 111 |
|
111 |
|
| 112 |
DictEntry =
|
112 |
DictEntry =
|
| 113 |
id : U16
|
113 |
id : U16
|
| 114 |
offset : U16
|
114 |
offset : U16
|
| 115 |
; relative to Language.strings[0]
|
115 |
; relative to Language.strings[0]
|
| 116 |
|
116 |
|
| 117 |
StringZ = array[?] of Char ; zero-terminated string
|
117 |
StringZ = array[?] of Char ; zero-terminated string
|
| 118 |
|
118 |
|
| 119 |
|
119 |
|
| 120 |
NOTE: All numeric values are stored in x86 (little endian) order.
|
120 |
NOTE: All numeric values are stored in x86 (little endian) order.
|
| 121 |
|
121 |
|
| 122 |
|
122 |
|
| 123 |
####################################################################### EOF ###
|
123 |
####################################################################### EOF ###
|
| 124 |
|
124 |
|