/sved/tags/2023.1/svarlang/history.txt |
---|
0,0 → 1,28 |
20230730 |
- dropped svarlang_autoload() (replaced by more specialized functions below) |
- added svarlang_autoload_exepath() and svarlang_autoload_nlspath() |
- svarlang_load() simplified so it takes the target filename as an argument |
- file access relies on fopen() when svarlang is compiled with -DWITHSTDIO |
- new file format: sorted dictionary for faster lookup (by Bernd Boeckmann) |
breaking change! See svarlang.txt for file format specification |
20230630 |
- tlumacz.exe warns about empty strings (patch by Bernd Boeckmann) |
- tlumacz.exe does not abort when a malformed line is found |
20230629 |
- deflang.c has each message on a different line so it is nicer to VCSes |
20230628 |
- added support for \e sequences in translation strings |
- implemented svarlang_getver() |
20220314 |
- added support for flagging strings as being "dirty", eg: ?1.1:Hello, World |
20220309 |
- static lib buffer is sized to fit the largest lang block +5% of margin |
(was: twice the size of the reference language) |
20220226 |
- replaced fopen() and friends by direct DOS calls (smaller memory footprint) |
/sved/tags/2023.1/svarlang/svarlang.h |
---|
0,0 → 1,79 |
/* This file is part of the svarlang project and is published under the terms |
* of the MIT license. |
* |
* Copyright (C) 2021-2023 Mateusz Viste |
* |
* Permission is hereby granted, free of charge, to any person obtaining a |
* copy of this software and associated documentation files (the "Software"), |
* to deal in the Software without restriction, including without limitation |
* the rights to use, copy, modify, merge, publish, distribute, sublicense, |
* and/or sell copies of the Software, and to permit persons to whom the |
* Software is furnished to do so, subject to the following conditions: |
* |
* The above copyright notice and this permission notice shall be included in |
* all copies or substantial portions of the Software. |
* |
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
* DEALINGS IN THE SOFTWARE. |
*/ |
#ifndef SVARLANG_H |
#define SVARLANG_H |
/* library version */ |
#define SVARLANGVER "20230730" |
/* returns a pointer to a string with the SvarLANG's library version, |
* independently of the SVARLANGVER string above. */ |
const char *svarlang_getver(void); |
/* loads lang translations from file fname. |
* |
* only the two first letters of the lang strings are meaningful and they are |
* case insensitive. |
* |
* a typical call would be: svarlang_load("myprog.lng", "PL"); |
* |
* this function returns 0 on success, non-zero otherwise. It is still possible |
* to call svarlang_strid() after a load failure, the previously loaded |
* language will be used then, or the default language if no loading has been |
* done yet. */ |
int svarlang_load(const char *fname, const char *lang); |
/* tries loading lang strings from a file located in the executable's |
* directory that is named like the executable but with an *.LNG extension. |
* this is certainly the most practical way of loading svarlang. |
* selfexe should point to the executable's full filename path (either relative |
* or absolute). You may want to pass argv[0] or __argv[0] there. example: |
* |
* svarlang_autoload_exepath(argv[0], getenv("LANG")); |
*/ |
int svarlang_autoload_exepath(const char *selfexe, const char *lang); |
/* this looks in a list of paths separated by ';' to locate a translation file |
* for progname. this might be called by some FreeDOS programs that rely on the |
* NLSPATH environment variable for locating strings. example: |
* |
* svarlang_autoload_pathlist("myprog", getenv("NLSPATH"), getenv("LANG")); |
*/ |
int svarlang_autoload_pathlist(const char *progname, const char *pathlist, const char *lang); |
/* 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. |
* It NEVER returns NULL, if id not found then an empty string is returned */ |
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) |
#endif |
/sved/tags/2023.1/svarlang/svarlang.txt |
---|
0,0 → 1,123 |
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 ### |
/sved/tags/2023.1/svarlang/svarlngs.lib |
---|
Cannot display: file marked as a binary type. |
svn:mime-type = application/octet-stream |
Property changes: |
Added: svn:mime-type |
+application/octet-stream |
\ No newline at end of property |
/sved/tags/2023.1/svarlang/tlumacz.exe |
---|
Cannot display: file marked as a binary type. |
svn:mime-type = application/x-dosexec |
Property changes: |
Added: svn:mime-type |
+application/x-dosexec |
\ No newline at end of property |