3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 28 December 2015 -->
6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
7 <TITLE>GNU gettext utilities - 10 Producing Binary MO Files</TITLE>
10 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_9.html">previous</A>, <A HREF="gettext_11.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
14 <H1><A NAME="SEC156" HREF="gettext_toc.html#TOC156">10 Producing Binary MO Files</A></H1>
18 <H2><A NAME="SEC157" HREF="gettext_toc.html#TOC157">10.1 Invoking the <CODE>msgfmt</CODE> Program</A></H2>
25 msgfmt [<VAR>option</VAR>] <VAR>filename</VAR>.po ...
30 The <CODE>msgfmt</CODE> programs generates a binary message catalog from a textual
31 translation description.
36 <H3><A NAME="SEC158" HREF="gettext_toc.html#TOC158">10.1.1 Input file location</A></H3>
40 <DT><SAMP>‘<VAR>filename</VAR>.po ...’</SAMP>
42 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
44 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
48 Add <VAR>directory</VAR> to the list of directories. Source files are
49 searched relative to this list of directories. The resulting binary
50 file will be written relative to the current directory, though.
55 If an input file is <SAMP>‘-’</SAMP>, standard input is read.
60 <H3><A NAME="SEC159" HREF="gettext_toc.html#TOC159">10.1.2 Operation mode</A></H3>
64 <DT><SAMP>‘-j’</SAMP>
66 <DT><SAMP>‘--java’</SAMP>
71 Java mode: generate a Java <CODE>ResourceBundle</CODE> class.
73 <DT><SAMP>‘--java2’</SAMP>
76 Like --java, and assume Java2 (JDK 1.2 or higher).
78 <DT><SAMP>‘--csharp’</SAMP>
82 C# mode: generate a .NET .dll file containing a subclass of
83 <CODE>GettextResourceSet</CODE>.
85 <DT><SAMP>‘--csharp-resources’</SAMP>
89 C# resources mode: generate a .NET <TT>‘.resources’</TT> file.
91 <DT><SAMP>‘--tcl’</SAMP>
95 Tcl mode: generate a tcl/msgcat <TT>‘.msg’</TT> file.
97 <DT><SAMP>‘--qt’</SAMP>
100 <A NAME="IDX991"></A>
101 Qt mode: generate a Qt <TT>‘.qm’</TT> file.
103 <DT><SAMP>‘--desktop’</SAMP>
105 <A NAME="IDX992"></A>
106 <A NAME="IDX993"></A>
107 Desktop Entry mode: generate a <TT>‘.desktop’</TT> file.
109 <DT><SAMP>‘--xml’</SAMP>
111 <A NAME="IDX994"></A>
112 <A NAME="IDX995"></A>
113 XML mode: generate an XML file.
119 <H3><A NAME="SEC160" HREF="gettext_toc.html#TOC160">10.1.3 Output file location</A></H3>
123 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
125 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
127 <A NAME="IDX996"></A>
128 <A NAME="IDX997"></A>
129 Write output to specified file.
131 <DT><SAMP>‘--strict’</SAMP>
133 <A NAME="IDX998"></A>
134 Direct the program to work strictly following the Uniforum/Sun
135 implementation. Currently this only affects the naming of the output
136 file. If this option is not given the name of the output file is the
137 same as the domain name. If the strict Uniforum mode is enabled the
138 suffix <TT>‘.mo’</TT> is added to the file name if it is not already
141 We find this behaviour of Sun's implementation rather silly and so by
142 default this mode is <EM>not</EM> selected.
147 If the output <VAR>file</VAR> is <SAMP>‘-’</SAMP>, output is written to standard output.
152 <H3><A NAME="SEC161" HREF="gettext_toc.html#TOC161">10.1.4 Output file location in Java mode</A></H3>
156 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
158 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
160 <A NAME="IDX999"></A>
161 <A NAME="IDX1000"></A>
162 Specify the resource name.
164 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
166 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
168 <A NAME="IDX1001"></A>
169 <A NAME="IDX1002"></A>
170 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
171 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
173 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
175 <A NAME="IDX1003"></A>
176 Specify the base directory of classes directory hierarchy.
178 <DT><SAMP>‘--source’</SAMP>
180 <A NAME="IDX1004"></A>
181 Produce a .java source file, instead of a compiled .class file.
186 The class name is determined by appending the locale name to the resource name,
187 separated with an underscore. The <SAMP>‘-d’</SAMP> option is mandatory. The class
188 is written under the specified directory.
193 <H3><A NAME="SEC162" HREF="gettext_toc.html#TOC162">10.1.5 Output file location in C# mode</A></H3>
197 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
199 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
201 <A NAME="IDX1005"></A>
202 <A NAME="IDX1006"></A>
203 Specify the resource name.
205 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
207 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
209 <A NAME="IDX1007"></A>
210 <A NAME="IDX1008"></A>
211 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
212 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
214 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
216 <A NAME="IDX1009"></A>
217 Specify the base directory for locale dependent <TT>‘.dll’</TT> files.
222 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.dll’</TT> file is
223 written in a subdirectory of the specified directory whose name depends on the
229 <H3><A NAME="SEC163" HREF="gettext_toc.html#TOC163">10.1.6 Output file location in Tcl mode</A></H3>
233 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
235 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
237 <A NAME="IDX1010"></A>
238 <A NAME="IDX1011"></A>
239 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
240 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
242 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
244 <A NAME="IDX1012"></A>
245 Specify the base directory of <TT>‘.msg’</TT> message catalogs.
250 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
251 written in the specified directory.
256 <H3><A NAME="SEC164" HREF="gettext_toc.html#TOC164">10.1.7 Desktop Entry mode operations</A></H3>
260 <DT><SAMP>‘--template=<VAR>template</VAR>’</SAMP>
262 <A NAME="IDX1013"></A>
263 Specify a .desktop file used as a template.
265 <DT><SAMP>‘-k[<VAR>keywordspec</VAR>]’</SAMP>
267 <DT><SAMP>‘--keyword[=<VAR>keywordspec</VAR>]’</SAMP>
269 <A NAME="IDX1014"></A>
270 <A NAME="IDX1015"></A>
271 Specify <VAR>keywordspec</VAR> as an additional keyword to be looked for.
272 Without a <VAR>keywordspec</VAR>, the option means to not use default keywords.
274 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
276 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
278 <A NAME="IDX1016"></A>
279 <A NAME="IDX1017"></A>
280 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
281 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
283 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
285 <A NAME="IDX1018"></A>
286 Specify the directory where PO files are read. The directory must
287 contain the <SAMP>‘LINGUAS’</SAMP> file.
292 To generate a <SAMP>‘.desktop’</SAMP> file for a single locale, you can use it
298 msgfmt --desktop --template=<VAR>template</VAR> --locale=<VAR>locale</VAR> \
299 -o <VAR>file</VAR> <VAR>filename</VAR>.po ...
303 msgfmt provides a special "bulk" operation mode to process multiple
304 <TT>‘.po’</TT> files at a time.
309 msgfmt --desktop --template=<VAR>template</VAR> -d <VAR>directory</VAR> -o <VAR>file</VAR>
313 msgfmt first reads the <SAMP>‘LINGUAS’</SAMP> file under <VAR>directory</VAR>, and
314 then processes all <SAMP>‘.po’</SAMP> files listed there. You can also limit
315 the locales to a subset, through the <SAMP>‘LINGUAS’</SAMP> environment
320 For either operation modes, the <SAMP>‘-o’</SAMP> and <SAMP>‘--template’</SAMP>
321 options are mandatory.
326 <H3><A NAME="SEC165" HREF="gettext_toc.html#TOC165">10.1.8 XML mode operations</A></H3>
330 <DT><SAMP>‘--template=<VAR>template</VAR>’</SAMP>
332 <A NAME="IDX1019"></A>
333 Specify an XML file used as a template.
335 <DT><SAMP>‘-L <VAR>name</VAR>’</SAMP>
337 <DT><SAMP>‘--language=<VAR>name</VAR>’</SAMP>
339 <A NAME="IDX1020"></A>
340 <A NAME="IDX1021"></A>
341 <A NAME="IDX1022"></A>
342 Specifies the language of the input files.
344 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
346 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
348 <A NAME="IDX1023"></A>
349 <A NAME="IDX1024"></A>
350 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
351 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
353 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
355 <A NAME="IDX1025"></A>
356 Specify the base directory of <TT>‘.po’</TT> message catalogs.
361 To generate an XML file for a single locale, you can use it as follows.
366 msgfmt --xml --template=<VAR>template</VAR> --locale=<VAR>locale</VAR> \
367 -o <VAR>file</VAR> <VAR>filename</VAR>.po ...
371 msgfmt provides a special "bulk" operation mode to process multiple
372 <TT>‘.po’</TT> files at a time.
377 msgfmt --xml --template=<VAR>template</VAR> -d <VAR>directory</VAR> -o <VAR>file</VAR>
381 msgfmt first reads the <SAMP>‘LINGUAS’</SAMP> file under <VAR>directory</VAR>, and
382 then processes all <SAMP>‘.po’</SAMP> files listed there. You can also limit
383 the locales to a subset, through the <SAMP>‘LINGUAS’</SAMP> environment
388 For either operation modes, the <SAMP>‘-o’</SAMP> and <SAMP>‘--template’</SAMP>
389 options are mandatory.
394 <H3><A NAME="SEC166" HREF="gettext_toc.html#TOC166">10.1.9 Input file syntax</A></H3>
398 <DT><SAMP>‘-P’</SAMP>
400 <DT><SAMP>‘--properties-input’</SAMP>
402 <A NAME="IDX1026"></A>
403 <A NAME="IDX1027"></A>
404 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
405 syntax, not in PO file syntax.
407 <DT><SAMP>‘--stringtable-input’</SAMP>
409 <A NAME="IDX1028"></A>
410 Assume the input files are NeXTstep/GNUstep localized resource files in
411 <CODE>.strings</CODE> syntax, not in PO file syntax.
417 <H3><A NAME="SEC167" HREF="gettext_toc.html#TOC167">10.1.10 Input file interpretation</A></H3>
421 <DT><SAMP>‘-c’</SAMP>
423 <DT><SAMP>‘--check’</SAMP>
425 <A NAME="IDX1029"></A>
426 <A NAME="IDX1030"></A>
427 Perform all the checks implied by <CODE>--check-format</CODE>, <CODE>--check-header</CODE>,
428 <CODE>--check-domain</CODE>.
430 <DT><SAMP>‘--check-format’</SAMP>
432 <A NAME="IDX1031"></A>
433 <A NAME="IDX1032"></A>
434 Check language dependent format strings.
436 If the string represents a format string used in a
437 <CODE>printf</CODE>-like function both strings should have the same number of
438 <SAMP>‘%’</SAMP> format specifiers, with matching types. If the flag
439 <CODE>c-format</CODE> or <CODE>possible-c-format</CODE> appears in the special
440 comment <KBD>#,</KBD> for this entry a check is performed. For example, the
441 check will diagnose using <SAMP>‘%.*s’</SAMP> against <SAMP>‘%s’</SAMP>, or <SAMP>‘%d’</SAMP>
442 against <SAMP>‘%s’</SAMP>, or <SAMP>‘%d’</SAMP> against <SAMP>‘%x’</SAMP>. It can even handle
443 positional parameters.
445 Normally the <CODE>xgettext</CODE> program automatically decides whether a
446 string is a format string or not. This algorithm is not perfect,
447 though. It might regard a string as a format string though it is not
448 used in a <CODE>printf</CODE>-like function and so <CODE>msgfmt</CODE> might report
449 errors where there are none.
451 To solve this problem the programmer can dictate the decision to the
452 <CODE>xgettext</CODE> program (see section <A HREF="gettext_15.html#SEC252">15.3.1 C Format Strings</A>). The translator should not
453 consider removing the flag from the <KBD>#,</KBD> line. This "fix" would be
454 reversed again as soon as <CODE>msgmerge</CODE> is called the next time.
456 <DT><SAMP>‘--check-header’</SAMP>
458 <A NAME="IDX1033"></A>
459 Verify presence and contents of the header entry. See section <A HREF="gettext_6.html#SEC44">6.2 Filling in the Header Entry</A>,
460 for a description of the various fields in the header entry.
462 <DT><SAMP>‘--check-domain’</SAMP>
464 <A NAME="IDX1034"></A>
465 Check for conflicts between domain directives and the <CODE>--output-file</CODE>
468 <DT><SAMP>‘-C’</SAMP>
470 <DT><SAMP>‘--check-compatibility’</SAMP>
472 <A NAME="IDX1035"></A>
473 <A NAME="IDX1036"></A>
474 <A NAME="IDX1037"></A>
475 Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error
476 when attempting to use the GNU extensions.
478 <DT><SAMP>‘--check-accelerators[=<VAR>char</VAR>]’</SAMP>
480 <A NAME="IDX1038"></A>
481 <A NAME="IDX1039"></A>
482 <A NAME="IDX1040"></A>
483 <A NAME="IDX1041"></A>
484 Check presence of keyboard accelerators for menu items. This is based on
485 the convention used in some GUIs that a keyboard accelerator in a menu
486 item string is designated by an immediately preceding <SAMP>‘&’</SAMP> character.
487 Sometimes a keyboard accelerator is also called "keyboard mnemonic".
488 This check verifies that if the untranslated string has exactly one
489 <SAMP>‘&’</SAMP> character, the translated string has exactly one <SAMP>‘&’</SAMP> as well.
490 If this option is given with a <VAR>char</VAR> argument, this <VAR>char</VAR> should
491 be a non-alphanumeric character and is used as keyboard accelerator mark
492 instead of <SAMP>‘&’</SAMP>.
494 <DT><SAMP>‘-f’</SAMP>
496 <DT><SAMP>‘--use-fuzzy’</SAMP>
498 <A NAME="IDX1042"></A>
499 <A NAME="IDX1043"></A>
500 <A NAME="IDX1044"></A>
501 Use fuzzy entries in output. Note that using this option is usually wrong,
502 because fuzzy messages are exactly those which have not been validated by
509 <H3><A NAME="SEC168" HREF="gettext_toc.html#TOC168">10.1.11 Output details</A></H3>
513 <DT><SAMP>‘-a <VAR>number</VAR>’</SAMP>
515 <DT><SAMP>‘--alignment=<VAR>number</VAR>’</SAMP>
517 <A NAME="IDX1045"></A>
518 <A NAME="IDX1046"></A>
519 Align strings to <VAR>number</VAR> bytes (default: 1).
521 <DT><SAMP>‘--endianness=<VAR>byteorder</VAR>’</SAMP>
523 <A NAME="IDX1047"></A>
524 Write out 32-bit numbers in the given byte order. The possible values are
525 <CODE>big</CODE> and <CODE>little</CODE>. The default depends on the platform, namely
526 on the endianness of the CPU.
528 MO files of any endianness can be used on any platform. When a MO file has
529 an endianness other than the platform's one, the 32-bit numbers from the MO
530 file are swapped at runtime. The performance impact is negligible.
532 This option can be useful to produce MO files that are independent of the
535 <DT><SAMP>‘--no-hash’</SAMP>
537 <A NAME="IDX1048"></A>
538 Don't include a hash table in the binary file. Lookup will be more expensive
539 at run time (binary search instead of hash table lookup).
545 <H3><A NAME="SEC169" HREF="gettext_toc.html#TOC169">10.1.12 Informative output</A></H3>
549 <DT><SAMP>‘-h’</SAMP>
551 <DT><SAMP>‘--help’</SAMP>
553 <A NAME="IDX1049"></A>
554 <A NAME="IDX1050"></A>
555 Display this help and exit.
557 <DT><SAMP>‘-V’</SAMP>
559 <DT><SAMP>‘--version’</SAMP>
561 <A NAME="IDX1051"></A>
562 <A NAME="IDX1052"></A>
563 Output version information and exit.
565 <DT><SAMP>‘--statistics’</SAMP>
567 <A NAME="IDX1053"></A>
568 Print statistics about translations. When the option <CODE>--verbose</CODE> is used
569 in combination with <CODE>--statistics</CODE>, the input file name is printed in
570 front of the statistics line.
572 <DT><SAMP>‘-v’</SAMP>
574 <DT><SAMP>‘--verbose’</SAMP>
576 <A NAME="IDX1054"></A>
577 <A NAME="IDX1055"></A>
578 Increase verbosity level.
584 <H2><A NAME="SEC170" HREF="gettext_toc.html#TOC170">10.2 Invoking the <CODE>msgunfmt</CODE> Program</A></H2>
587 <A NAME="IDX1056"></A>
588 <A NAME="IDX1057"></A>
591 msgunfmt [<VAR>option</VAR>] [<VAR>file</VAR>]...
595 <A NAME="IDX1058"></A>
596 The <CODE>msgunfmt</CODE> program converts a binary message catalog to a
597 Uniforum style .po file.
602 <H3><A NAME="SEC171" HREF="gettext_toc.html#TOC171">10.2.1 Operation mode</A></H3>
606 <DT><SAMP>‘-j’</SAMP>
608 <DT><SAMP>‘--java’</SAMP>
610 <A NAME="IDX1059"></A>
611 <A NAME="IDX1060"></A>
612 <A NAME="IDX1061"></A>
613 Java mode: input is a Java <CODE>ResourceBundle</CODE> class.
615 <DT><SAMP>‘--csharp’</SAMP>
617 <A NAME="IDX1062"></A>
618 <A NAME="IDX1063"></A>
619 C# mode: input is a .NET .dll file containing a subclass of
620 <CODE>GettextResourceSet</CODE>.
622 <DT><SAMP>‘--csharp-resources’</SAMP>
624 <A NAME="IDX1064"></A>
625 <A NAME="IDX1065"></A>
626 C# resources mode: input is a .NET <TT>‘.resources’</TT> file.
628 <DT><SAMP>‘--tcl’</SAMP>
630 <A NAME="IDX1066"></A>
631 <A NAME="IDX1067"></A>
632 Tcl mode: input is a tcl/msgcat <TT>‘.msg’</TT> file.
638 <H3><A NAME="SEC172" HREF="gettext_toc.html#TOC172">10.2.2 Input file location</A></H3>
642 <DT><SAMP>‘<VAR>file</VAR> ...’</SAMP>
649 If no input <VAR>file</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
654 <H3><A NAME="SEC173" HREF="gettext_toc.html#TOC173">10.2.3 Input file location in Java mode</A></H3>
658 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
660 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
662 <A NAME="IDX1068"></A>
663 <A NAME="IDX1069"></A>
664 Specify the resource name.
666 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
668 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
670 <A NAME="IDX1070"></A>
671 <A NAME="IDX1071"></A>
672 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
673 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
678 The class name is determined by appending the locale name to the resource name,
679 separated with an underscore. The class is located using the <CODE>CLASSPATH</CODE>.
684 <H3><A NAME="SEC174" HREF="gettext_toc.html#TOC174">10.2.4 Input file location in C# mode</A></H3>
688 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
690 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
692 <A NAME="IDX1072"></A>
693 <A NAME="IDX1073"></A>
694 Specify the resource name.
696 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
698 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
700 <A NAME="IDX1074"></A>
701 <A NAME="IDX1075"></A>
702 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
703 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
705 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
707 <A NAME="IDX1076"></A>
708 Specify the base directory for locale dependent <TT>‘.dll’</TT> files.
713 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
714 located in a subdirectory of the specified directory whose name depends on the
720 <H3><A NAME="SEC175" HREF="gettext_toc.html#TOC175">10.2.5 Input file location in Tcl mode</A></H3>
724 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
726 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
728 <A NAME="IDX1077"></A>
729 <A NAME="IDX1078"></A>
730 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
731 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
733 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
735 <A NAME="IDX1079"></A>
736 Specify the base directory of <TT>‘.msg’</TT> message catalogs.
741 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
742 located in the specified directory.
747 <H3><A NAME="SEC176" HREF="gettext_toc.html#TOC176">10.2.6 Output file location</A></H3>
751 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
753 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
755 <A NAME="IDX1080"></A>
756 <A NAME="IDX1081"></A>
757 Write output to specified file.
762 The results are written to standard output if no output file is specified
763 or if it is <SAMP>‘-’</SAMP>.
768 <H3><A NAME="SEC177" HREF="gettext_toc.html#TOC177">10.2.7 Output details</A></H3>
772 <DT><SAMP>‘--color’</SAMP>
774 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
776 <A NAME="IDX1082"></A>
777 Specify whether or when to use colors and other text attributes.
778 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
780 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
782 <A NAME="IDX1083"></A>
783 Specify the CSS style rule file to use for <CODE>--color</CODE>.
784 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
786 <DT><SAMP>‘--force-po’</SAMP>
788 <A NAME="IDX1084"></A>
789 Always write an output file even if it contains no message.
791 <DT><SAMP>‘-i’</SAMP>
793 <DT><SAMP>‘--indent’</SAMP>
795 <A NAME="IDX1085"></A>
796 <A NAME="IDX1086"></A>
797 Write the .po file using indented style.
799 <DT><SAMP>‘--strict’</SAMP>
801 <A NAME="IDX1087"></A>
802 Write out a strict Uniforum conforming PO file. Note that this
803 Uniforum format should be avoided because it doesn't support the
806 <DT><SAMP>‘-p’</SAMP>
808 <DT><SAMP>‘--properties-output’</SAMP>
810 <A NAME="IDX1088"></A>
811 <A NAME="IDX1089"></A>
812 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
813 that this file format doesn't support plural forms and silently drops
816 <DT><SAMP>‘--stringtable-output’</SAMP>
818 <A NAME="IDX1090"></A>
819 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
820 Note that this file format doesn't support plural forms.
822 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
824 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
826 <A NAME="IDX1091"></A>
827 <A NAME="IDX1092"></A>
828 Set the output page width. Long strings in the output files will be
829 split across multiple lines in order to ensure that each line's width
830 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
832 <DT><SAMP>‘--no-wrap’</SAMP>
834 <A NAME="IDX1093"></A>
835 Do not break long message lines. Message lines whose width exceeds the
836 output page width will not be split into several lines. Only file reference
837 lines which are wider than the output page width will be split.
839 <DT><SAMP>‘-s’</SAMP>
841 <DT><SAMP>‘--sort-output’</SAMP>
843 <A NAME="IDX1094"></A>
844 <A NAME="IDX1095"></A>
845 <A NAME="IDX1096"></A>
846 Generate sorted output. Note that using this option makes it much harder
847 for the translator to understand each message's context.
853 <H3><A NAME="SEC178" HREF="gettext_toc.html#TOC178">10.2.8 Informative output</A></H3>
857 <DT><SAMP>‘-h’</SAMP>
859 <DT><SAMP>‘--help’</SAMP>
861 <A NAME="IDX1097"></A>
862 <A NAME="IDX1098"></A>
863 Display this help and exit.
865 <DT><SAMP>‘-V’</SAMP>
867 <DT><SAMP>‘--version’</SAMP>
869 <A NAME="IDX1099"></A>
870 <A NAME="IDX1100"></A>
871 Output version information and exit.
873 <DT><SAMP>‘-v’</SAMP>
875 <DT><SAMP>‘--verbose’</SAMP>
877 <A NAME="IDX1101"></A>
878 <A NAME="IDX1102"></A>
879 Increase verbosity level.
885 <H2><A NAME="SEC179" HREF="gettext_toc.html#TOC179">10.3 The Format of GNU MO Files</A></H2>
887 <A NAME="IDX1103"></A>
888 <A NAME="IDX1104"></A>
892 The format of the generated MO files is best described by a picture,
897 <A NAME="IDX1105"></A>
898 The first two words serve the identification of the file. The magic
899 number will always signal GNU MO files. The number is stored in the
900 byte order of the generating machine, so the magic number really is
901 two numbers: <CODE>0x950412de</CODE> and <CODE>0xde120495</CODE>.
905 The second word describes the current revision of the file format,
906 composed of a major and a minor revision number. The revision numbers
907 ensure that the readers of MO files can distinguish new formats from
908 old ones and handle their contents, as far as possible. For now the
909 major revision is 0 or 1, and the minor revision is also 0 or 1. More
910 revisions might be added in the future. A program seeing an unexpected
911 major revision number should stop reading the MO file entirely; whereas
912 an unexpected minor revision number means that the file can be read but
913 will not reveal its full contents, when parsed by a program that
914 supports only smaller minor revision numbers.
919 separate from the magic number, instead of using different magic
920 numbers for different formats, mainly because <TT>‘/etc/magic’</TT> is
925 Follow a number of pointers to later tables in the file, allowing
926 for the extension of the prefix part of MO files without having to
927 recompile programs reading them. This might become useful for later
928 inserting a few flag bits, indication about the charset used, new
929 tables, or other things.
933 Then, at offset <VAR>O</VAR> and offset <VAR>T</VAR> in the picture, two tables
934 of string descriptors can be found. In both tables, each string
935 descriptor uses two 32 bits integers, one for the string length,
936 another for the offset of the string in the MO file, counting in bytes
937 from the start of the file. The first table contains descriptors
938 for the original strings, and is sorted so the original strings
939 are in increasing lexicographical order. The second table contains
940 descriptors for the translated strings, and is parallel to the first
941 table: to find the corresponding translation one has to access the
942 array slot in the second array with the same index.
946 Having the original strings sorted enables the use of simple binary
947 search, for when the MO file does not contain an hashing table, or
948 for when it is not practical to use the hashing table provided in
949 the MO file. This also has another advantage, as the empty string
950 in a PO file GNU <CODE>gettext</CODE> is usually <EM>translated</EM> into
951 some system information attached to that particular MO file, and the
952 empty string necessarily becomes the first in both the original and
953 translated tables, making the system information very easy to find.
957 <A NAME="IDX1106"></A>
958 The size <VAR>S</VAR> of the hash table can be zero. In this case, the
959 hash table itself is not contained in the MO file. Some people might
960 prefer this because a precomputed hashing table takes disk space, and
961 does not win <EM>that</EM> much speed. The hash table contains indices
962 to the sorted array of strings in the MO file. Conflict resolution is
963 done by double hashing. The precise hashing algorithm used is fairly
964 dependent on GNU <CODE>gettext</CODE> code, and is not documented here.
968 As for the strings themselves, they follow the hash file, and each
969 is terminated with a <KBD>NUL</KBD>, and this <KBD>NUL</KBD> is not counted in
970 the length which appears in the string descriptor. The <CODE>msgfmt</CODE>
971 program has an option selecting the alignment for MO file strings.
972 With this option, each string is separately aligned so it starts at
973 an offset which is a multiple of the alignment value. On some RISC
974 machines, a correct alignment will speed things up.
978 <A NAME="IDX1107"></A>
979 Contexts are stored by storing the concatenation of the context, a
980 <KBD>EOT</KBD> byte, and the original string, instead of the original string.
984 <A NAME="IDX1108"></A>
985 Plural forms are stored by letting the plural of the original string
986 follow the singular of the original string, separated through a
987 <KBD>NUL</KBD> byte. The length which appears in the string descriptor
988 includes both. However, only the singular of the original string
989 takes part in the hash table lookup. The plural variants of the
990 translation are all stored consecutively, separated through a
991 <KBD>NUL</KBD> byte. Here also, the length in the string descriptor
992 includes all of them.
996 Nothing prevents a MO file from having embedded <KBD>NUL</KBD>s in strings.
997 However, the program interface currently used already presumes
998 that strings are <KBD>NUL</KBD> terminated, so embedded <KBD>NUL</KBD>s are
999 somewhat useless. But the MO file format is general enough so other
1000 interfaces would be later possible, if for example, we ever want to
1001 implement wide characters right in MO files, where <KBD>NUL</KBD> bytes may
1002 accidentally appear. (No, we don't want to have wide characters in MO
1003 files. They would make the file unnecessarily large, and the
1004 <SAMP>‘wchar_t’</SAMP> type being platform dependent, MO files would be
1005 platform dependent as well.)
1009 This particular issue has been strongly debated in the GNU
1010 <CODE>gettext</CODE> development forum, and it is expectable that MO file
1011 format will evolve or change over time. It is even possible that many
1012 formats may later be supported concurrently. But surely, we have to
1013 start somewhere, and the MO file format described here is a good start.
1014 Nothing is cast in concrete, and the format may later evolve fairly
1015 easily, so we should feel comfortable with the current approach.
1021 +------------------------------------------+
1022 0 | magic number = 0x950412de |
1024 4 | file format revision = 0 |
1026 8 | number of strings | == N
1028 12 | offset of table with original strings | == O
1030 16 | offset of table with translation strings | == T
1032 20 | size of hashing table | == S
1034 24 | offset of hashing table | == H
1037 . (possibly more entries later) .
1040 O | length & offset 0th string ----------------.
1041 O + 8 | length & offset 1st string ------------------.
1043 O + ((N-1)*8)| length & offset (N-1)th string | | |
1045 T | length & offset 0th translation ---------------.
1046 T + 8 | length & offset 1st translation -----------------.
1048 T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
1050 H | start hash table | | | | |
1052 H + S * 4 | end hash table | | | | |
1054 | NUL terminated 0th string <----------------' | | |
1056 | NUL terminated 1st string <------------------' | |
1060 | NUL terminated 0th translation <---------------' |
1062 | NUL terminated 1st translation <-----------------'
1066 +------------------------------------------+
1070 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_9.html">previous</A>, <A HREF="gettext_11.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.