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.