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