Lines Matching +refs:po +refs:string +refs:end
6 @c @end ifhtml
34 @c %**end of header
63 @end direntry
64 @end ifinfo
90 @end copying
91 @end ifinfo
125 @end ifnothtml
126 @end titlepage
131 @end ifnottex
192 * c-format Flag:: Telling something about the following string
321 * po/POTFILES.in:: @file{POTFILES.in} in @file{po/}
322 * po/LINGUAS:: @file{LINGUAS} in @file{po/}
323 * po/Makevars:: @file{Makevars} in @file{po/}
324 * po/Rules-*:: Extending @file{Makefile} in @file{po/}
341 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in @file{po.m4}
450 @end detailmenu
451 @end menu
453 @end ifinfo
473 when speaking of the installers or end users of the translated program.
487 @end group
488 @end example
499 @end menu
557 @end itemize
697 @end itemize
768 @end example
783 @end table
794 @cindex files, @file{.po} and @file{.mo}
795 The letters PO in @file{.po} files means Portable Object, to
802 original, translatable string of a given package with its translation
852 │ ├────> msgmerge ──────> LANG.po ────>────────╯ │
856 │ ├─── New LANG.po <────────────────────╯
862 @end group
863 @end ifhtml
876 | +----> msgmerge ------> LANG.po ---->--------' |
880 | +--- New LANG.po <--------------------'
886 @end group
887 @end ifnothtml
888 @end example
911 @end group
912 @end example
926 @end group
927 @end example
943 exactly where in C sources each string is used. All translations
953 The first time through, there is no @file{@var{lang}.po} yet, so the
955 @file{@var{package}.pot} to @file{@var{lang}.po}, where @var{lang}
967 While adding the translated messages into the @file{@var{lang}.po}
999 evolving over time, so the translations carried by @file{@var{lang}.po}
1012 existing @file{@var{lang}.po} file, by comparing it with a newer
1017 obsolete, in @file{@var{lang}.po}, those already translated entries
1025 @file{@var{lang}.po} file offering translations for all strings.
1081 @dfn{end users} that call programs of the package, once these have
1083 for both installers and end users.
1088 @end menu
1099 some @file{@var{ll}.po} files, often kept together into some @file{po/}
1101 have usually many @file{@var{ll}.po} files, where @var{ll} represents
1135 @cindex file format, @file{.po}
1143 between an original untranslated string and its corresponding
1155 #| msgid @var{previous-untranslated-string}
1156 msgid @var{untranslated-string}
1157 msgstr @var{translated-string}
1158 @end example
1170 @end example
1190 contain the previous untranslated string for which the translator gave
1198 first the untranslated string as it appears in the original program
1199 sources, and then, the translation of this string. The original
1200 string is introduced by the keyword @code{msgid}, and the translation,
1211 On the other hand, the @code{msgstr} string, as well as translator
1226 string might not be a correct translation (anymore). Only the translator
1242 The @code{c-format} flag tells that the untranslated string and the
1245 string happens to look like a C format string (with @samp{%} directives).
1247 In case the @code{c-format} flag is given for a string the @code{msgfmt}
1371 @end table
1385 #| msgid @var{previous-untranslated-string}
1387 msgid @var{untranslated-string}
1388 msgstr @var{translated-string}
1389 @end example
1392 @var{untranslated-string}. It is possible to have several entries with
1393 the same @var{untranslated-string} in a PO file, provided that they each
1394 have a different @var{context}. Note that an empty @var{context} string
1408 #| msgid @var{previous-untranslated-string-singular}
1409 #| msgid_plural @var{previous-untranslated-string-plural}
1410 msgid @var{untranslated-string-singular}
1411 msgid_plural @var{untranslated-string-plural}
1412 msgstr[0] @var{translated-string-case-0}
1414 msgstr[N] @var{translated-string-case-n}
1415 @end example
1420 #: src/msgcmp.c:338 src/po-lex.c:699
1426 @end example
1431 The @var{previous-untranslated-string} is optionally inserted by the
1434 on the @var{untranslated-string}.
1446 Each of @var{untranslated-string} and @var{translated-string} respects
1447 the C syntax for a character string, including the surrounding quotes
1451 line to be continued, and an opening quote should resume the string
1456 "Here is an example of how one might continue a very long string\n"
1457 "for the common case the string represents multi-line output.\n"
1458 @end example
1461 In this example, the empty string is used on the first line, to
1465 to be concatenated. Concatenating the empty string does not change
1466 the resulting overall string, but it is a way for us to comply with
1467 the necessity of @code{msgid} to be followed by a string on the same
1469 we find this to be a cleaner disposition. The empty string could have
1470 been omitted, but only if the string starting with @samp{Here} was
1479 One should carefully distinguish between end of lines marked as
1481 string, and end of lines in the PO file itself, outside string quotes,
1482 which have no incidence on the represented string.
1487 until the end of the PO file line. Comments written by translators
1514 * c-format Flag:: Telling something about the following string
1518 @end menu
1531 @end example
1534 calls with a format string that could be a translated C string (even if
1535 the C string comes from a different C module) should contain the line:
1539 @end example
1559 @end group
1560 @end example
1600 @end group
1601 @end example
1636 be adjusted. Usually preparing a string for translation is done right
1652 Use format strings instead of string concatenation.
1656 @end itemize
1668 @end example
1676 @end example
1694 @end example
1698 string @code{"File %s is %s protected"}, which is unintelligible. Change
1704 @end example
1717 and then combining these two half-sentences through dumb string concatenation
1727 @end example
1739 @end example
1746 @end example
1760 translatable string changes, the translator is faced with the task of
1761 updating the entire translated string. Maybe only a single word will
1762 have changed in the English string, but the translator doesn't see that
1775 @cindex string concatenation
1777 Hardcoded string concatenation is sometimes used to construct English
1786 @end example
1792 to use a format string:
1796 @end example
1802 integer through @code{printf}. It expands to a constant string, usually
1808 @end example
1816 @end example
1819 The PO file will contain the string "The amount is %0<PRId64>\n".
1822 contain the appropriate constant string, "d" or "ld" or "lld".
1833 @end example
1841 @cindex Java, string concatenation
1842 @cindex C#, string concatenation
1844 Java and C#, string concatenation is very frequently used, because it is a
1849 @end example
1852 into a statement involving a format string:
1858 @end example
1865 @end example
1868 into a statement involving a format string:
1873 @end example
1889 string. This is flawed. Some translators may convert it to a simple
1906 is done in such a way that each translatable string appears to be
1912 produced by formatting. The format string needs translation, as
1922 argument string. Most localizable strings are found in executable
1946 and write @samp{_("Translatable string")} instead of @samp{gettext
1947 ("Translatable string")}. Further, the coding rule, from GNU standards,
1950 So, the textual overhead per translatable string is reduced to
1960 @end example
1966 string as sole argument. It is also possible to define marking functions
1973 adjacent string tokens. Automatic string concatenation is performed
1978 you add or modify a string, you will have to ask yourself if the
1979 new or altered string requires translation, and include it within
1981 is an example of string @emph{not} requiring translation. But
2009 @end example
2034 Search through program sources for a string which looks like a
2035 candidate for translation (@code{po-tags-search}).
2039 Mark the last string found with @samp{_()} (@code{po-mark-translatable}).
2043 Mark the last string found with a keyword taken from a set of possible
2045 keywords (@code{po-select-mark-and-mark}).
2047 @end table
2049 @efindex po-tags-search@r{, PO Mode command}
2050 The @kbd{,} (@code{po-tags-search}) command searches for the next
2051 occurrence of a string which looks like a possible candidate for
2053 positioned in such a way that the string is near the top of this other
2054 window. If the string is too big to fit whole in this window, it is
2055 positioned so only its end is shown. In any case, the cursor
2056 is left in the PO file window. If the shown string would be better
2059 and skip to the next string by merely repeating the @kbd{,} command.
2061 A string is a good candidate for translation if it contains a sequence
2062 of three or more letters. A string containing at most two letters in
2091 @efindex po-mark-translatable@r{, PO Mode command}
2092 @efindex po-select-mark-and-mark@r{, PO Mode command}
2093 The @kbd{M-,} (@code{po-mark-translatable}) command will mark the
2094 recently found string with the @samp{_} keyword. The @kbd{M-.}
2095 (@code{po-select-mark-and-mark}) command will request that you type
2097 the string. Both commands will automatically create a new PO file
2098 untranslated entry for the string being marked, and make it the
2108 @kbd{,} for the next string, say.
2154 @end example
2157 A possible German translation for the above string might be:
2161 @end example
2167 string is regarded as the address.
2171 translation string match in type and number. If this is not the case
2183 @end example
2189 useful for @code{msgfmt} to test all the strings in the @file{.po} file.
2190 This might cause problems because the string might contain what looks
2191 like a format specifier, but the string is not used in @code{printf}.
2194 thinks might be a format string. There is no absolute rule for this,
2195 only a heuristic. In the @file{.po} file the entry is marked using the
2206 @code{xgettext:c-format}, it will mark the string in any case with
2208 @code{xgettext} does not recognize the string as a format string but
2211 before the string to be translated.
2216 @code{xgettext} does not recognize this as a format string but what
2222 round, i.e.@: a string marked as a format string actually is not a format
2223 string. In this case the @code{msgfmt} might give too many warnings and
2224 would prevent translating the @file{.po} file. The method to prevent
2226 to use must contain the string @code{xgettext:no-c-format}.
2228 If a string is marked with @code{c-format} and this is not correct the
2236 @cindex marking string initializers
2238 to mark translatable string with @code{gettext} or something like this.
2248 const char *string;
2250 string
2253 fputs (string);
2256 @end group
2257 @end example
2259 While it is no problem to mark the string @code{"a default message"} it
2260 is not possible to mark the string initializers for @code{messages}.
2263 can find them, and second we have to translate the string at runtime
2267 no-op. For the second we have to mark all access points to a string
2279 const char *string;
2281 string
2284 fputs (string);
2287 @end group
2288 @end example
2290 Please convince yourself that the string which is written by
2307 const char *string;
2309 string
2312 fputs (gettext (string));
2315 @end group
2316 @end example
2319 he uses @code{gettext_noop} for the string @code{"a default message"}.
2355 @end group
2356 @end example
2379 @end group
2380 @end example
2396 for translators using GNU Emacs or XEmacs with po-mode.
2425 @end smallexample
2432 @end smallexample
2473 @end group
2474 @end example
2482 @end smallexample
2491 @end smallexample
2496 @end enumerate
2505 @code{xgettext} creates a file named @file{@var{domainname}.po}. You
2516 @end menu
2528 @file{@var{LANG}.po}, as a copy of the @file{@var{package}.pot} template
2537 $ cd po
2539 @end example
2543 @file{@var{LANG}.po}. Then she modifies the initial comments and
2549 @end menu
2567 type @kbd{M-x po-mode RET} and then @kbd{RET} again to start editing the
2588 @end itemize
2611 Project's homepage, @uref{http://www.iro.umontreal.ca/contrib/po/HTML/},
2687 @end itemize
2723 @end table
2730 @end menu
2745 @end menu
2791 @end menu
2813 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
2814 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
2815 @end example
2817 Later, whenever you edit some @file{.po}
2818 file, or any file having the string @samp{.po.} within its name,
2819 Emacs loads @file{po-mode.elc} (or @file{po-mode.el}) as needed, and
2821 The string @emph{PO} appears in the mode line for any buffer for
2833 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
2834 'po-find-file-coding-system)
2835 (autoload 'po-find-file-coding-system "po-mode")
2836 @end example
2851 po-mode-map, which is a genuine Emacs mode, in a way that is not derived
2852 from text mode in any way. Functions found on @code{po-mode-hook},
2858 the string @samp{132t+3f+10u+2o} would tell the translator that the
2874 Undo last modification to the PO file (@code{po-undo}).
2878 Quit processing and save the PO file (@code{po-quit}).
2882 Quit processing, possibly after confirmation (@code{po-confirm-and-quit}).
2886 Temporary leave the PO file window (@code{po-other-window}).
2892 Show help about PO mode (@code{po-help}).
2896 Give some PO file statistics (@code{po-statistics}).
2900 Batch validate the format of the whole PO file (@code{po-validate}).
2902 @end table
2905 @efindex po-undo@r{, PO Mode command}
2906 The command @kbd{_} (@code{po-undo}) interfaces to the Emacs
2918 @efindex po-quit@r{, PO Mode command}
2919 @efindex po-confirm-and-quit@r{, PO Mode command}
2920 The commands @kbd{Q} (@code{po-quit}) and @kbd{q}
2921 (@code{po-confirm-and-quit}) are used when the translator is done with the
2931 @efindex po-other-window@r{, PO Mode command}
2932 The command @kbd{0} (@code{po-other-window}) is another, softer way,
2945 @efindex po-help@r{, PO Mode command}
2946 The command @kbd{h} (@code{po-help}) displays a summary of all available PO
2952 @efindex po-statistics@r{, PO Mode command}
2953 The command @kbd{=} (@code{po-statistics}) computes the total number of
2959 @efindex po-validate@r{, PO Mode command}
2960 The command @kbd{V} (@code{po-validate}) launches @code{msgfmt} in
3000 Redisplay the current entry (@code{po-current-entry}).
3004 Select the entry after the current one (@code{po-next-entry}).
3008 Select the entry before the current one (@code{po-previous-entry}).
3012 Select the first entry in the PO file (@code{po-first-entry}).
3016 Select the last entry in the PO file (@code{po-last-entry}).
3021 (@code{po-push-location}).
3025 Return to a previously saved entry location (@code{po-pop-location}).
3030 (@code{po-exchange-location}).
3032 @end table
3035 @efindex po-current-entry@r{, PO Mode command}
3042 (@code{po-current-entry}) has the sole purpose of redisplaying the
3061 @efindex po-next-entry@r{, PO Mode command}
3063 @efindex po-previous-entry@r{, PO Mode command}
3064 The commands @kbd{n} (@code{po-next-entry}) and @kbd{p}
3065 (@code{po-previous-entry}) move the cursor the entry following,
3071 @efindex po-first-entry@r{, PO Mode command}
3073 @efindex po-last-entry@r{, PO Mode command}
3074 The commands @kbd{<} (@code{po-first-entry}) and @kbd{>}
3075 (@code{po-last-entry}) move the cursor to the first entry, or last
3093 @efindex po-push-location@r{, PO Mode command}
3095 @efindex po-pop-location@r{, PO Mode command}
3097 onto a special stack. The command @kbd{m} (@code{po-push-location})
3100 @kbd{r} (@code{po-pop-location}) consumes the top stack element and
3112 @efindex po-exchange-location@r{, PO Mode command}
3113 The command @kbd{x} (@code{po-exchange-location}) simultaneously
3124 @cindex string normalization in entries
3126 There are many different ways for encoding a particular string into a
3131 particular string encoded into the @code{msgid} field of some entry.
3150 @emindex string normalization in entries
3152 @item M-x po-normalize
3153 @efindex po-normalize@r{, PO Mode command}
3156 @end table
3158 The special command @kbd{M-x po-normalize}, which has no associated
3165 speeding up @code{msgid} string lookup for some other PO mode commands.
3167 @kbd{M-x po-normalize} presently makes three passes over the entries.
3170 fields were using K&R style C string syntax for multi-line strings.
3187 string format is given below, for the particular benefit of those not
3192 Right now, in PO mode, strings are single line or multi-line. A string
3198 @end example
3210 @end example
3215 We might lump together all initial newlines into the empty string,
3218 string), so making the previous example appear:
3225 @end example
3227 There are a few yet undecided little points about string normalization,
3246 Find the next translated entry (@code{po-next-translated-entry}).
3250 Find the previous translated entry (@code{po-previous-translated-entry}).
3252 @end table
3255 @efindex po-next-translated-entry@r{, PO Mode command}
3257 @efindex po-previous-translated-entry@r{, PO Mode command}
3258 The commands @kbd{t} (@code{po-next-translated-entry}) and @kbd{T}
3259 (@code{po-previous-translated-entry}) move forwards or backwards, chasing
3263 @evindex po-auto-fuzzy-on-edit@r{, PO Mode variable}
3266 variable @code{po-auto-fuzzy-on-edit} is not @code{nil}, the entry having
3290 The slight alteration in the original string (the @code{msgid} string)
3291 should often be reflected in the translated string, and this requires
3305 Find the next fuzzy entry (@code{po-next-fuzzy-entry}).
3309 Find the previous fuzzy entry (@code{po-previous-fuzzy-entry}).
3313 Remove the fuzzy attribute of the current entry (@code{po-unfuzzy}).
3315 @end table
3318 @efindex po-next-fuzzy-entry@r{, PO Mode command}
3320 @efindex po-previous-fuzzy-entry@r{, PO Mode command}
3321 The commands @kbd{z} (@code{po-next-fuzzy-entry}) and @kbd{Z}
3322 (@code{po-previous-fuzzy-entry}) move forwards or backwards, chasing for
3327 @efindex po-unfuzzy@r{, PO Mode command}
3328 @evindex po-auto-select-on-unfuzzy@r{, PO Mode variable}
3329 The command @kbd{@key{TAB}} (@code{po-unfuzzy}) removes the fuzzy
3331 Further, if the variable @code{po-auto-select-on-unfuzzy} has not
3334 @code{po-auto-select-on-unfuzzy} is @code{nil}.
3336 The initial value of @code{po-auto-fuzzy-on-edit} is @code{nil}. However,
3337 if the variable @code{po-auto-fuzzy-on-edit} is set to @code{t}, any entry
3347 @efindex po-fade-out-entry@r{, PO Mode command}
3349 (@code{po-fade-out-entry}) over any translated entry to mark it as being
3354 command, the translator is asked for confirmation, if fuzzy string
3363 string, and leaves the @code{msgstr} string to be empty. Such entries,
3365 Later, when the programmer slightly modifies some string right in
3367 by the appearance of a new untranslated entry for the modified string.
3371 are easily recognizable by the fact they end with @w{@samp{msgstr ""}}.
3383 Find the next untranslated entry (@code{po-next-untranslated-entry}).
3387 Find the previous untranslated entry (@code{po-previous-untransted-entry}).
3391 Turn the current entry into an untranslated one (@code{po-kill-msgstr}).
3393 @end table
3396 @efindex po-next-untranslated-entry@r{, PO Mode command}
3398 @efindex po-previous-untransted-entry@r{, PO Mode command}
3399 The commands @kbd{u} (@code{po-next-untranslated-entry}) and @kbd{U}
3400 (@code{po-previous-untransted-entry}) move forwards or backwards,
3405 @efindex po-kill-msgstr@r{, PO Mode command}
3408 (@code{po-kill-msgstr}). @xref{Modifying Translations}.
3412 if some untranslated string still exists.
3428 to the original untranslated string. Commands interfacing with the
3441 Find the next obsolete entry (@code{po-next-obsolete-entry}).
3445 Find the previous obsolete entry (@code{po-previous-obsolete-entry}).
3450 (@code{po-fade-out-entry}).
3452 @end table
3455 @efindex po-next-obsolete-entry@r{, PO Mode command}
3457 @efindex po-previous-obsolete-entry@r{, PO Mode command}
3458 The commands @kbd{o} (@code{po-next-obsolete-entry}) and @kbd{O}
3459 (@code{po-previous-obsolete-entry}) move forwards or backwards,
3465 untranslated string which does not correspond to any marked string
3470 @efindex po-fade-out-entry@r{, PO Mode command}
3475 disappearance of a translation by using the untranslated string.
3476 The command @kbd{@key{DEL}} (@code{po-fade-out-entry}) pushes the current entry
3488 entries, for initializing the translation of a newly appeared string.
3490 we have to develop good and efficient measures of string similarity.
3518 Interactively edit the translation (@code{po-edit-msgstr}).
3524 Reinitialize the translation with the original, untranslated string
3525 (@code{po-msgid-to-msgstr}).
3529 Save the translation on the kill ring, and delete it (@code{po-kill-msgstr}).
3534 (@code{po-kill-ring-save-msgstr}).
3539 (@code{po-yank-msgstr}).
3541 @end table
3544 @efindex po-edit-msgstr@r{, PO Mode command}
3545 The command @kbd{@key{RET}} (@code{po-edit-msgstr}) opens a new Emacs
3557 @efindex po-msgid-to-msgstr@r{, PO Mode command}
3558 The command @kbd{@key{LFD}} (@code{po-msgid-to-msgstr}) initializes, or
3559 reinitializes the translation with the original string. This command is
3561 the original string, disregarding any previous work.
3563 @evindex po-auto-edit-with-msgid@r{, PO Mode variable}
3566 @code{po-auto-edit-with-msgid} to @code{t}, the translation gets
3567 initialised with the original string, in case none exists already.
3568 The default value for @code{po-auto-edit-with-msgid} is @code{nil}.
3570 @emindex starting a string translation
3572 string, or rather with a copy of the original string, is a matter of
3577 already being written in the original string. A translator may also
3578 like having the original string right under her eyes, as she will
3584 @efindex po-kill-msgstr@r{, PO Mode command}
3586 @efindex po-kill-ring-save-msgstr@r{, PO Mode command}
3587 The command @kbd{k} (@code{po-kill-msgstr}) merely empties the
3588 translation string, so turning the entry into an untranslated
3591 (@code{po-kill-ring-save-msgstr}) has also the effect of taking a
3606 translation string put on the kill ring by the @kbd{k} command is fully
3613 @efindex po-yank-msgstr@r{, PO Mode command}
3614 The command @kbd{y} (@code{po-yank-msgstr}) completely replaces the
3615 translation of the current entry by a string taken from the kill ring.
3617 string is @dfn{yanked} into the PO file buffer.
3625 until she finds the string she really wanted.
3627 When a string is yanked into a PO file entry, it is fully and
3630 push the inserted string inside comments. Once again, translators
3632 course, the necessity of the translated string itself respective to
3637 strings (or the translator comments) automatically saves the old string
3644 programmer slightly modifies some string right in the program, his
3646 of a new untranslated entry for the modified string, and the fact
3647 that the entry translating the original or unmodified string becomes
3658 to the unmodified string. Once found, she uses the @kbd{@key{DEL}} command
3665 then @kbd{m} again, for going on with the next untranslated string.
3698 Interactively edit the translator comments (@code{po-edit-comment}).
3703 (@code{po-kill-comment}).
3708 (@code{po-kill-ring-save-comment}).
3713 (@code{po-yank-comment}).
3715 @end table
3725 @efindex po-edit-comment@r{, PO Mode command}
3726 The command @kbd{#} (@code{po-edit-comment}) opens a new Emacs window
3737 @evindex po-subedit-mode-hook@r{, PO Mode variable}
3738 Functions found on @code{po-subedit-mode-hook}, if any, are executed after
3739 the string has been inserted in the edit buffer.
3742 @efindex po-kill-comment@r{, PO Mode command}
3744 @efindex po-kill-ring-save-comment@r{, PO Mode command}
3746 @efindex po-yank-comment@r{, PO Mode command}
3747 The command @kbd{K} (@code{po-kill-comment}) gets rid of all
3749 The command @kbd{W} (@code{po-kill-ring-save-comment}) takes
3752 (@code{po-yank-comment}) completely replaces the translator comments
3753 by a string taken at the front of the kill ring. When this command
3789 Complete edition (@code{po-subedit-exit}).
3793 Abort edition (@code{po-subedit-abort}).
3797 Consult auxiliary PO files (@code{po-subedit-cycle-auxiliary}).
3799 @end table
3803 @efindex po-subedit-exit@r{, PO Mode command}
3807 (@code{po-subedit-exit}) may be used to return the edited translation into
3812 @efindex po-subedit-abort@r{, PO Mode command}
3816 (@code{po-subedit-abort}) to merely get rid of edition, while preserving
3822 @efindex po-subedit-cycle-auxiliary@r{, PO Mode command}
3823 The command @w{@kbd{C-c C-a}} (@code{po-subedit-cycle-auxiliary})
3830 Functions found on @code{po-subedit-mode-hook}, if any, are executed after
3831 the string has been inserted in the edit buffer.
3834 inserting unwanted @kbd{@key{RET}} (newline) characters at the end of
3835 the translated string if those are not meant to be there, or to removing
3839 at the end of the string being edited, but this @code{<} is not really
3840 part of the string. On exiting the editing window with @w{@kbd{C-c C-c}},
3843 looses its delimiting property and integrally becomes part of the string.
3844 If she removes the delimiting @code{<}, then the edited string is taken
3846 the translated string ought to end itself with a genuine @code{<}, then
3847 the delimiting @code{<} may not be removed; so the string should appear,
3877 exactly where the untranslated string appears in the program sources.
3880 often faced with an original string which is not as informative as
3882 Before choosing how to translate the string, she needs to understand
3883 better what the string really means and how tight the translation has
3886 string originated, searching for surrounding comments the programmer
3908 (@code{po-cycle-source-reference}).
3913 (@code{po-select-source-reference}).
3918 (@code{po-consider-source-path}).
3923 (@code{po-ignore-source-path}).
3925 @end table
3928 @efindex po-cycle-source-reference@r{, PO Mode command}
3930 @efindex po-select-source-reference@r{, PO Mode command}
3931 The commands @kbd{s} (@code{po-cycle-source-reference}) and @kbd{M-s}
3932 (@code{po-select-source-reference}) both open another window displaying
3934 it shows an actual use of the string to be translated. By doing
3935 so, the command gives source program context for the string. But if
3965 available for a single string to translate.
3968 @efindex po-consider-source-path@r{, PO Mode command}
3970 @efindex po-ignore-source-path@r{, PO Mode command}
3980 The command @kbd{S} (@code{po-consider-source-path}) is used to interactively
3982 @kbd{M-S} (@code{po-ignore-source-path}) is used to select, with completion,
4009 (@code{po-cycle-auxiliary}).
4013 Switch to a particular auxiliary file (@code{po-select-auxiliary}).
4017 Declare this PO file as an auxiliary file (@code{po-consider-as-auxiliary}).
4022 (@code{po-ignore-as-auxiliary}).
4024 @end table
4027 @efindex po-consider-as-auxiliary@r{, PO Mode command}
4029 @efindex po-ignore-as-auxiliary@r{, PO Mode command}
4030 Command @kbd{A} (@code{po-consider-as-auxiliary}) adds the current
4032 (@code{po-ignore-as-auxiliary} just removes it.
4035 @efindex po-cycle-auxiliary@r{, PO Mode command}
4036 The command @kbd{a} (@code{po-cycle-auxiliary}) seeks all auxiliary PO
4046 @efindex po-select-auxiliary@r{, PO Mode command}
4047 The command @kbd{C-c C-a} (@code{po-select-auxiliary}) asks the translator
4057 ways for representing the same string, different writing would break the
4083 @end menu
4103 msgcat -o compendium.po file1.po file2.po
4104 @end example
4107 for the same string. Those occurrences will be marked as @code{fuzzy}
4109 @file{file1.po}:
4116 @end example
4119 and @file{file2.po}:
4126 @end example
4136 "#-#-#-#-# file1.po #-#-#-#-#\n"
4138 "#-#-#-#-# file2.po #-#-#-#-#\n"
4140 @end example
4153 msgcat --use-first -o compendium.po file1.po file2.po
4154 @end example
4170 msggrep --location src/getopt.c -o compendium.po file.po
4171 @end example
4186 msgmerge --compendium compendium.po -o file.po /dev/null file.pot
4187 @end example
4197 msgcat --use-first -o update.po compendium1.po compendium2.po file.po
4198 msgmerge update.po file.pot | sed -e '/^#~/d' > file.po
4199 @end example
4283 @end menu
4345 The functions are declared in the header file @samp{<gettext-po.h>}, and are
4351 @end deftp
4356 @end deftp
4361 @end deftp
4368 @end deftypefun
4373 @end deftypefun
4381 @end deftypefun
4388 @end deftypefun
4393 @end deftypefun
4398 iterator has reached the end of its message list.
4399 @end deftypefun
4406 English string) of a message. This is guaranteed to be non-@code{NULL}.
4407 @end deftypefun
4411 (untranslated English plural string) of a message with plurals, or @code{NULL}
4413 @end deftypefun
4418 string.
4419 @end deftypefun
4425 @end deftypefun
4461 @end example
4472 @end menu
4513 of string descriptors can be found. In both tables, each string
4514 descriptor uses two 32 bits integers, one for the string length,
4515 another for the offset of the string in the MO file, counting in bytes
4526 the MO file. This also has another advantage, as the empty string
4529 empty string necessarily becomes the first in both the original and
4543 the length which appears in the string descriptor. The @code{msgfmt}
4545 With this option, each string is separately aligned so it starts at
4551 @key{EOT} byte, and the original string, instead of the original string.
4554 Plural forms are stored by letting the plural of the original string
4555 follow the singular of the original string, separated through a
4556 @key{NUL} byte. The length which appears in the string descriptor
4557 includes both. However, only the singular of the original string
4560 @key{NUL} byte. Here also, the length in the string descriptor
4604 O | length & offset 0th string ----------------.
4605 O + 8 | length & offset 1st string ------------------.
4607 O + ((N-1)*8)| length & offset (N-1)th string | | |
4616 H + S * 4 | end hash table | | | | |
4618 | NUL terminated 0th string <----------------' | | |
4620 | NUL terminated 1st string <------------------' | |
4631 @end group
4632 @end example
4657 @end menu
4687 @end menu
4705 @end example
4719 char *translation = catgets (catd, set_no, msg_id, "original string");
4720 @end example
4729 @end display
4736 is @code{char *} the resulting string @emph{must not} be changed. It
4746 @end example
4795 @end menu
4804 perhaps impossible) and b) to access a string in a selected domain.
4812 @end example
4816 argument is a null-terminated string, whose characters must be legal in
4830 @end example
4834 The translation of the string @var{msgid} is returned if it is available
4876 @end example
4894 @end example
4927 @end example
4933 @end example
4990 string containing the name of the selected codeset. The string is
4995 @end deftypefun
5020 translation lookup is when a translation for a given string is searched,
5021 that is limited to a given context. The translation for the same string
5023 the same string in different contexts can be stored in the in the same
5033 @end example
5035 In a call of this macro, @var{msgctxt} and @var{msgid} must be string
5039 The @var{msgctxt} string is visible in the PO file to the translator.
5044 Finding a canonical @var{msgctxt} string that doesn't change over time can
5063 @end example
5081 @end smallexample
5086 family. But in two places the string passed into the function would be
5101 @end smallexample
5114 @end smallexample
5116 Whether or not to use the @samp{|} character at the end of the context is a
5120 string literals, more general macros are available:
5132 @end example
5134 Here @var{msgctxt} and @var{msgid} can be arbitrary string-valued expressions.
5136 are string literals, the macros without the @samp{_expr} suffix are more
5154 @end smallexample
5167 @end smallexample
5173 @end ifhtml
5176 @end ifnothtml
5190 @end example
5193 @end quotation
5207 @end ifhtml
5210 @end ifnothtml
5220 @end itemize
5227 These extra functions are taking instead of the one key string two
5229 the numerical argument and the first string as a key, the implementation
5231 form. The two string arguments then will be used to provide a return
5234 is used and it is assumed that the first string argument is the singular
5249 form of the string to be converted. It is also used as the key for the
5259 @end smallexample
5270 @end smallexample
5274 are not consumed by the format string.
5283 @end smallexample
5286 @end deftypefun
5293 @end deftypefun
5300 @end deftypefun
5318 header entry of the PO file (the one with the empty @code{msgid} string).
5323 @end smallexample
5326 many different plural forms exist for this language. The string
5355 @end smallexample
5365 @end table
5373 @end smallexample
5394 @end table
5402 @end table
5416 @end smallexample
5424 @end table
5431 @end smallexample
5439 @end table
5446 @end smallexample
5454 @end table
5462 @end smallexample
5470 @end table
5479 @end smallexample
5487 @end table
5496 @end smallexample
5504 @end table
5512 @end smallexample
5520 @end table
5529 @end smallexample
5537 @end table
5545 @end smallexample
5553 @end table
5554 @end table
5581 @end smallexample
5591 @end smallexample
5597 @end smallexample
5608 string has to be translated in an inner loop. While this is unavoidable
5609 when the string varies from one run of the loop to the other it is
5610 simply a waste of time when the string is always the same. Take the
5621 @end group
5622 @end example
5626 string is always the same. One way to use this is:
5637 @end group
5638 @end example
5664 Only when we come to a string which might be seen by the users and thus
5671 @end example
5678 additional characters per translatable string to @emph{3} (in words:
5686 @end example
5695 @end example
5711 @end example
5714 the @file{po/} directory of GNU @code{gettext} knows by default both of the
5719 programmer. Every time he comes to a translatable string he has to
5729 @code{catgets}. If you have a single word in a string and this string
5738 @end example
5740 Here we have to translate two times the string @code{"number"}. Even
5757 @end example
5760 difficult one can also consider changing one of the conflicting string a
5815 @end enumerate
5843 @end example
5851 @end itemize
5864 @end menu
5881 vs. @code{catgets} (XPG). In the end the committee couldn't
5932 Otherwise, we'll end up with two message catalog access systems installed
5946 other platforms, they're now going to have to include the front-end
5947 (@code{libintl}) code plus the back-end code (the non-@code{catgets}
5984 @end menu
6022 @end quotation
6033 @end example
6068 @end quotation
6108 On the other end, people might enjoy their own language a lot, and be
6165 @end itemize
6208 @end menu
6280 @end menu
6294 the wrong way, we could end up nowhere, or spoil a lot of energies.
6326 @end itemize
6335 @end example
6445 @end smallexample
6453 @end smallexample
6463 @end smallexample
6468 $ msguniq $HOME/gettextlogused > missing.po
6469 @end smallexample
6478 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq
6479 @end smallexample
6489 @end smallexample
6491 She takes the latest copy of @file{$lang.po} from the Translation Project,
6492 or from the package (in most cases, @file{$package/po/$lang.po}), or
6500 $ msggrep --domain=$domain missing.po | grep -v '^domain' \
6501 > $domain-missing.po
6502 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \
6503 > $domain.$lang-urgent.po
6504 @end smallexample
6506 The she translates @file{$domain.$lang-urgent.po} by use of a PO file editor
6514 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \
6515 > $domain.$lang.po
6516 @end smallexample
6518 Then she can submit @file{$domain.$lang.po} and proceed to the next domain.
6527 for installers and end users.
6558 @end menu
6609 tool and the @file{Makefile}s in the @file{intl/} and @file{po/}
6614 installers of your own package and end users do not really need any of
6619 @code{gettext} shall then be installed at the user site if the end users
6634 Your @file{po/} directory should receive all PO files submitted to you
6635 by the translator teams, each having @file{@var{ll}.po} as a name.
6642 @end itemize
6651 PO files in @file{po/} for distribution.
6697 * po/POTFILES.in:: @file{POTFILES.in} in @file{po/}
6698 * po/LINGUAS:: @file{LINGUAS} in @file{po/}
6699 * po/Makevars:: @file{Makevars} in @file{po/}
6700 * po/Rules-*:: Extending @file{Makefile} in @file{po/}
6710 @end menu
6712 @node po/POTFILES.in, po/LINGUAS, Adjusting Files, Adjusting Files
6713 @subsection @file{POTFILES.in} in @file{po/}
6716 The @file{po/} directory should receive a file named
6735 @end group
6736 @end example
6747 it is recommended to list in @file{po/POTFILES.in} the real source file
6751 @node po/LINGUAS, po/Makevars, po/POTFILES.in, Adjusting Files
6752 @subsection @file{LINGUAS} in @file{po/}
6755 The @file{po/} directory should also receive a file named
6764 @end group
6765 @end example
6788 in the @file{po/} directory. You can copy them from GNU gettext's @file{po/}
6791 @node po/Makevars, po/Rules-*, po/LINGUAS, Adjusting Files
6792 @subsection @file{Makevars} in @file{po/}
6795 The @file{po/} directory also has a file named @file{Makevars}. It
6796 contains variables that are specific to your project. @file{po/Makevars}
6797 gets inserted into the @file{po/Makefile} when the latter is created.
6802 single message domain and, accordingly, a single @file{po/} directory.
6803 Only packages which have multiple @file{po/} directories at different
6807 @node po/Rules-*, configure.in, po/Makevars, Adjusting Files
6808 @subsection Extending @file{Makefile} in @file{po/}
6811 All files called @file{Rules-*} in the @file{po/} directory get appended to
6812 the @file{po/Makefile} when it is created. They present an opportunity to
6814 with @file{po/Makefile.in.in}.
6819 building catalogs @file{en@@quot.po} and @file{en@@boldquot.po}. The
6820 effect of @file{en@@quot.po} is that people who set their @code{LANGUAGE}
6824 enable this catalog, simply add @code{en@@quot} to the @file{po/LINGUAS}
6825 file. The effect of @file{en@@boldquot.po} is that people who set
6830 @file{po/LINGUAS} file.
6837 @node configure.in, config.guess, po/Rules-*, Adjusting Files
6856 @end example
6863 @end example
6878 @end example
6889 @end example
6893 The @code{AC_OUTPUT} directive, at the end of your @file{configure.in}
6897 AC_OUTPUT([@var{existing configuration files} intl/Makefile po/Makefile.in],
6899 @end example
6902 for substitution in the @file{intl/} and @file{po/} directories.
6903 Note the @samp{.in} suffix used for @file{po/} only. This is because
6904 the distributed file is really @file{po/Makefile.in.in}.
6910 @end enumerate
6925 @end smallexample
6949 @end smallexample
6963 @end example
6984 @file{longdouble.m4}, @file{longlong.m4}, @file{nls.m4}, @file{po.m4},
6992 @file{nls.m4}, @file{po.m4}, @file{progtest.m4} need to be concatenated.
7012 @end example
7067 @end example
7083 @end example
7091 you also process the subdirectories @samp{intl} and @samp{po}. Special
7105 SUBDIRS = doc intl lib src po
7106 @end example
7115 @file{intl/Makefile} and @file{po/Makefile} will later assume that the
7135 @end example
7137 @end enumerate
7159 @end example
7168 @end example
7178 @end example
7187 @end example
7196 @end example
7210 @end example
7223 @end example
7241 @end example
7243 @end enumerate
7257 @end example
7264 @end example
7271 @end example
7280 @end example
7287 @end example
7301 @end example
7303 @end enumerate
7328 @end itemize
7349 @end example
7356 @end example
7380 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in @file{po.m4}
7382 @end menu
7392 the @file{po/} directories of the package for building.
7399 @end example
7473 @end itemize
7495 @end example
7525 @subsection AM_PO_SUBDIRS in @file{po.m4}
7528 The @code{AM_PO_SUBDIRS} macro prepares the @file{po/} directories of the
7538 variables in each @file{po/} directory.
7587 @end itemize
7603 @end menu
7642 @end itemize
7650 @code{@var{parser}.y}, or @code{po/Makefile.in.in} autoinstalled by
7663 @end enumerate
7690 @end enumerate
7703 @end example
7742 $ (cd po; make update-po)
7744 @end example
7767 Internationalized packages have usually many @file{@var{ll}.po}
7791 @end menu
7807 example, in C we use the syntax @code{_("string")}, and in GNU awk we use
7808 the shorthand @code{_"string"}.
7811 You should arrange that evaluation of such a translatable string at
7846 the string extractor is best integrated into your language's parser, GNU
7847 @code{xgettext} can function as a front end to your string extractor.
7850 The language's library should have a string formatting facility where
7851 the arguments of a format string are denoted by a positional number or a
7868 your language to @file{po-mode.el}.
7869 @end enumerate
7897 @end itemize
7904 @code{xgettext} string extractor recognizes other languages based on the
7938 @end menu
7954 @end example
7961 @end example
7981 untranslated string. (Putting the @samp{I} format directive flag into an
7982 @var{msgid} string would lead to undefined behaviour on platforms without
8132 string, a directive starts with @samp{%}, is optionally followed by a
8135 percent sign, @samp{c} denotes a character, @samp{s} denotes a string,
8137 denote an unsigned integer, @samp{.*s} denotes a string preceded by a
8152 directive cannot occur more than once in a format string.
8160 In summary, a directive has either the same syntax as in a C format string,
8181 variable in @file{po/Makevars} (@pxref{po/Makevars}) should be adjusted to
8185 in @file{po/Makefile.in.in}. It is recommended to make one @code{xgettext}
8188 @end itemize
8268 @end menu
8305 @*@code{#define _(string) gettext (string)}
8321 @item po-mode marking
8323 @end table
8379 @item po-mode marking
8381 @end table
8393 @end menu
8409 @end smallexample
8428 @end smallexample
8443 @end smallexample
8450 @end smallexample
8456 @end smallexample
8463 @end smallexample
8466 For each translatable string, change the output command @samp{echo} or
8467 @samp{$echo} to @samp{gettext} (if the string contains no references to
8476 function receives the translatable string before the variable values are
8481 @end smallexample
8487 @end smallexample
8497 @end smallexample
8503 @end smallexample
8509 @end smallexample
8510 @end enumerate
8521 and a newline, without interpreting backslashes in the argument string.
8528 @end itemize
8551 @end example
8564 @end example
8577 string and substituting variable values in it: @code{$"msgid"}. But
8582 the translation of the string, @code{bash} processes it like it processes
8583 any double-quoted string: dollar and backquote processing, like @samp{eval}
8605 @end enumerate
8662 @item po-mode marking
8664 @end table
8714 @item po-mode marking
8716 @end table
8766 @item po-mode marking
8768 @end table
8814 @item po-mode marking
8816 @end table
8862 @item po-mode marking
8864 @end table
8915 @item po-mode marking
8917 @end table
8967 @item po-mode marking
8969 @end table
9018 @item po-mode marking
9020 @end table
9022 Before marking strings as internationalizable, uses of the string
9058 In particular, its @code{getString} function returns a string translation.
9075 Its @code{gettext} function returns a string translation. Note that when
9084 @end enumerate
9104 @end smallexample
9110 @end smallexample
9117 @end smallexample
9126 @end smallexample
9133 @end smallexample
9140 @end smallexample
9154 @end smallexample
9161 @end smallexample
9162 @end itemize
9215 @item po-mode marking
9217 @end table
9219 Before marking strings as internationalizable, uses of the string
9248 @end itemize
9288 only contain data and only support lookups that depend on a single string.
9307 @end enumerate
9323 @end smallexample
9326 The @code{GetString} function returns a string's translation. Note that this
9341 @end smallexample
9343 The @code{GetString} function returns a string's translation. Note that when
9346 The @code{GetPluralString} function returns a string translation with plural
9352 @end enumerate
9375 @end smallexample
9382 @end smallexample
9389 @end smallexample
9403 @end smallexample
9410 @end smallexample
9411 @end itemize
9464 @item po-mode marking
9466 @end table
9516 @item po-mode marking
9518 @end table
9575 @item po-mode marking
9577 @end table
9624 @item po-mode marking
9626 @end table
9676 @item po-mode marking
9678 @end table
9684 into the string need to be converted to @code{format} applications. For
9732 @end itemize
9776 @item po-mode marking
9783 @end table
9792 Perl parser backend offers many more string marking facilities than
9806 @end menu
9819 @end example
9827 @end example
9829 In this context, the string @code{gettext} looks more like a
9836 @end example
9847 @end example
9849 In this case, the string @code{gettext} will be interpreted as a file
9851 and write the string ``Hello world!'' into it. Even advanced
9861 @end example
9890 @end example
9954 @end itemize
9961 original string in the translation database and returning the
9970 @end example
9988 @end example
10000 Perl offers a plethora of different string constructs. Those that can
10009 @end example
10015 @end example
10022 @end example
10033 @end example
10044 @end example
10069 @end group
10070 @end example
10073 quotes, the string is not interpolated. If it is enclosed in double
10074 quotes or has no quotes at all, the string is interpolated.
10078 @end itemize
10082 @cindex Perl invalid string interpolation
10092 @end example
10096 argument is not a string constant but a variable argument (@code{$0}
10098 executed). The interpolation is performed by Perl before the string
10102 up at runtime (except if, by accident, the interpolated string is found
10106 error if it encounters a variable inside of an extracted string. In
10107 general, this will happen for all kinds of string interpolations that
10114 @end example
10119 original string make it into your message catalog.
10156 @end itemize
10170 @item @code{\E} end case modification
10174 @end itemize
10176 These escapes are only considered safe if the string consists of
10189 @cindex Perl valid string interpolation
10208 @end example
10226 @end example
10238 @end example
10240 The @code{qq}-quoted string is recognized as an argument to @code{xgettext} in
10252 @end example
10273 # single-quoted string!
10293 @end group
10294 @end example
10304 operator (the string concatenation operator) may come in handy:
10313 @end group
10314 @end example
10316 Perl is smart enough to concatenate these constant string fragments
10317 into one long string at compile time, and so is
10322 (@samp{_}) as the string concatenation operator, and the dot
10337 @end group
10338 @end example
10351 @end group
10352 @end example
10379 @end example
10388 @end example
10393 string ``Sunday''. Use a temporary variable as a simple workaround if
10399 @end example
10409 @end example
10429 @end example
10436 @end example
10448 in your string, or if it describes a syntax, like in this one --, you can
10449 mark the string as @code{no-perl-brace-format} and use @code{printf()}:
10454 @end example
10462 @end example
10516 @item po-mode marking
10518 @end table
10566 @item po-mode marking
10568 @end table
10615 @item po-mode marking
10617 @end table
10652 @item po-mode marking
10653 @end table
10655 @end ignore
10667 @end menu
10677 @code{pot}, @code{po}
10681 @end table
10696 @end table
10710 @end table
10724 @end table
10726 @end ignore
10739 @end menu
10833 @end example
10847 @end example
10855 @end example
10860 @end example
10865 @end example
10882 @end menu
10892 @end table
10903 @end table
10916 @end table
10954 @end itemize
10960 @end menu
11002 @end iftex