Subversion Repositories SvarDOS

Rev

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

Rev Author Line No. Line
597 mateuszvis 1
 
814 mateusz.vi 2
 
599 mateuszvis 3
              SVARLANG.LIB - THE SVARDOS TRANSLATION C LIBRARY
597 mateuszvis 4
 
814 mateusz.vi 5
                   Copyright (C) 2021-2022 Mateusz Viste
597 mateuszvis 6
 
814 mateusz.vi 7
 
8
 
599 mateuszvis 9
SvarLANG is a library and tooling for enabling SvarDOS applications to easily
10
support multiple languages.
597 mateuszvis 11
 
599 mateuszvis 12
 
13
### PREPARING TRANSLATION FILES ###
14
 
15
The translation files must be CATS-style text files in the usual format:
16
 
17
1.1:Hello, World!
18
1.2:Help screen
19
2.0:Type /? for more options
20
 
21
The files must be named as EN.TXT, DE.TXT, FR.TXT, etc. Then, they must be
22
"compiled" into SvarLANG's binary format using the TLUMACZ tool:
23
 
24
tlumacz en fr pl (...)
25
 
26
The first language provided in the command line is the reference language and
27
is used both as the default (embedded in the application) language, as well as
28
to substitute messages missing in other languages.
29
 
30
TLUMACZ computes two files:
31
 
32
 * OUT.LNG   - the binary file that contains all translations
33
 * DEFLANG.C - the default translations that will be embedded into the program
34
 
35
Then, DEFLANG.C must be compiled and linked to your program along with
814 mateusz.vi 36
SVARLNGx.LIB. From there you will be able to use SvarLANG calls, typically:
599 mateuszvis 37
 
814 mateusz.vi 38
  svarlang_load("myprogram", "pl", "."); /* load .\myprogram.lng */
39
  puts(svarlang_str(2, 0));              /* display the string with id 2.0 */
599 mateuszvis 40
 
814 mateusz.vi 41
Read svarlang.h for more information about available functions.
599 mateuszvis 42
 
43
 
1114 mateusz.vi 44
### DIRTY STRINGS ###
45
 
46
In the CATS-style source translation, lines may be prefixed with a '?' sign:
47
 
48
?1.1:Hello, World!
49
 
50
Such string is used by tlumacz like any other, but it is also reported on the
51
command-line with a warning about the line being "dirty" (that is, requiring
52
to be reviewed by a translator).
53
 
54
 
599 mateuszvis 55
### ENVIRONMENT ###
56
 
814 mateusz.vi 57
The program translation file should be named "PROGNAME.LNG", where PROGNAME
58
is the program's name. This file should be placed in a well-known location,
59
typically the program's own directory. An exception are SvarDOS "CORE" programs
60
that store their translation files in a directory pointed out by %NLSPATH%.
599 mateuszvis 61
 
814 mateusz.vi 62
The %LANG% environment variable usually defines what language should be loaded,
63
albeit the program can just as well provide its own controls for language
64
selection and pass this information to svarlang_load() accordingly.
599 mateuszvis 65
 
66
 
67
### WHY IS IT BETTER THAN CATS? ###
68
 
69
The CATS library is heavier and slower, as it embeds a text-file parser.
70
Translations also take more disk space since each file is in a separate file
71
leading to cluster waste. Finally, CATS requires default strings to be part of
72
the application's source code, while SvarLANG keeps all strings in TXT files
73
and embedds the default one inside the application in an automated way at
74
compile time.
75
 
620 mateuszvis 76
There is also a licensing issue: CATS/Kitten libraries are published under the
77
terms of a viral license. SvarLANG, on the other hand, is published under a
78
truly free, liberal license (MIT).
599 mateuszvis 79
 
620 mateuszvis 80
 
599 mateuszvis 81
======================================================================= EOF ===