3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 6 June 2010 -->
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 <TT>‘.po’</TT>
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="IDX963"></A>
101 Qt mode: generate a Qt <TT>‘.qm’</TT> file.
107 <H3><A NAME="SEC160" HREF="gettext_toc.html#TOC160">10.1.3 Output file location</A></H3>
111 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
113 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
115 <A NAME="IDX964"></A>
116 <A NAME="IDX965"></A>
117 Write output to specified file.
119 <DT><SAMP>‘--strict’</SAMP>
121 <A NAME="IDX966"></A>
122 Direct the program to work strictly following the Uniforum/Sun
123 implementation. Currently this only affects the naming of the output
124 file. If this option is not given the name of the output file is the
125 same as the domain name. If the strict Uniforum mode is enabled the
126 suffix <TT>‘.mo’</TT> is added to the file name if it is not already
129 We find this behaviour of Sun's implementation rather silly and so by
130 default this mode is <EM>not</EM> selected.
135 If the output <VAR>file</VAR> is <SAMP>‘-’</SAMP>, output is written to standard output.
140 <H3><A NAME="SEC161" HREF="gettext_toc.html#TOC161">10.1.4 Output file location in Java mode</A></H3>
144 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
146 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
148 <A NAME="IDX967"></A>
149 <A NAME="IDX968"></A>
150 Specify the resource name.
152 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
154 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
156 <A NAME="IDX969"></A>
157 <A NAME="IDX970"></A>
158 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
159 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
161 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
163 <A NAME="IDX971"></A>
164 Specify the base directory of classes directory hierarchy.
169 The class name is determined by appending the locale name to the resource name,
170 separated with an underscore. The <SAMP>‘-d’</SAMP> option is mandatory. The class
171 is written under the specified directory.
176 <H3><A NAME="SEC162" HREF="gettext_toc.html#TOC162">10.1.5 Output file location in C# mode</A></H3>
180 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
182 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
184 <A NAME="IDX972"></A>
185 <A NAME="IDX973"></A>
186 Specify the resource name.
188 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
190 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
192 <A NAME="IDX974"></A>
193 <A NAME="IDX975"></A>
194 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
195 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
197 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
199 <A NAME="IDX976"></A>
200 Specify the base directory for locale dependent <TT>‘.dll’</TT> files.
205 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.dll’</TT> file is
206 written in a subdirectory of the specified directory whose name depends on the
212 <H3><A NAME="SEC163" HREF="gettext_toc.html#TOC163">10.1.6 Output file location in Tcl mode</A></H3>
216 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
218 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
220 <A NAME="IDX977"></A>
221 <A NAME="IDX978"></A>
222 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
223 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
225 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
227 <A NAME="IDX979"></A>
228 Specify the base directory of <TT>‘.msg’</TT> message catalogs.
233 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
234 written in the specified directory.
239 <H3><A NAME="SEC164" HREF="gettext_toc.html#TOC164">10.1.7 Input file syntax</A></H3>
243 <DT><SAMP>‘-P’</SAMP>
245 <DT><SAMP>‘--properties-input’</SAMP>
247 <A NAME="IDX980"></A>
248 <A NAME="IDX981"></A>
249 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
250 syntax, not in PO file syntax.
252 <DT><SAMP>‘--stringtable-input’</SAMP>
254 <A NAME="IDX982"></A>
255 Assume the input files are NeXTstep/GNUstep localized resource files in
256 <CODE>.strings</CODE> syntax, not in PO file syntax.
262 <H3><A NAME="SEC165" HREF="gettext_toc.html#TOC165">10.1.8 Input file interpretation</A></H3>
266 <DT><SAMP>‘-c’</SAMP>
268 <DT><SAMP>‘--check’</SAMP>
270 <A NAME="IDX983"></A>
271 <A NAME="IDX984"></A>
272 Perform all the checks implied by <CODE>--check-format</CODE>, <CODE>--check-header</CODE>,
273 <CODE>--check-domain</CODE>.
275 <DT><SAMP>‘--check-format’</SAMP>
277 <A NAME="IDX985"></A>
278 <A NAME="IDX986"></A>
279 Check language dependent format strings.
281 If the string represents a format string used in a
282 <CODE>printf</CODE>-like function both strings should have the same number of
283 <SAMP>‘%’</SAMP> format specifiers, with matching types. If the flag
284 <CODE>c-format</CODE> or <CODE>possible-c-format</CODE> appears in the special
285 comment <KBD>#,</KBD> for this entry a check is performed. For example, the
286 check will diagnose using <SAMP>‘%.*s’</SAMP> against <SAMP>‘%s’</SAMP>, or <SAMP>‘%d’</SAMP>
287 against <SAMP>‘%s’</SAMP>, or <SAMP>‘%d’</SAMP> against <SAMP>‘%x’</SAMP>. It can even handle
288 positional parameters.
290 Normally the <CODE>xgettext</CODE> program automatically decides whether a
291 string is a format string or not. This algorithm is not perfect,
292 though. It might regard a string as a format string though it is not
293 used in a <CODE>printf</CODE>-like function and so <CODE>msgfmt</CODE> might report
294 errors where there are none.
296 To solve this problem the programmer can dictate the decision to the
297 <CODE>xgettext</CODE> program (see section <A HREF="gettext_15.html#SEC249">15.3.1 C Format Strings</A>). The translator should not
298 consider removing the flag from the <KBD>#,</KBD> line. This "fix" would be
299 reversed again as soon as <CODE>msgmerge</CODE> is called the next time.
301 <DT><SAMP>‘--check-header’</SAMP>
303 <A NAME="IDX987"></A>
304 Verify presence and contents of the header entry. See section <A HREF="gettext_6.html#SEC44">6.2 Filling in the Header Entry</A>,
305 for a description of the various fields in the header entry.
307 <DT><SAMP>‘--check-domain’</SAMP>
309 <A NAME="IDX988"></A>
310 Check for conflicts between domain directives and the <CODE>--output-file</CODE>
313 <DT><SAMP>‘-C’</SAMP>
315 <DT><SAMP>‘--check-compatibility’</SAMP>
317 <A NAME="IDX989"></A>
318 <A NAME="IDX990"></A>
319 <A NAME="IDX991"></A>
320 Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error
321 when attempting to use the GNU extensions.
323 <DT><SAMP>‘--check-accelerators[=<VAR>char</VAR>]’</SAMP>
325 <A NAME="IDX992"></A>
326 <A NAME="IDX993"></A>
327 <A NAME="IDX994"></A>
328 <A NAME="IDX995"></A>
329 Check presence of keyboard accelerators for menu items. This is based on
330 the convention used in some GUIs that a keyboard accelerator in a menu
331 item string is designated by an immediately preceding <SAMP>‘&’</SAMP> character.
332 Sometimes a keyboard accelerator is also called "keyboard mnemonic".
333 This check verifies that if the untranslated string has exactly one
334 <SAMP>‘&’</SAMP> character, the translated string has exactly one <SAMP>‘&’</SAMP> as well.
335 If this option is given with a <VAR>char</VAR> argument, this <VAR>char</VAR> should
336 be a non-alphanumeric character and is used as keyboard accelerator mark
337 instead of <SAMP>‘&’</SAMP>.
339 <DT><SAMP>‘-f’</SAMP>
341 <DT><SAMP>‘--use-fuzzy’</SAMP>
343 <A NAME="IDX996"></A>
344 <A NAME="IDX997"></A>
345 <A NAME="IDX998"></A>
346 Use fuzzy entries in output. Note that using this option is usually wrong,
347 because fuzzy messages are exactly those which have not been validated by
354 <H3><A NAME="SEC166" HREF="gettext_toc.html#TOC166">10.1.9 Output details</A></H3>
358 <DT><SAMP>‘-a <VAR>number</VAR>’</SAMP>
360 <DT><SAMP>‘--alignment=<VAR>number</VAR>’</SAMP>
362 <A NAME="IDX999"></A>
363 <A NAME="IDX1000"></A>
364 Align strings to <VAR>number</VAR> bytes (default: 1).
366 <DT><SAMP>‘--no-hash’</SAMP>
368 <A NAME="IDX1001"></A>
369 Don't include a hash table in the binary file. Lookup will be more expensive
370 at run time (binary search instead of hash table lookup).
376 <H3><A NAME="SEC167" HREF="gettext_toc.html#TOC167">10.1.10 Informative output</A></H3>
380 <DT><SAMP>‘-h’</SAMP>
382 <DT><SAMP>‘--help’</SAMP>
384 <A NAME="IDX1002"></A>
385 <A NAME="IDX1003"></A>
386 Display this help and exit.
388 <DT><SAMP>‘-V’</SAMP>
390 <DT><SAMP>‘--version’</SAMP>
392 <A NAME="IDX1004"></A>
393 <A NAME="IDX1005"></A>
394 Output version information and exit.
396 <DT><SAMP>‘--statistics’</SAMP>
398 <A NAME="IDX1006"></A>
399 Print statistics about translations. When the option <CODE>--verbose</CODE> is used
400 in combination with <CODE>--statistics</CODE>, the input file name is printed in
401 front of the statistics line.
403 <DT><SAMP>‘-v’</SAMP>
405 <DT><SAMP>‘--verbose’</SAMP>
407 <A NAME="IDX1007"></A>
408 <A NAME="IDX1008"></A>
409 Increase verbosity level.
415 <H2><A NAME="SEC168" HREF="gettext_toc.html#TOC168">10.2 Invoking the <CODE>msgunfmt</CODE> Program</A></H2>
418 <A NAME="IDX1009"></A>
419 <A NAME="IDX1010"></A>
422 msgunfmt [<VAR>option</VAR>] [<VAR>file</VAR>]...
426 <A NAME="IDX1011"></A>
427 The <CODE>msgunfmt</CODE> program converts a binary message catalog to a
428 Uniforum style .po file.
433 <H3><A NAME="SEC169" HREF="gettext_toc.html#TOC169">10.2.1 Operation mode</A></H3>
437 <DT><SAMP>‘-j’</SAMP>
439 <DT><SAMP>‘--java’</SAMP>
441 <A NAME="IDX1012"></A>
442 <A NAME="IDX1013"></A>
443 <A NAME="IDX1014"></A>
444 Java mode: input is a Java <CODE>ResourceBundle</CODE> class.
446 <DT><SAMP>‘--csharp’</SAMP>
448 <A NAME="IDX1015"></A>
449 <A NAME="IDX1016"></A>
450 C# mode: input is a .NET .dll file containing a subclass of
451 <CODE>GettextResourceSet</CODE>.
453 <DT><SAMP>‘--csharp-resources’</SAMP>
455 <A NAME="IDX1017"></A>
456 <A NAME="IDX1018"></A>
457 C# resources mode: input is a .NET <TT>‘.resources’</TT> file.
459 <DT><SAMP>‘--tcl’</SAMP>
461 <A NAME="IDX1019"></A>
462 <A NAME="IDX1020"></A>
463 Tcl mode: input is a tcl/msgcat <TT>‘.msg’</TT> file.
469 <H3><A NAME="SEC170" HREF="gettext_toc.html#TOC170">10.2.2 Input file location</A></H3>
473 <DT><SAMP>‘<VAR>file</VAR> ...’</SAMP>
480 If no input <VAR>file</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
485 <H3><A NAME="SEC171" HREF="gettext_toc.html#TOC171">10.2.3 Input file location in Java mode</A></H3>
489 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
491 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
493 <A NAME="IDX1021"></A>
494 <A NAME="IDX1022"></A>
495 Specify the resource name.
497 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
499 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
501 <A NAME="IDX1023"></A>
502 <A NAME="IDX1024"></A>
503 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
504 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
509 The class name is determined by appending the locale name to the resource name,
510 separated with an underscore. The class is located using the <CODE>CLASSPATH</CODE>.
515 <H3><A NAME="SEC172" HREF="gettext_toc.html#TOC172">10.2.4 Input file location in C# mode</A></H3>
519 <DT><SAMP>‘-r <VAR>resource</VAR>’</SAMP>
521 <DT><SAMP>‘--resource=<VAR>resource</VAR>’</SAMP>
523 <A NAME="IDX1025"></A>
524 <A NAME="IDX1026"></A>
525 Specify the resource name.
527 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
529 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
531 <A NAME="IDX1027"></A>
532 <A NAME="IDX1028"></A>
533 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
534 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
536 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
538 <A NAME="IDX1029"></A>
539 Specify the base directory for locale dependent <TT>‘.dll’</TT> files.
544 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
545 located in a subdirectory of the specified directory whose name depends on the
551 <H3><A NAME="SEC173" HREF="gettext_toc.html#TOC173">10.2.5 Input file location in Tcl mode</A></H3>
555 <DT><SAMP>‘-l <VAR>locale</VAR>’</SAMP>
557 <DT><SAMP>‘--locale=<VAR>locale</VAR>’</SAMP>
559 <A NAME="IDX1030"></A>
560 <A NAME="IDX1031"></A>
561 Specify the locale name, either a language specification of the form <VAR>ll</VAR>
562 or a combined language and country specification of the form <VAR>ll_CC</VAR>.
564 <DT><SAMP>‘-d <VAR>directory</VAR>’</SAMP>
566 <A NAME="IDX1032"></A>
567 Specify the base directory of <TT>‘.msg’</TT> message catalogs.
572 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
573 located in the specified directory.
578 <H3><A NAME="SEC174" HREF="gettext_toc.html#TOC174">10.2.6 Output file location</A></H3>
582 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
584 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
586 <A NAME="IDX1033"></A>
587 <A NAME="IDX1034"></A>
588 Write output to specified file.
593 The results are written to standard output if no output file is specified
594 or if it is <SAMP>‘-’</SAMP>.
599 <H3><A NAME="SEC175" HREF="gettext_toc.html#TOC175">10.2.7 Output details</A></H3>
603 <DT><SAMP>‘--color’</SAMP>
605 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
607 <A NAME="IDX1035"></A>
608 Specify whether or when to use colors and other text attributes.
609 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
611 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
613 <A NAME="IDX1036"></A>
614 Specify the CSS style rule file to use for <CODE>--color</CODE>.
615 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
617 <DT><SAMP>‘--force-po’</SAMP>
619 <A NAME="IDX1037"></A>
620 Always write an output file even if it contains no message.
622 <DT><SAMP>‘-i’</SAMP>
624 <DT><SAMP>‘--indent’</SAMP>
626 <A NAME="IDX1038"></A>
627 <A NAME="IDX1039"></A>
628 Write the .po file using indented style.
630 <DT><SAMP>‘--strict’</SAMP>
632 <A NAME="IDX1040"></A>
633 Write out a strict Uniforum conforming PO file. Note that this
634 Uniforum format should be avoided because it doesn't support the
637 <DT><SAMP>‘-p’</SAMP>
639 <DT><SAMP>‘--properties-output’</SAMP>
641 <A NAME="IDX1041"></A>
642 <A NAME="IDX1042"></A>
643 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
644 that this file format doesn't support plural forms and silently drops
647 <DT><SAMP>‘--stringtable-output’</SAMP>
649 <A NAME="IDX1043"></A>
650 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
651 Note that this file format doesn't support plural forms.
653 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
655 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
657 <A NAME="IDX1044"></A>
658 <A NAME="IDX1045"></A>
659 Set the output page width. Long strings in the output files will be
660 split across multiple lines in order to ensure that each line's width
661 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
663 <DT><SAMP>‘--no-wrap’</SAMP>
665 <A NAME="IDX1046"></A>
666 Do not break long message lines. Message lines whose width exceeds the
667 output page width will not be split into several lines. Only file reference
668 lines which are wider than the output page width will be split.
670 <DT><SAMP>‘-s’</SAMP>
672 <DT><SAMP>‘--sort-output’</SAMP>
674 <A NAME="IDX1047"></A>
675 <A NAME="IDX1048"></A>
676 <A NAME="IDX1049"></A>
677 Generate sorted output. Note that using this option makes it much harder
678 for the translator to understand each message's context.
684 <H3><A NAME="SEC176" HREF="gettext_toc.html#TOC176">10.2.8 Informative output</A></H3>
688 <DT><SAMP>‘-h’</SAMP>
690 <DT><SAMP>‘--help’</SAMP>
692 <A NAME="IDX1050"></A>
693 <A NAME="IDX1051"></A>
694 Display this help and exit.
696 <DT><SAMP>‘-V’</SAMP>
698 <DT><SAMP>‘--version’</SAMP>
700 <A NAME="IDX1052"></A>
701 <A NAME="IDX1053"></A>
702 Output version information and exit.
704 <DT><SAMP>‘-v’</SAMP>
706 <DT><SAMP>‘--verbose’</SAMP>
708 <A NAME="IDX1054"></A>
709 <A NAME="IDX1055"></A>
710 Increase verbosity level.
716 <H2><A NAME="SEC177" HREF="gettext_toc.html#TOC177">10.3 The Format of GNU MO Files</A></H2>
718 <A NAME="IDX1056"></A>
719 <A NAME="IDX1057"></A>
723 The format of the generated MO files is best described by a picture,
728 <A NAME="IDX1058"></A>
729 The first two words serve the identification of the file. The magic
730 number will always signal GNU MO files. The number is stored in the
731 byte order of the generating machine, so the magic number really is
732 two numbers: <CODE>0x950412de</CODE> and <CODE>0xde120495</CODE>.
736 The second word describes the current revision of the file format,
737 composed of a major and a minor revision number. The revision numbers
738 ensure that the readers of MO files can distinguish new formats from
739 old ones and handle their contents, as far as possible. For now the
740 major revision is 0 or 1, and the minor revision is also 0 or 1. More
741 revisions might be added in the future. A program seeing an unexpected
742 major revision number should stop reading the MO file entirely; whereas
743 an unexpected minor revision number means that the file can be read but
744 will not reveal its full contents, when parsed by a program that
745 supports only smaller minor revision numbers.
750 separate from the magic number, instead of using different magic
751 numbers for different formats, mainly because <TT>‘/etc/magic’</TT> is
756 Follow a number of pointers to later tables in the file, allowing
757 for the extension of the prefix part of MO files without having to
758 recompile programs reading them. This might become useful for later
759 inserting a few flag bits, indication about the charset used, new
760 tables, or other things.
764 Then, at offset <VAR>O</VAR> and offset <VAR>T</VAR> in the picture, two tables
765 of string descriptors can be found. In both tables, each string
766 descriptor uses two 32 bits integers, one for the string length,
767 another for the offset of the string in the MO file, counting in bytes
768 from the start of the file. The first table contains descriptors
769 for the original strings, and is sorted so the original strings
770 are in increasing lexicographical order. The second table contains
771 descriptors for the translated strings, and is parallel to the first
772 table: to find the corresponding translation one has to access the
773 array slot in the second array with the same index.
777 Having the original strings sorted enables the use of simple binary
778 search, for when the MO file does not contain an hashing table, or
779 for when it is not practical to use the hashing table provided in
780 the MO file. This also has another advantage, as the empty string
781 in a PO file GNU <CODE>gettext</CODE> is usually <EM>translated</EM> into
782 some system information attached to that particular MO file, and the
783 empty string necessarily becomes the first in both the original and
784 translated tables, making the system information very easy to find.
788 <A NAME="IDX1059"></A>
789 The size <VAR>S</VAR> of the hash table can be zero. In this case, the
790 hash table itself is not contained in the MO file. Some people might
791 prefer this because a precomputed hashing table takes disk space, and
792 does not win <EM>that</EM> much speed. The hash table contains indices
793 to the sorted array of strings in the MO file. Conflict resolution is
794 done by double hashing. The precise hashing algorithm used is fairly
795 dependent on GNU <CODE>gettext</CODE> code, and is not documented here.
799 As for the strings themselves, they follow the hash file, and each
800 is terminated with a <KBD>NUL</KBD>, and this <KBD>NUL</KBD> is not counted in
801 the length which appears in the string descriptor. The <CODE>msgfmt</CODE>
802 program has an option selecting the alignment for MO file strings.
803 With this option, each string is separately aligned so it starts at
804 an offset which is a multiple of the alignment value. On some RISC
805 machines, a correct alignment will speed things up.
809 <A NAME="IDX1060"></A>
810 Contexts are stored by storing the concatenation of the context, a
811 <KBD>EOT</KBD> byte, and the original string, instead of the original string.
815 <A NAME="IDX1061"></A>
816 Plural forms are stored by letting the plural of the original string
817 follow the singular of the original string, separated through a
818 <KBD>NUL</KBD> byte. The length which appears in the string descriptor
819 includes both. However, only the singular of the original string
820 takes part in the hash table lookup. The plural variants of the
821 translation are all stored consecutively, separated through a
822 <KBD>NUL</KBD> byte. Here also, the length in the string descriptor
823 includes all of them.
827 Nothing prevents a MO file from having embedded <KBD>NUL</KBD>s in strings.
828 However, the program interface currently used already presumes
829 that strings are <KBD>NUL</KBD> terminated, so embedded <KBD>NUL</KBD>s are
830 somewhat useless. But the MO file format is general enough so other
831 interfaces would be later possible, if for example, we ever want to
832 implement wide characters right in MO files, where <KBD>NUL</KBD> bytes may
833 accidentally appear. (No, we don't want to have wide characters in MO
834 files. They would make the file unnecessarily large, and the
835 <SAMP>‘wchar_t’</SAMP> type being platform dependent, MO files would be
836 platform dependent as well.)
840 This particular issue has been strongly debated in the GNU
841 <CODE>gettext</CODE> development forum, and it is expectable that MO file
842 format will evolve or change over time. It is even possible that many
843 formats may later be supported concurrently. But surely, we have to
844 start somewhere, and the MO file format described here is a good start.
845 Nothing is cast in concrete, and the format may later evolve fairly
846 easily, so we should feel comfortable with the current approach.
852 +------------------------------------------+
853 0 | magic number = 0x950412de |
855 4 | file format revision = 0 |
857 8 | number of strings | == N
859 12 | offset of table with original strings | == O
861 16 | offset of table with translation strings | == T
863 20 | size of hashing table | == S
865 24 | offset of hashing table | == H
868 . (possibly more entries later) .
871 O | length & offset 0th string ----------------.
872 O + 8 | length & offset 1st string ------------------.
874 O + ((N-1)*8)| length & offset (N-1)th string | | |
876 T | length & offset 0th translation ---------------.
877 T + 8 | length & offset 1st translation -----------------.
879 T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
881 H | start hash table | | | | |
883 H + S * 4 | end hash table | | | | |
885 | NUL terminated 0th string <----------------' | | |
887 | NUL terminated 1st string <------------------' | |
891 | NUL terminated 0th translation <---------------' |
893 | NUL terminated 1st translation <-----------------'
897 +------------------------------------------+
901 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>.
projects / platform / upstream / gettext.git / blob