Yelp

(The Help System)

l10n.gettext

Look up the translation for a string.

Parameters

domain

The domain to look up the string in.

msgid

The id of the string to look up, often the string in the C locale.

lang

The locale to use when looking up the translated string.

number

The cardinality for plural-form lookups.

form

The form name for plural-form lookups.

format

Whether to treat the result as a format string.

node

A context node to pass to l10n.format.mode.

string

A string to pass to l10n.format.mode for msg:string elements.

This template extracts a translated version of a source string. In simple cases, the source string is exactly the string in msgid, though in more complex cases, the msgid parameter is a separate unique identifier.

This template looks up the translation in a message catalog file based on the domain parameter. The file must be in a domains subdirectory relative to the directory holding this stylesheet and be named the same as domain with the suffix .xml. This template will fail if no such file is found. By default, the domain is yelp-xsl to reference the translations shipped with these stylesheets. Extensions and third-party stylesheets, however, can use this template by installing a file and passing the domain parameter.

The message catalog file format is designed to work with the XML/PO translation tool itstool, using its join mode to create a single polylingual file. There is no tool to automatically extract messages from XSLT files. You must add messages to the source catalog file when adding translatable strings.

The message catalog file contains a set of msg elements, one for each string that needs translation. Each msg element has an id attribute. It is this attribute that is matched against the msgid parameter. Each msg element then has one or more msgstr elements, each with an xml:lang attribute. This template tries to find a best match language with the lang parameter, falling back to a msgstr element with no xml:lang attribute.

In a source message catalog file, put the string to be translated inside a singleton msgstr element in each msg element, without an xml:lang parameter. Add this element even if it is the same as the id attribute of the msg element. These msgstr elements are what itstool uses to create a PO file, and it provides the fallback string when no language matches.

The xml:lang attribute should contain an RFC 3066 language identifier, which is different from the POSIX locale identifiers used by gettext. To accommodate this difference, this stylesheet converts all identifiers to lowercase and replaces the characters _, @, and . with the character -. If it cannot find an exact match, it strips the part after the last - and looks again. It repeats this as long as the identifier contains a - character. If there is still no matching msgstr element, it looks for one with no xml:lang attribute.

Sometimes you have to provide different versions of a string for different cardinalities. While English and many other languages have singular and plural, some languages have no plural forms, while others have as many as six. These stylesheets use a numeric index for plural forms, similarly to gettext. To get the string for a plural, pass the cardinality in the number parameter. This template gets an index for that number by calling l10n.plural.form. The plural form index is in the form parameter. You do not have to pass this parameter. It will be computed automatically based on the number parameter.

There is currently no support for editing plural forms using the standard PO syntax. Instead, plurals are defined with an XML snippet. Instead of putting the single translated message in the msgstr element, plural messages have msgstr child elements of the msgstr element with the xml:lang attribute. Each of these child msgstr elements has a form attribute that holds the numeric index returned by l10n.plural.form. Translators must adapt the XML snippet according to the plural rules and forms defined in this stylesheet for their language.

Some translations aren't simple strings, but are instead format strings where certain values are inserted. This template can handle format strings with XML marker elements to signal where values should be substituted. These values can be the result of applying templates.

To enable format strings, set the format parameter to true(). Instead of just returning the translated string, this template will apply templates in the mode l10n.format.mode to the fragment contained in the msgstr element.

The node and string parameters are passed to templates in l10n.format.mode. This stylesheet contains matches in l10n.format.mode for the marker elements <string/> and <node/>. The element <string/> will be replaced by the string value of string. The element <node/> will apply templates without a mode to node. Text nodes are copied to the result in l10n.format.mode.

If you need any other behavior, add elements with any name of your choosing to the format string, then match on those elements in l10n.format.mode. You will be able to use the node and string parameters in your template. Try to use a name that is unique.

Calls Templates

Calls Keys