Subversion Repositories SvarDOS

Rev

Rev 1386 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
1386 mateusz.vi 1
 
2
 
3
              SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY
4
 
5
                   Copyright (C) 2021-2023 Mateusz Viste
6
 
7
 
8
 
9
SvarLANG is a library and toolset for enabling SvarDOS applications to easily
10
support multiple languages. It is part of the SvarDOS project.
11
 
12
Homepage: http://svardos.org/svarlang/
13
 
14
 
15
### PREPARING TRANSLATION FILES ###############################################
16
 
17
The translation files must be CATS-style text files in the usual format:
18
 
19
1.1:Hello, World!
20
1.2:Help screen
21
2.0:Type /? for more options
22
 
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:
25
 
26
tlumacz en fr pl (...)
27
 
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
30
to substitute messages missing in other languages.
31
 
32
TLUMACZ computes two files:
33
 
34
 * OUT.LNG   - the binary file that contains all translations
35
 * DEFLANG.C - the default translations that will be embedded into the program
36
 
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
39
very basic example:
40
 
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 */
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
 
49
Read svarlang.h for more information about available functions.
50
 
51
 
52
### ESCAPED CHARACTERS ########################################################
53
 
54
Translation strings may contain some escaped characters. At this time only the
55
following escaped characters are supported: \e \r \n \t and \\
56
 
57
 
58
### DIRTY STRINGS #############################################################
59
 
60
In the CATS-style source translation, lines may be prefixed with a '?' sign:
61
 
62
?1.1:Hello, World!
63
 
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
66
to be reviewed by a translator).
67
 
68
 
69
### ENVIRONMENT ###############################################################
70
 
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,
73
typically the program's own directory.
74
 
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
77
selection and pass this information to svarlang_load() accordingly.
78
 
79
 
80
### WHY IS IT BETTER THAN CATS? ###############################################
81
 
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
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
86
in TXT files and embedds the default one inside the application in an automated
87
way at compile time.
88
 
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
91
under a truly free, liberal MIT license.
92
 
93
 
94
### FILE FORMAT ###############################################################
95
 
96
File =
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
99
    num_strings   : U16
100
    languages     : array[num_languages] of Language
101
 
102
Language =
103
    lang_id       : Char[2]
104
    len_strings   : U16 := SizeOf(strings)
105
    dictionary    : StringDict
106
    strings       : array[File.num_strings] of StringZ
107
 
108
StringDict =
109
    elements : array[File.num_strings] of DictEntry
110
             ; sorted by DictEntry.Id
111
 
112
DictEntry =
113
    id     : U16
114
    offset : U16
115
           ; relative to Language.strings[0]
116
 
117
StringZ = array[?] of Char ; zero-terminated string
118
 
119
 
120
NOTE: All numeric values are stored in x86 (little endian) order.
121
 
122
 
123
####################################################################### EOF ###