1 /* Localization of proper names. -*- coding: utf-8 -*-
2 Copyright (C) 2006, 2008-2023 Free Software Foundation, Inc.
3 Written by Bruno Haible <bruno@clisp.org>, 2006.
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <https://www.gnu.org/licenses/>. */
17
18 /* INTRODUCTION
19
20 What do
21
22 Torbjörn Granlund (coreutils)
23 François Pinard (coreutils)
24 Danilo Šegan (gettext)
25
26 have in common?
27
28 A non-ASCII name. This causes trouble in the --version output. The simple
29 "solution" unfortunately mutilates the name.
30
31 $ du --version | grep Granlund
32 Écrit par Torbjorn Granlund, David MacKenzie, Paul Eggert et Jim Meyering.
33
34 $ ptx --version | grep Pinard
35 Écrit par F. Pinard.
36
37 What is desirable, is to print the full name if the output character set
38 allows it, and the ASCIIfied name only as a fallback.
39
40 $ recode-sr-latin --version
41 ...
42 Written by Danilo Šegan and Bruno Haible.
43
44 $ LC_ALL=C recode-sr-latin --version
45 ...
46 Written by Danilo Segan and Bruno Haible.
47
48 The 'propername' and 'propername-lite' modules do this. Plus, for
49 languages that do not use the Latin alphabet, they allow a translator
50 to write the name using that different writing system. In that case the
51 propername and propername_utf8 output will look like this:
52 <translated name> (<original name in English>)
53 whereas the propername_lite output will just be the translated name
54 if available, otherwise the original name (in UTF-8 if possible and
55 in ASCII if not).
56
57 To use the 'propername' module requires two simple steps:
58
59 1) Add it to the list of gnulib modules to import,
60
61 2) Change the arguments of version_etc(),
62
63 from "Paul Eggert"
64 to proper_name ("Paul Eggert")
65
66 from "Torbjorn Granlund"
67 to proper_name_utf8 ("Torbjorn Granlund", "Torbj\303\266rn Granlund")
68 or proper_name_lite ("Torbjorn Granlund", "Torbj\303\266rn Granlund")
69
70 from "F. Pinard"
71 to proper_name_utf8 ("Franc,ois Pinard", "Fran\303\247ois Pinard")
72 or proper_name_lite ("Franc,ois Pinard", "Fran\303\247ois Pinard")
73
74 In source code, the second argument of proper_name_lite and
75 proper_name_utf8 should use octal escapes, not UTF-8 - e.g.,
76 "Fran\303\247ois Pinard", not "François Pinard". Doing it
77 this way can avoid mishandling non-ASCII characters if the
78 source is recoded to non-UTF-8, or if the compiler does not
79 treat UTF-8 as-is in character string contents.
80
81 (Optionally, here you can also add / * TRANSLATORS: ... * / comments
82 explaining how the name is written or pronounced.)
83
84 Here is an example in context.
85
86 char const *author_names[2] = {
87 / * TRANSLATORS: This is the proper name "Danilo Šegan".
88 In the original Cyrillic it is "Данило Шеган". * /
89 proper_name_utf8 ("Danilo Segan", "Danilo \305\240egan"),
90 proper_name ("Bruno Haible")
91 };
92
93 Differences between proper_name_utf8 and proper_name_lite:
94 * proper_name_lite uses the localization provided by the translator.
95 If there is no localization, it uses the name with Unicode characters
96 only in UTF-8 locales, otherwise it uses the original name in English.
97 * proper_name_utf8 is more elaborate:
98 - It uses the name with Unicode characters also when the locale encoding
99 is not UTF-8 but contains the necessary characters (e.g. ISO-8859-x or
100 GB18030).
101 - If there is a localization, it produces a better result when the
102 translator has given a poor localization.
103 */
104
105 #ifndef _PROPERNAME_H
106 #define _PROPERNAME_H
107
108
109 #ifdef __cplusplus
110 extern "C" {
111 #endif
112
113 /* Return the localization of NAME. NAME is written in ASCII. */
114 extern const char * proper_name (const char *name) /* NOT attribute const */;
115
116 /* Return the localization of a name whose original writing is not ASCII.
117 NAME_UTF8 is the real name, written in UTF-8 with octal or hexadecimal
118 escape sequences. NAME_ASCII is a fallback written only with ASCII
119 characters. */
120 extern const char * proper_name_utf8 (const char *name_ascii,
121 const char *name_utf8);
122
123 /* Return the localization of the name spelled NAME_ASCII in ASCII,
124 and NAME_UTF8 in UTF-8. This function needs less infrastructure
125 than proper_name and proper_name_utf8. */
126 extern const char *proper_name_lite (const char *name_ascii,
127 const char *name_utf8);
128
129 #ifdef __cplusplus
130 }
131 #endif
132
133
134 #endif /* _PROPERNAME_H */