summaryrefslogtreecommitdiff
path: root/support/dktools/sttfiles.dox
blob: d79bf7aafce74d0213cfaed5cbf8e73039be2ca9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
/**	@page	sttfiles	String table files

@section	secsttfiles	String table files

An application can contain a set of default strings, i.e. in English.
These default strings are hard-coded in the sources.

When the application is run, it can detect the users language and region
and search for an appropriate string table files containing replacement
strings to use instead of the default strings.

@section	secsttsource	String tables in source code

We use an example to show it.

In the *.ctr, *.cpt or *.wxc file write:
~~~~~~~~~~~~~~~{.c}
const dkChar * const	default_strings[] = {
$!string-table	macro=dkT
#
#	0: Welcome greeting "Hello"
#
Hello.
#
#	1: Goodbye greeting "Goodbye"
#
Goodbye.
$!end
};

const dkChar * const	*msgs = default_strings;

static size_t sz_msg = (sizeof(default_strings)/sizeof(DK4_PDKCHAR) - 1);
~~~~~~~~~~~~~~~
The lines started by '#' character are comments.
I recommend to have index numbers in comments as you later use
msgs[index] to access the strings.

This will result in the following code in the *.c or *.cpp file created:
~~~~~~~~~~~~~~~{.c}
const dkChar * const    default_strings[] = {
/* 0 */
dkT("Hello"),

/* 1 */
dkT("Goodbye"),

NULL
};

const dkChar * const    *msgs = default_strings;

static size_t sz_msg = (sizeof(default_strings)/sizeof(DK4_PDKCHAR) - 1);
~~~~~~~~~~~~~~~
The index numbers here are generated automatically.

We create a file ${datarootdir}/program/de/greetings.str:
~~~~~~~~~~~~~~~
#
#	0: Welcome greeting "Hello"
#
Guten Tag.
#
#	1: Goodbye greeting "Goodbye"
#
Auf Wiedersehen.
~~~~~~~~~~~~~~~
As you see we copied the contents from $!string-table to $!end into the
new text file. We left all comments and indices untouched, only the
texts were changed.

After
~~~~~~~~~~~~~~~{.c}
sz_msg = dk4app_string_table_size(default_strings);
msgs   = dk4app_string_table(app, dkT("greetings.str"), default_strings);
~~~~~~~~~~~~~~~
you can access msgs[0] and msgs[1] to use localized texts.

@section	secsttfileformat	File format

- The file consists of comment lines and text lines.
- Each line started by '#' is a comment line, all other lines are text lines.
- If a '#' character is required as start of the text, write "\#" instead.
- If a newline or tabulator is required, use "\n" or "\t".
- Strings are accessed by index in an array, so make sure to keep the
  indices unchanged (do not accidently add empty lines).
- The file must be saved UTF-8 encoded without leading byte order mark (BOM).

*/