-
While the presentation of gettext focuses mostly on C and
@@ -24,10 +24,10 @@ approach.
-
@@ -125,7 +125,7 @@ different effects on portability and copyright:
gettext's ‘intl/’ directory in
-your package, as described in section 13 The Maintainer's View. This allows you to
+your package, as described in section 13 The Maintainer's View. This allows you to
have internationalization on all kinds of platforms. Note that when you
then distribute your package, it legally falls under the GNU General
Public License, and the GNU project will be glad about your contribution
@@ -151,7 +151,7 @@ and plural handling).
-For the programmer, the general procedure is the same as for the C @@ -164,7 +164,7 @@ underlying language runtime.
-The translator works exactly as in the C language case. The only @@ -176,7 +176,7 @@ strings. -
C format strings are described in POSIX (IEEE P1003.1 2001), section @@ -214,8 +214,8 @@ activates these replacement functions automatically.
-
-
+
+
As a special feature for Farsi (Persian) and maybe Arabic, translators can
insert an ‘I’ flag into numeric format directives. For example, the
translation of "%d" can be "%Id". The effect of this flag,
@@ -234,7 +234,7 @@ glibc when NLS is disabled.)
Objective C format strings are like C format strings. They support an
@@ -244,7 +244,7 @@ of type Object *.
Shell format strings, as supported by GNU gettext and the ‘envsubst’ @@ -266,7 +266,7 @@ a variable reference is ignored.
-There are two kinds of format strings in Python: those acceptable to @@ -278,11 +278,10 @@ of the ‘str’ object.
Python % format strings are described in
Python Library reference /
-2. Built-in Types, Exceptions and Functions /
-2.2. Built-in Types /
-2.2.6. Sequence Types /
-2.2.6.2. String Formatting Operations.
-http://www.python.org/doc/2.2.1/lib/typesseq-strings.html.
+5. Built-in Types /
+5.6. Sequence Types /
+5.6.2. String Formatting Operations.
+http://docs.python.org/2/library/stdtypes.html#string-formatting-operations.
@@ -292,7 +291,7 @@ String Formatting, http://www
-Lisp format strings are described in the Common Lisp HyperSpec, @@ -302,7 +301,7 @@ chapter 22.3 Formatted Output,
-Emacs Lisp format strings are documented in the Emacs Lisp reference, @@ -314,7 +313,7 @@ in format strings while FSF Emacs doesn't.
-librep format strings are documented in the librep manual, section @@ -325,7 +324,7 @@ Formatted Output,
-Scheme format strings are documented in the SLIB manual, section @@ -334,7 +333,7 @@ Format Specification.
-Smalltalk format strings are described in the GNU Smalltalk documentation, @@ -347,7 +346,7 @@ or a nonzero digit (‘1’ to ‘9’
-Java format strings are described in the JDK documentation for class @@ -359,7 +358,7 @@ See also the ICU documentation
-C# format strings are described in the .NET documentation for class @@ -369,7 +368,7 @@ C# format strings are described in the .NET documentation for class
-awk format strings are described in the gawk documentation, section @@ -379,7 +378,7 @@ Printf,
-Object Pascal format strings are described in the documentation of the @@ -389,7 +388,7 @@ Free Pascal runtime library, section Format,
-YCP sformat strings are described in the libycp documentation @@ -400,7 +399,7 @@ or a nonzero digit (‘1’ to ‘9’
-Tcl format strings are described in the ‘format.n’ manual page, @@ -409,7 +408,7 @@ Tcl format strings are described in the ‘format.n’ manual p
-There are two kinds format strings in Perl: those acceptable to the @@ -433,7 +432,7 @@ of simple identifiers.
-PHP format strings are described in the documentation of the PHP function @@ -443,7 +442,7 @@ PHP format strings are described in the documentation of the PHP function
-These format strings are used inside the GCC sources. In such a format @@ -464,7 +463,7 @@ operator, ‘V’ denotes a const/volatile qualifier.
-
These format strings are used inside the GNU Fortran Compiler sources,
@@ -479,7 +478,7 @@ denote an integer, ‘u’ denotes an unsigned integer.
-15.3.20 Qt Format Strings
+15.3.20 Qt Format Strings
Qt format strings are described in the documentation of the QString class @@ -490,7 +489,7 @@ directive cannot occur more than once in a format string.
-Qt format strings are described in the documentation of the QObject::tr method @@ -500,7 +499,7 @@ In summary, the only allowed directive is ‘%n’.
-KDE 4 format strings are defined as follows: @@ -511,7 +510,24 @@ must occur as well, except possibly one of them.
-+KUIT (KDE User Interface Text) is compatible with KDE 4 format strings, +while it also allows programmers to add semantic information to a format +string, through XML markup tags. For example, if the first format +directive in a string is a filename, programmers could indicate that +with a ‘filename’ tag, like ‘<filename>%1</filename>’. + +
++KUIT format strings are described in +http://api.kde.org/frameworks-api/frameworks5-apidocs/ki18n/html/prg_guide.html#kuit_markup. + +
+ + +Boost format strings are described in the documentation of the @@ -525,7 +541,7 @@ between percent signs, such as ‘%1%’.
-Lua format strings are described in the Lua reference manual, section String Manipulation, @@ -534,7 +550,7 @@ Lua format strings are described in the Lua reference manual, section String Man
-Although JavaScript specification itself does not define any format @@ -552,7 +568,7 @@ object. -
For the maintainer, the general procedure differs from the C language
@@ -572,7 +588,7 @@ invokes the AM_GNU_GETTEXT autoconf macro via
XGETTEXT_OPTIONS
-variable in ‘po/Makevars’ (see section 13.4.3 ‘Makevars’ in ‘po/’) should be adjusted to
+variable in ‘po/Makevars’ (see section 13.4.3 ‘Makevars’ in ‘po/’) should be adjusted to
match the xgettext options for that particular programming language.
If the package uses more than one programming language with gettext
support, it becomes necessary to change the POT file construction rule
@@ -583,13 +599,13 @@ that language, and to combine the resulting files using msgcat.
-gettext, ngettext programs
eval_gettext, eval_ngettext shell functions
TEXTDOMAIN
TEXTDOMAINDIR
-15.5.2.1 Preparing Shell Scripts for Internationalization
+15.5.2.1 Preparing Shell Scripts for Internationalization
@@ -767,8 +783,8 @@ Insert the line
near the top of the script. gettext.sh is a shell function library
that provides the functions
-eval_gettext (see section 15.5.2.6 Invoking the eval_gettext function) and
-eval_ngettext (see section 15.5.2.7 Invoking the eval_ngettext function).
+eval_gettext (see section 15.5.2.6 Invoking the eval_gettext function) and
+eval_ngettext (see section 15.5.2.7 Invoking the eval_ngettext function).
You have to ensure that gettext.sh can be found in the PATH.
-
@@ -883,7 +899,7 @@ error "`eval_gettext \"file not found: \\\$filename\"`"
-
15.5.2.2 Contents of gettext.sh
+15.5.2.2 Contents of gettext.sh
gettext.sh, contained in the run-time package of GNU gettext, provides
@@ -899,20 +915,20 @@ and a newline, without interpreting backslashes in the argument string.
- eval_gettext
-See section 15.5.2.6 Invoking the
eval_gettext function.
+See section 15.5.2.6 Invoking the eval_gettext function.
- eval_ngettext
-See section 15.5.2.7 Invoking the
eval_ngettext function.
+See section 15.5.2.7 Invoking the eval_ngettext function.
-15.5.2.3 Invoking the gettext program
+15.5.2.3 Invoking the gettext program
gettext [option] [[textdomain] msgid]
@@ -920,7 +936,7 @@ gettext [option] -s [msgid]...
-
+
The gettext program displays the native language translation of a
textual message.
@@ -935,14 +951,14 @@ textual message.
-
- ‘--domain=textdomain’
-
-
-
+
+
Retrieve translated messages from textdomain. Usually a textdomain
corresponds to a package, a program, or a module of a program.
- ‘-e’
-
-
+
Enable expansion of some escape sequences. This option is for compatibility
with the ‘echo’ program or shell built-in. The escape sequences
‘\a’, ‘\b’, ‘\c’, ‘\f’, ‘\n’, ‘\r’, ‘\t’,
@@ -951,7 +967,7 @@ interpreted like the System V ‘echo’ program did.
- ‘-E’
-
-
+
This option is only for compatibility with the ‘echo’ program or shell
built-in. It has no effect.
@@ -959,13 +975,13 @@ built-in. It has no effect.
-
- ‘--help’
-
-
-
+
+
Display this help and exit.
- ‘-n’
-
-
+
Suppress trailing newline. By default,
gettext adds a newline to
the output.
@@ -973,8 +989,8 @@ the output.
-
- ‘--version’
-
-
-
+
+
Output version information and exit.
- ‘[textdomain] msgid’
@@ -1004,18 +1020,18 @@ Note:
xgettext supports only the one-argument form of the
-15.5.2.4 Invoking the ngettext program
+15.5.2.4 Invoking the ngettext program
ngettext [option] [textdomain] msgid msgid-plural count
-
+
The ngettext program displays the native language translation of a
textual message whose grammatical form depends on a number.
@@ -1030,14 +1046,14 @@ textual message whose grammatical form depends on a number.
-
- ‘--domain=textdomain’
-
-
-
+
+
Retrieve translated messages from textdomain. Usually a textdomain
corresponds to a package, a program, or a module of a program.
- ‘-e’
-
-
+
Enable expansion of some escape sequences. This option is for compatibility
with the ‘gettext’ program. The escape sequences
‘\a’, ‘\b’, ‘\c’, ‘\f’, ‘\n’, ‘\r’, ‘\t’,
@@ -1046,7 +1062,7 @@ interpreted like the System V ‘echo’ program did.
- ‘-E’
-
-
+
This option is only for compatibility with the ‘gettext’ program. It has
no effect.
@@ -1054,16 +1070,16 @@ no effect.
-
- ‘--help’
-
-
-
+
+
Display this help and exit.
- ‘-V’
-
- ‘--version’
-
-
-
+
+
Output version information and exit.
- ‘textdomain’
@@ -1095,20 +1111,20 @@ Note:
xgettext supports only the three-arguments form of the
-15.5.2.5 Invoking the envsubst program
+15.5.2.5 Invoking the envsubst program
envsubst [option] [shell-format]
-
-
-
+
+
+
The envsubst program substitutes the values of environment variables.
@@ -1122,8 +1138,8 @@ The envsubst program substitutes the values of environment variable
-
- ‘--variables’
-
-
-
+
+
Output the variables occurring in shell-format.
eval_gettext functioneval_gettext functioneval_gettext msgid
- + This function outputs the native language translation of a textual message, performing dollar-substitution on the result. Note that only shell variables mentioned in msgid will be dollar-substituted in the result. @@ -1195,17 +1211,17 @@ mentioned in msgid will be dollar-substituted in the result.
-eval_ngettext functioneval_ngettext functioneval_ngettext msgid msgid-plural count
- + This function outputs the native language translation of a textual message whose grammatical form depends on a number, performing dollar-substitution on the result. Note that only shell variables mentioned in msgid or @@ -1214,9 +1230,9 @@ on the result. Note that only shell variables mentioned in msgid or
-
@@ -1265,9 +1281,9 @@ that don't have the gettext() function in libc.
-15.5.6 GNU clisp C sources
+15.5.6 GNU clisp C sources
@@ -1519,9 +1535,9 @@ On platforms without gettext, no translation.
-15.5.7 Emacs Lisp
+15.5.7 Emacs Lisp
@@ -1585,9 +1601,9 @@ Only XEmacs. Without I18N3 defined at build time, no translation.
-15.5.8 librep
+15.5.8 librep
@@ -1655,10 +1671,10 @@ An example is available in the ‘examples’ directory:
-15.5.9 GNU guile - Scheme
+15.5.9 GNU guile - Scheme
@@ -1677,7 +1693,7 @@ guile
- gettext shorthand
-
-
(_ "abc")
+(_ "abc"), _"abc" (GIMP script-fu extension)
- gettext/ngettext functions
-
@@ -1726,9 +1742,9 @@ An example is available in the ‘examples’ directory:
-15.5.10 GNU Smalltalk
+15.5.10 GNU Smalltalk
@@ -1799,9 +1815,9 @@ An example is available in the ‘examples’ directory:
-15.5.11 Java
+15.5.11 Java
@@ -1935,7 +1951,7 @@ This has the advantage of having the ngettext function for plural
handling and the pgettext and npgettext for strings constraint
to a particular context.
-
+
To use this API, one needs the libintl.jar file which is part of
the GNU gettext package and distributed under the LGPL.
@@ -2042,9 +2058,9 @@ than a class with a single-letter name.
-15.5.12 C#
+15.5.12 C#
@@ -2283,7 +2299,7 @@ The GetParticularPluralString function returns a string translation
specific to a particular context, with plural handling, like the
npgettext function in C.
-
+
To use this API, one needs the GNU.Gettext.dll file which is part of
the GNU gettext package and distributed under the LGPL.
@@ -2368,10 +2384,10 @@ with a single-letter name.
-15.5.13 GNU awk
+15.5.13 GNU awk
@@ -2382,7 +2398,9 @@ gawk 3.1 or newer
- File extension
-
-
awk
+awk, gawk, twjr.
+The file extension twjr is used by TexiWeb Jr
+(https://github.com/arnoldrobbins/texiwebjr).
- String syntax
-
@@ -2441,11 +2459,11 @@ An example is available in the ‘examples’ directory:
-15.5.14 Pascal - Free Pascal Compiler
+15.5.14 Pascal - Free Pascal Compiler
@@ -2522,9 +2540,9 @@ An example is available in the ‘examples’ directory:
-15.5.15 wxWidgets library
+15.5.15 wxWidgets library
@@ -2590,10 +2608,10 @@ yes
-15.5.16 YCP - YaST2 scripting language
+15.5.16 YCP - YaST2 scripting language
@@ -2661,10 +2679,10 @@ An example is available in the ‘examples’ directory:
-15.5.17 Tcl - Tk's scripting language
+15.5.17 Tcl - Tk's scripting language
@@ -2747,9 +2765,9 @@ argument is given.
-15.5.18 Perl
+15.5.18 Perl
@@ -2862,7 +2880,7 @@ An example is available in the ‘examples’ directory:
@@ -2877,7 +2895,7 @@ worst probably being its imperfectness.
-
15.5.18.1 General Problems Parsing Perl Code
+15.5.18.1 General Problems Parsing Perl Code
It is often heard that only Perl can parse Perl. This is not true.
@@ -3082,9 +3100,9 @@ about such constructs.
-15.5.18.2 Which keywords will xgettext look for?
+15.5.18.2 Which keywords will xgettext look for?
@@ -3131,9 +3149,9 @@ The keys of lookups into the hash reference $gettext will be extrac
-
15.5.18.3 How to Extract Hash Keys
+15.5.18.3 How to Extract Hash Keys
@@ -3186,9 +3204,9 @@ are not allowed, regardless of the use utf8 pragma.
-15.5.18.4 What are Strings And Quote-like Expressions?
+15.5.18.4 What are Strings And Quote-like Expressions?
@@ -3286,9 +3304,9 @@ Delimiters that start with a digit are not supported!
-
15.5.18.5 Invalid Uses Of String Interpolation
+15.5.18.5 Invalid Uses Of String Interpolation
@@ -3424,9 +3442,9 @@ well write what you mean.
-15.5.18.6 Valid Uses Of String Interpolation
+15.5.18.6 Valid Uses Of String Interpolation
@@ -3512,9 +3530,9 @@ s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g;
-
15.5.18.7 When To Use Parentheses
+15.5.18.7 When To Use Parentheses
@@ -3558,9 +3576,9 @@ print dngettext 'package', ("one cake", "several cakes", $n), $discarded;
-
15.5.18.8 How To Grok with Long Lines
+15.5.18.8 How To Grok with Long Lines
@@ -3632,9 +3650,9 @@ the resulting POT file.
-15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work
+15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work
@@ -3784,9 +3802,9 @@ get executed. Most of the time you will happily get along with
-15.5.19 PHP Hypertext Preprocessor
+15.5.19 PHP Hypertext Preprocessor
@@ -3855,9 +3873,9 @@ An example is available in the ‘examples’ directory:
-15.5.20 Pike
+15.5.20 Pike
@@ -3921,9 +3939,9 @@ On platforms without gettext, the functions are not available.
-15.5.21 GNU Compiler Collection sources
+15.5.21 GNU Compiler Collection sources
@@ -3988,7 +4006,7 @@ yes
-15.5.22 Lua
+15.5.22 Lua
@@ -4067,7 +4085,7 @@ On platforms without gettext, the functions are not available.
-15.5.23 JavaScript
+15.5.23 JavaScript
@@ -4138,7 +4156,78 @@ On platforms without gettext, the functions are not available.
-15.6 Internationalizable Data
+15.5.24 Vala
+
+
+
+- RPMs
+
-
+vala
+
+
- File extension
+
-
+
vala
+
+ - String syntax
+
-
+
+
+
+"abc"
+
+"""abc"""
+
+
+
+ - gettext shorthand
+
-
+
_("abc")
+
+ - gettext/ngettext functions
+
-
+
gettext, dgettext, dcgettext, ngettext,
+dngettext, dpgettext, dpgettext2
+
+ - textdomain
+
-
+
textdomain function, defined under the Intl namespace
+
+ - bindtextdomain
+
-
+
bindtextdomain function, defined under the Intl namespace
+
+ - setlocale
+
-
+Programmer must call
Intl.setlocale (LocaleCategory.ALL, "")
+
+ - Prerequisite
+
-
+---
+
+
- Use or emulate GNU gettext
+
-
+Use
+
+
- Extractor
+
-
+
xgettext
+
+ - Formatting with positions
+
-
+Same as for the C language.
+
+
- Portability
+
-
+autoconf (gettext.m4) and #if ENABLE_NLS
+
+
- po-mode marking
+
-
+yes
+
+
+
+
+15.6 Internationalizable Data
Here is a list of other data formats which can be internationalized
@@ -4148,7 +4237,7 @@ using GNU gettext.
-
15.6.1 POT - Portable Object Template
+15.6.1 POT - Portable Object Template
@@ -4167,9 +4256,9 @@ gettext
-15.6.2 Resource String Table
+15.6.2 Resource String Table
@@ -4189,7 +4278,7 @@ fpk
-15.6.3 Glade - GNOME user interface description
+15.6.3 Glade - GNOME user interface description
@@ -4206,6 +4295,245 @@ glade, libglade, glade2, libglade2, intltool
xgettext, libglade-xgettext, xml-i18n-extract, intltool-extract
+
+
+15.6.4 GSettings - GNOME user configuration schema
+
+
+
+- RPMs
+
-
+glib2
+
+
- File extension
+
-
+
gschema.xml
+
+ - Extractor
+
-
+
xgettext, intltool-extract
+
+
+
+
+15.6.5 AppData - freedesktop.org application description
+
+
+
+- RPMs
+
-
+appdata-tools, appstream, libappstream-glib, libappstream-glib-builder
+
+
- File extension
+
-
+
appdata.xml
+
+ - Extractor
+
-
+
xgettext, intltool-extract, itstool
+
+
+
+
+15.6.6 Preparing Rules for XML Internationalization
+
+
+Marking translatable strings in an XML file is done through a separate
+"rule" file, making use of the Internationalization Tag Set standard
+(ITS, http://www.w3.org/TR/its20/). The currently supported ITS
+data categories are: ‘Translate’, ‘Localization Note’,
+‘Elements Within Text’, and ‘Preserve Space’. In addition to
+them, xgettext also recognizes the following extended data
+categories:
+
+
+
+
+- ‘Context’
+
-
+This data category associates
msgctxt to the extracted text. In
+the global rule, the contextRule element contains the following:
+
+
+
+-
+
+A required
selector attribute. It contains an absolute selector
+that selects the nodes to which this rule applies.
+
+ -
+
+A required
contextPointer attribute that contains a relative
+selector pointing to a node that holds the msgctxt value.
+
+ -
+
+An optional
textPointer attribute that contains a relative
+selector pointing to a node that holds the msgid value.
+
+
+ - ‘Escape Special Characters’
+
-
+This data category indicates whether the special XML characters
+(
<, >, &, ") are escaped with entity
+reference. In the global rule, the escapeRule element contains
+the following:
+
+
+
+-
+
+A required
selector attribute. It contains an absolute selector
+that selects the nodes to which this rule applies.
+
+ -
+
+A required
escape attribute with the value yes or no.
+
+
+ - ‘Extended Preserve Space’
+
-
+This data category extends the standard ‘Preserve Space’ data
+category with the additional value ‘trim’. The value means to
+remove the leading and trailing whitespaces of the content, but not to
+normalize whitespaces in the middle. In the global rule, the
+
preserveSpaceRule element contains the following:
+
+
+
+-
+
+A required
selector attribute. It contains an absolute selector
+that selects the nodes to which this rule applies.
+
+ -
+
+A required
space attribute with the value default,
+preserve, or trim.
+
+
+
+
+
+All those extended data categories can only be expressed with global
+rules, and the rule elements have to have the
+https://www.gnu.org/s/gettext/ns/its/extensions/1.0 namespace.
+
+
+
+Given the following XML document in a file ‘messages.xml’:
+
+
+
+
+<?xml version="1.0"?>
+<messages>
+ <message>
+ <p>A translatable string</p>
+ </message>
+ <message>
+ <p translatable="no">A non-translatable string</p>
+ </message>
+</messages>
+
+
+
+To extract the first text content ("A translatable string"), but not the
+second ("A non-translatable string"), the following ITS rules can be used:
+
+
+
+
+<?xml version="1.0"?>
+<its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0">
+ <its:translateRule selector="/messages" translate="no"/>
+ <its:translateRule selector="//message/p" translate="yes"/>
+
+ <!-- If 'p' has an attribute 'translatable' with the value 'no', then
+ the content is not translatable. -->
+ <its:translateRule selector="//message/p[@translatable = 'no']"
+ translate="no"/>
+</its:rules>
+
+
+
+‘xgettext’ needs another file called "locating rule" to associate
+an ITS rule with an XML file. If the above ITS file is saved as
+‘messages.its’, the locating rule would look like:
+
+
+
+
+<?xml version="1.0"?>
+<locatingRules>
+ <locatingRule name="Messages" pattern="*.xml">
+ <documentRule localName="messages" target="messages.its"/>
+ </locatingRule>
+ <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
+</locatingRules>
+
+
+
+The locatingRule element must have a pattern attribute,
+which denotes either a literal file name or a wildcard pattern of the
+XML file. The locatingRule element can have child
+documentRule element, which adds checks on the content of the XML
+file.
+
+
+
+The first rule matches any file with the ‘.xml’ file extension, but
+it only applies to XML files whose root element is ‘<messages>’.
+
+
+
+The second rule indicates that the same ITS rule file are also
+applicable to any file with the ‘.msg’ file extension. The
+optional name attribute of locatingRule allows to choose
+rules by name, typically with xgettext's -L option.
+
+
+
+The associated ITS rule file is indicated by the target attribute
+of locatingRule or documentRule. If it is specified in a
+documentRule element, the parent locatingRule shouldn't
+have the target attribute.
+
+
+
+Locating rule files must have the ‘.loc’ file extension. Both ITS
+rule files and locating rule files must be installed in the
+‘$prefix/share/gettext/its’ directory. Once those files are
+properly installed, xgettext can extract translatable strings
+from the matching XML files.
+
+
+
+
+15.6.6.1 Two Use-cases of Translated Strings in XML
+
+
+For XML, there are two use-cases of translated strings. One is the case
+where the translated strings are directly consumed by programs, and the
+other is the case where the translated strings are merged back to the
+original XML document. In the former case, special characters in the
+extracted strings shouldn't be escaped, while they should in the latter
+case. To control wheter to escape special characters, the ‘Escape
+Special Characters’ data category can be used.
+
+
+
+To merge the translations, the ‘msgfmt’ program can be used with
+the option --xml. See section 10.1 Invoking the msgfmt Program, for more details
+about how one calls the ‘msgfmt’ program. ‘msgfmt’'s
+--xml option doesn't perform character escaping, so translated
+strings can have arbitrary XML constructs, such as elements for markup.
+
+
+
Go to the first, previous, next, last section, table of contents.