| blob | c747abc6f398fad74e8af566da2bcac0ad1f4c01 |
1 <HTML>
2 <HEAD>
3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 6 June 2010 -->
8 </HEAD>
9 <BODY>
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>.
11 <P><HR><P>
18 <H2><A NAME="SEC157" HREF="gettext_toc.html#TOC157">10.1 Invoking the <CODE>msgfmt</CODE> Program</A></H2>
20 <P>
24 <PRE>
26 </PRE>
28 <P>
31 translation description.
33 </P>
41 <DD>
43 <DD>
45 <DD>
50 file will be written relative to the current directory, though.
52 </DL>
54 <P>
57 </P>
65 <DD>
67 <DD>
74 <DD>
76 Like --java, and assume Java2 (JDK 1.2 or higher).
79 <DD>
82 C# mode: generate a .NET .dll file containing a subclass of
86 <DD>
92 <DD>
98 <DD>
103 </DL>
112 <DD>
114 <DD>
117 Write output to specified file.
120 <DD>
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
127 present.
129 We find this behaviour of Sun's implementation rather silly and so by
132 </DL>
134 <P>
135 If the output <VAR>file</VAR> is <SAMP>‘-’</SAMP>, output is written to standard output.
137 </P>
140 <H3><A NAME="SEC161" HREF="gettext_toc.html#TOC161">10.1.4 Output file location in Java mode</A></H3>
145 <DD>
147 <DD>
150 Specify the resource name.
153 <DD>
155 <DD>
162 <DD>
164 Specify the base directory of classes directory hierarchy.
166 </DL>
168 <P>
169 The class name is determined by appending the locale name to the resource name,
171 is written under the specified directory.
173 </P>
176 <H3><A NAME="SEC162" HREF="gettext_toc.html#TOC162">10.1.5 Output file location in C# mode</A></H3>
181 <DD>
183 <DD>
186 Specify the resource name.
189 <DD>
191 <DD>
198 <DD>
202 </DL>
204 <P>
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
207 locale.
209 </P>
212 <H3><A NAME="SEC163" HREF="gettext_toc.html#TOC163">10.1.6 Output file location in Tcl mode</A></H3>
217 <DD>
219 <DD>
226 <DD>
230 </DL>
232 <P>
233 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
234 written in the specified directory.
236 </P>
244 <DD>
246 <DD>
250 syntax, not in PO file syntax.
253 <DD>
255 Assume the input files are NeXTstep/GNUstep localized resource files in
258 </DL>
267 <DD>
269 <DD>
276 <DD>
279 Check language dependent format strings.
281 If the string represents a format string used in a
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.
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
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
302 <DD>
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.
308 <DD>
311 option
314 <DD>
316 <DD>
320 Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error
321 when attempting to use the GNU extensions.
324 <DD>
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.
336 be a non-alphanumeric character and is used as keyboard accelerator mark
340 <DD>
342 <DD>
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
348 a human translator.
350 </DL>
359 <DD>
361 <DD>
367 <DD>
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).
372 </DL>
381 <DD>
383 <DD>
386 Display this help and exit.
389 <DD>
391 <DD>
394 Output version information and exit.
397 <DD>
401 front of the statistics line.
404 <DD>
406 <DD>
409 Increase verbosity level.
411 </DL>
415 <H2><A NAME="SEC168" HREF="gettext_toc.html#TOC168">10.2 Invoking the <CODE>msgunfmt</CODE> Program</A></H2>
417 <P>
421 <PRE>
423 </PRE>
425 <P>
428 Uniforum style .po file.
430 </P>
438 <DD>
440 <DD>
447 <DD>
450 C# mode: input is a .NET .dll file containing a subclass of
454 <DD>
460 <DD>
465 </DL>
474 <DD>
475 Input .mo files.
477 </DL>
479 <P>
480 If no input <VAR>file</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
482 </P>
485 <H3><A NAME="SEC171" HREF="gettext_toc.html#TOC171">10.2.3 Input file location in Java mode</A></H3>
490 <DD>
492 <DD>
495 Specify the resource name.
498 <DD>
500 <DD>
506 </DL>
508 <P>
509 The class name is determined by appending the locale name to the resource name,
512 </P>
515 <H3><A NAME="SEC172" HREF="gettext_toc.html#TOC172">10.2.4 Input file location in C# mode</A></H3>
520 <DD>
522 <DD>
525 Specify the resource name.
528 <DD>
530 <DD>
537 <DD>
541 </DL>
543 <P>
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
546 locale.
548 </P>
551 <H3><A NAME="SEC173" HREF="gettext_toc.html#TOC173">10.2.5 Input file location in Tcl mode</A></H3>
556 <DD>
558 <DD>
565 <DD>
569 </DL>
571 <P>
572 The <SAMP>‘-l’</SAMP> and <SAMP>‘-d’</SAMP> options are mandatory. The <TT>‘.msg’</TT> file is
573 located in the specified directory.
575 </P>
583 <DD>
585 <DD>
588 Write output to specified file.
590 </DL>
592 <P>
593 The results are written to standard output if no output file is specified
596 </P>
604 <DD>
606 <DD>
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.
612 <DD>
615 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
618 <DD>
620 Always write an output file even if it contains no message.
623 <DD>
625 <DD>
628 Write the .po file using indented style.
631 <DD>
633 Write out a strict Uniforum conforming PO file. Note that this
634 Uniforum format should be avoided because it doesn't support the
635 GNU extensions.
638 <DD>
640 <DD>
644 that this file format doesn't support plural forms and silently drops
645 obsolete messages.
648 <DD>
651 Note that this file format doesn't support plural forms.
654 <DD>
656 <DD>
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
664 <DD>
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.
671 <DD>
673 <DD>
677 Generate sorted output. Note that using this option makes it much harder
678 for the translator to understand each message's context.
680 </DL>
689 <DD>
691 <DD>
694 Display this help and exit.
697 <DD>
699 <DD>
702 Output version information and exit.
705 <DD>
707 <DD>
710 Increase verbosity level.
712 </DL>
717 <P>
721 </P>
722 <P>
723 The format of the generated MO files is best described by a picture,
724 which appears below.
726 </P>
727 <P>
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
734 </P>
735 <P>
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
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.
747 </P>
748 <P>
749 The version is kept
750 separate from the magic number, instead of using different magic
752 not updated often.
754 </P>
755 <P>
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.
762 </P>
763 <P>
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.
775 </P>
776 <P>
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
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.
786 </P>
787 <P>
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
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
797 </P>
798 <P>
799 As for the strings themselves, they follow the hash file, and each
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.
807 </P>
808 <P>
810 Contexts are stored by storing the concatenation of the context, a
813 </P>
814 <P>
816 Plural forms are stored by letting the plural of the original string
817 follow the singular of the original string, separated through a
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
823 includes all of them.
825 </P>
826 <P>
828 However, the program interface currently used already presumes
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
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
836 platform dependent as well.)
838 </P>
839 <P>
840 This particular issue has been strongly debated in the GNU
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.
848 </P>
850 <PRE>
851 byte
852 +------------------------------------------+
854 | |
856 | |
857 8 | number of strings | == N
858 | |
859 12 | offset of table with original strings | == O
860 | |
861 16 | offset of table with translation strings | == T
862 | |
863 20 | size of hashing table | == S
864 | |
865 24 | offset of hashing table | == H
866 | |
867 . .
868 . (possibly more entries later) .
869 . .
870 | |
873 ... ... | |
875 | | | |
878 ... ... | | | |
880 | | | | | |
881 H | start hash table | | | | |
882 ... ... | | | |
883 H + S * 4 | end hash table | | | | |
884 | | | | | |
886 | | | | |
888 | | | |
889 ... ... | |
890 | | | |
892 | | |
894 | |
895 ... ...
896 | |
897 +------------------------------------------+
898 </PRE>
900 <P><HR><P>
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>.
902 </BODY>
903 </HTML>