1 '\" te
2 .\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH MSGFMT 1 "Sep 17, 2001"
7 .SH NAME
8 msgfmt \- create a message object from a message file
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBmsgfmt\fR [\fB-D\fR \fIdir\fR | \fB-\(midirectory\fR=\fIdir\fR]
13 [\fB-f\fR | \fB-\(miuse-fuzzy\fR] [\fB-g\fR]
14 [\fB-o\fR \fIoutput-file\fR | \fB-\(mioutput-file\fR=\fIoutput-file\fR]
15 [\fB-s\fR] [\fB-\(mistrict\fR] [\fB-v\fR] [\fB-\(miverbose\fR] \fIfilename\fR.po...
16 .fi
17
18 .SH DESCRIPTION
19 .LP
20 The \fBmsgfmt\fR utility creates message object files from portable object
21 files (\fIfilename\fR\fB\&.po\fR), without changing the portable object files.
22 .sp
23 .LP
24 The \fB\&.po\fR file contains messages displayed to users by system commands or
25 by application programs. \fB\&.po\fR files can be edited. The messages in these
26 files can be rewritten in any language supported by the system.
27 .sp
28 .LP
29 The \fBxgettext\fR(1) command can be used to create \fB\&.po\fR files from
30 script or programs.
31 .sp
32 .LP
33 \fBmsgfmt\fR interprets data as characters according to the current setting of
34 the \fBLC_CTYPE\fR locale category or according to the codeset specified in the
35 \fB\&.po\fR file.
36 .SH OPTIONS
37 .LP
38 The following options are supported:
39 .sp
40 .ne 2
41 .na
42 \fB\fB-D\fR \fIdir\fR\fR
43 .ad
44 .br
45 .na
46 \fB\fB-\(midirectory=\fR\fIdir\fR\fR
47 .ad
48 .RS 27n
49 Adds \fIdir\fR to the list for input files search.
50 .RE
51
52 .sp
53 .ne 2
54 .na
55 \fB\fB-f\fR\fR
56 .ad
57 .br
58 .na
59 \fB\fB-\(miuse-fuzzy\fR\fR
60 .ad
61 .RS 27n
62 Uses fuzzy entries in output. If this option is not specified, fuzzy entries
63 are not included into the output. These options are ignored if Solaris message
64 catalogs are processed.
65 .RE
66
67 .sp
68 .ne 2
69 .na
70 \fB\fB-g\fR\fR
71 .ad
72 .RS 27n
73 Directs the utility to generate the GNU-compatible message catalog file. This
74 option cannot be specified with the \fB-s\fR option.
75 .RE
76
77 .sp
78 .ne 2
79 .na
80 \fB\fB-o\fR \fIoutput-file\fR\fR
81 .ad
82 .br
83 .na
84 \fB\fB-\(mioutput=\fR\fIoutput-file\fR\fR
85 .ad
86 .RS 27n
87 Specifies the output file name as \fIoutput-file\fR. All domain directives and
88 duplicate msgids in the .\fBpo\fR file are ignored.
89 .RE
90
91 .sp
92 .ne 2
93 .na
94 \fB\fB-s\fR\fR
95 .ad
96 .RS 27n
97 Directs the utility to generate the Solaris message catalog file. This option
98 cannot be specified with the \fB-g\fR option.
99 .RE
100
101 .sp
102 .ne 2
103 .na
104 \fB\fB-\(mistrict\fR\fR
105 .ad
106 .RS 27n
107 Directs the utility to append the suffix \fB\&.mo\fR to the generating message
108 object file name if it doesn't have this suffix. This option is ignored if
109 Solaris message catalogs are processed.
110 .RE
111
112 .sp
113 .ne 2
114 .na
115 \fB\fB-v\fR\fR
116 .ad
117 .br
118 .na
119 \fB\fB-\(miverbose\fR\fR
120 .ad
121 .RS 27n
122 Verbose. Lists duplicate message identifiers if Solaris message catalog files
123 are processed. Message strings are not redefined.
124 .sp
125 If GNU-compatible message files are processed, this option detects and
126 diagnoses input file anomalies which might represent translation errors. The
127 msgid and msgstr strings are studied and compared. It is considered abnormal if
128 one string starts or ends with a newline while the other does not. Also, if the
129 string represents a format string used in a printf-like function, both strings
130 should have the same number of % format specifiers, with matching types. If the
131 flag \fBc-format\fR appears in the special comment '\fB#\fR' for this entry, a
132 check is performed.
133 .RE
134
135 .SH USAGE
136 .LP
137 The format of portable object files (\fB\&.po\fR files) is defined as follows.
138 Each \fB\&.po\fR file contains one or more lines, with each line containing
139 either a comment or a statement. Comments start the line with a pound sign
140 (\fB#\fR) and end with the newline character. All comments (except special
141 comments described later) and empty lines are ignored. The format of a
142 statement is:
143 .sp
144 .in +2
145 .nf
146 \fIdirective\fR \fIvalue\fR
147 .fi
148 .in -2
149 .sp
150
151 .sp
152 .LP
153 Each \fIdirective\fR starts at the beginning of the line and is separated from
154 \fIvalue\fR by white space (such as one or more space or tab characters).
155 \fIvalue\fR consists of one or more quoted strings separated by white space.
156 Use any of the following types of directives for the Solaris message file:
157 .sp
158 .in +2
159 .nf
160 domain \fIdomainname\fR
161 msgid \fImessage_identifier\fR
162 msgstr \fImessage_string\fR
163 .fi
164 .in -2
165 .sp
166
167 .sp
168 .LP
169 For a GNU-compatible message file, use any of the following types of
170 directives:
171 .sp
172 .in +2
173 .nf
174 domain \fIdomainname\fR
175 msgid \fImessage_identifier\fR
176 msgid_plural \fIuntranslated_string_plural\fR
177 msgstr \fImessage_string\fR
178 msgstr[\fIn\fR] \fImessage_string\fR
179 .fi
180 .in -2
181 .sp
182
183 .sp
184 .LP
185 The behavior of the \fBdomain\fR directive is affected by the options used. See
186 OPTIONS for the behavior when the \fB-o\fR or \fB-\(mioutput-file\fR options
187 are specified. If the \fB-o\fR or \fB-\(mioutput-file\fR options are not
188 specified, the behavior of the \fBdomain\fR directive is as follows:
189 .RS +4
190 .TP
191 .ie t \(bu
192 .el o
193 All msgids from the beginning of each \fB\&.po\fR file to the first
194 \fBdomain\fR directive are put into a default message object file. The default
195 message object file is named \fBmessages.mo\fR, if the Solaris message catalog
196 file format is used to generate the message object file or if the
197 \fB-\(mistrict\fR option is specified. Otherwise, the default message object
198 file is named \fBmessages\fR.
199 .RE
200 .RS +4
201 .TP
202 .ie t \(bu
203 .el o
204 When \fBmsgfmt\fR encounters a \fBdomain\fR \fIdomainname\fR directive in the
205 \fB\&.po\fR file, all following msgids until the next \fBdomain\fR directive
206 are put into the message object file, named \fBdomainname.mo\fR, if the Solaris
207 message catalog file format is used to generate the message object file or if
208 the \fB-\(mistrict\fR option is specified. Otherwise, the msgids are put into
209 the message object file named \fBdomainname\fR.
210 .RE
211 .RS +4
212 .TP
213 .ie t \(bu
214 .el o
215 Duplicate msgids are defined in the scope of each domain. That is, a msgid is
216 considered a duplicate only if the identical msgid exists in the same domain.
217 .RE
218 .RS +4
219 .TP
220 .ie t \(bu
221 .el o
222 All duplicate msgids are ignored.
223 .RE
224 .sp
225 .LP
226 The \fBmsgid\fR directive specifies the value of a message identifier
227 associated with the directive that follows it. The \fBmsgid_plural\fR directive
228 specifies the plural form message specified to the plural message handling
229 functions \fBngettext()\fR, \fBdngettext()\fR, or \fBdcngettext()\fR. The
230 \fImessage_identifier\fR string identifies a target string to be used at
231 retrieval time. Each statement containing a \fBmsgid\fR directive must be
232 followed by a statement containing a \fBmsgstr\fR directive or
233 \fBmsgstr\fR[\fIn\fR] directives.
234 .sp
235 .LP
236 The \fBmsgstr\fR directive specifies the target string associated with the
237 \fImessage_identifier\fR string declared in the immediately preceding
238 \fBmsgid\fR directive.
239 .sp
240 .LP
241 The directive \fBmsgstr\fR[\fIn\fR] (where \fIn\fR = 0, 1, 2, ...) specifies
242 the target string to be used with plural form handling functions
243 \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR.
244 .sp
245 .LP
246 Message strings can contain the escape sequences \fB\\n\fR for newline,
247 \fB\\t\fR for tab, \fB\\v\fR for vertical tab, \fB\\b\fR for backspace,
248 \fB\\r\fR for carriage return, \fB\\f\fR for formfeed, \fB\\\fR for backslash,
249 \fB\\"\fR for double quote, \fB\\a\fR for alarm, \fB\\ddd\fR for octal bit
250 pattern, and \fB\\xDD\fR for hexadecimal bit pattern.
251 .sp
252 .LP
253 Comments for a GNU-compatible message file should be in one of the following
254 formats (the \fBmsgfmt\fR utility will ignore these comments when processing
255 Solaris message files):
256 .sp
257 .in +2
258 .nf
259 # \fItranslator-comments\fR
260 #. \fIautomatic-comments\fR
261 #: \fIreference\fR..
262 #, \fIflag\fR
263 .fi
264 .in -2
265 .sp
266
267 .sp
268 .LP
269 The '\fB#:\fR' comments indicate the location of the msgid string in the source
270 files in \fIfilename\fR:\fIline\fR format. The '\fB#\fR', '\fB#.\fR',
271 and '\fB#:\fR' comments are informative only and are silently ignored by the
272 \fBmsgfmt\fR utility. The '\fB#,\fR' comments require one or more flags
273 separated by the comma character. The following \fIflag\fRs can be specified:
274 .sp
275 .ne 2
276 .na
277 \fB\fBfuzzy\fR\fR
278 .ad
279 .RS 15n
280 This flag can be inserted by the translator. It shows that the \fBmsgstr\fR
281 string might not be a correct translation (anymore). Only the translator can
282 judge if the translation requires further modification or is acceptable as is.
283 Once satisfied with the translation, the translator removes this \fBfuzzy\fR
284 flag. If this flag is specified, the \fBmsgfmt\fR utility will not generate the
285 entry for the immediately following msgid in the output message catalog.
286 .RE
287
288 .sp
289 .ne 2
290 .na
291 \fB\fBc-format\fR\fR
292 .ad
293 .br
294 .na
295 \fB\fBno-c-format\fR\fR
296 .ad
297 .RS 15n
298 The \fBc-format\fR flag indicates that the \fBmsgid\fR string is used as a
299 format string by printf-like functions. In case the \fBc-format\fR flag is
300 given for a string, the \fBmsgfmt\fR utility does some more tests to check the
301 validity of the translation.
302 .RE
303
304 .sp
305 .LP
306 In the GNU-compatible message file, the \fBmsgid\fR entry with empty string
307 ("") is called the header entry and treated specially. If the message string
308 for the header entry contains \fBnplurals\fR=\fIvalue\fR, the value indicates
309 the number of plural forms. For example, if \fBnplurals\fR=4, there are four
310 plural forms. If \fBnplurals\fR is defined, the same line should contain
311 \fBplural=\fR\fIexpression\fR, separated by a semicolon character. The
312 \fIexpression\fR is a C language expression to determine which version of
313 \fBmsgstr\fR[\fIn\fR] is to be used based on the value of \fIn\fR, the last
314 argument of \fBngettext()\fR, \fBdngettext()\fR, or \fBdcngettext()\fR. For
315 example,
316 .sp
317 .in +2
318 .nf
319 nplurals=2; plural= n == 1 ? 0 : 1
320 .fi
321 .in -2
322 .sp
323
324 .sp
325 .LP
326 indicates that there are two plural forms in the language. msgstr[0] is used if
327 n == 1, otherwise msgstr[1] is used. For another example:
328 .sp
329 .in +2
330 .nf
331 nplurals=3; plural= n == 1 ? 0 : n == 2 ? 1 : 2
332 .fi
333 .in -2
334 .sp
335
336 .sp
337 .LP
338 indicates that there are three plural forms in the language. msgstr[0] is used
339 if n == 1, msgstr[1] is used if n == 2, otherwise msgstr[2] is used.
340 .sp
341 .LP
342 If the header entry contains a \fBcharset\fR=\fIcodeset\fR string, the
343 \fIcodeset\fR is used to indicate the codeset to be used to encode the message
344 strings. If the output string's codeset is different from the message string's
345 codeset, codeset conversion from the message string's codeset to the output
346 string's codeset will be performed upon the call of \fBgettext()\fR,
347 \fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR, \fBdngettext()\fR, and
348 \fBdcngettext()\fR for the GNU-compatible message catalogs. The output string's
349 codeset is determined by the current locale's codeset (the return value of
350 \fBnl_langinfo(CODESET\fR)) by default, and can be changed by the call of
351 \fBbind_textdomain_codeset()\fR.
352 .SS "Message catalog file format"
353 .LP
354 The \fBmsgfmt\fR utility can generate the message object both in Solaris
355 message catalog file format and in GNU-compatible message catalog file format.
356 If the \fB-s\fR option is specified and the input file is a Solaris \fB\&.po\fR
357 file, the \fBmsgfmt\fR utility generates the message object in Solaris message
358 catalog file format. If the \fB-g\fR option is specified and the input file is
359 a GNU \fB\&.po\fR file, the \fBmsgfmt\fR utility generates the message object
360 in GNU-compatible message catalog file format. If neither the \fB-s\fR nor
361 \fB-g\fR option is specified, the \fBmsgfmt\fR utility determines the message
362 catalog file format as follows:
363 .RS +4
364 .TP
365 .ie t \(bu
366 .el o
367 If the \fB\&.po\fR file contains a valid GNU header entry (having an empty
368 string for \fBmsgid\fR), the \fBmsgfmt\fR utility uses the GNU-compatible
369 message catalog file format.
370 .RE
371 .RS +4
372 .TP
373 .ie t \(bu
374 .el o
375 Otherwise, the \fBmsgfmt\fR utility uses the Solaris message catalog file
376 format.
377 .RE
378 .sp
379 .LP
380 If the \fBmsgfmt\fR utility determined that the Solaris message catalog file
381 format is used, as above, but found the \fB\&.po\fR file contains directives
382 that are specific to the GNU-compatible message catalog file format, such as
383 \fBmsgid_plural\fR and \fBmsgstr\fR[\fIn\fR], the \fBmsgfmt\fR utility handles
384 those directives as invalid specifications.
385 .SH EXAMPLES
386 .LP
387 \fBExample 1 \fRCreating message objects from message files
388 .sp
389 .LP
390 In this example, \fBmodule1.po\fR and \fBmodule2.po\fR are portable message
391 objects files.
392
393 .sp
394 .in +2
395 .nf
396 example% \fBcat module1.po\fR
397 # default domain "messages.mo"
398 msgid "msg 1"
399 msgstr "msg 1 translation"
400 #
401 domain "help_domain"
402 msgid "help 2"
403 msgstr "help 2 translation"
404 #
405 domain "error_domain"
406 msgid "error 3"
407 msgstr "error 3 translation"
408 example% \fBcat module2.po\fR
409 # default domain "messages.mo"
410 msgid "mesg 4"
411 msgstr "mesg 4 translation"
412 #
413 domain "error_domain"
414 msgid "error 5"
415 msgstr "error 5 translation"
416 #
417 domain "window_domain"
418 msgid "window 6"
419 msgstr "window 6 translation"
420 .fi
421 .in -2
422 .sp
423
424 .sp
425 .LP
426 The following command will produce the output files \fBmessages.mo\fR,
427 \fBhelp_domain.mo\fR, and \fBerror_domain.mo\fR in Solaris message catalog file
428 format:
429
430 .sp
431 .in +2
432 .nf
433 example% \fBmsgfmt module1.po\fR
434 .fi
435 .in -2
436 .sp
437
438 .sp
439 .LP
440 The following command will produce the output files \fBmessages.mo\fR,
441 \fBhelp_domain.mo\fR, \fBerror_domain.mo\fR, and \fBwindow_domain.mo\fR in
442 Solaris message catalog file format:
443
444 .sp
445 .in +2
446 .nf
447 example% \fBmsgfmt module1.po module2.po\fR
448 .fi
449 .in -2
450 .sp
451
452 .sp
453 .LP
454 The following command will produce the output file \fBhello.mo\fR in Solaris
455 message catalog file format:
456
457 .sp
458 .in +2
459 .nf
460 example% \fBmsgfmt -o hello.mo module1.po module2.po\fR
461 .fi
462 .in -2
463 .sp
464
465 .SH ENVIRONMENT VARIABLES
466 .LP
467 See \fBenviron\fR(5) for descriptions of the following environmental variables
468 that affect the execution of \fBmsgfmt\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR,
469 and \fBNLSPATH\fR.
470 .SH ATTRIBUTES
471 .LP
472 See \fBattributes\fR(5) for descriptions of the following attributes:
473 .sp
474
475 .sp
476 .TS
477 box;
478 c | c
479 l | l .
480 ATTRIBUTE TYPE ATTRIBUTE VALUE
481 _
482 CSI Enabled
483 .TE
484
485 .SH SEE ALSO
486 .LP
487 \fBxgettext\fR(1), \fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
488 \fBenviron\fR(5)
489 .SH NOTES
490 .LP
491 Installing message catalogs under the C locale is pointless, since they are
492 ignored for the sake of efficiency.