Joomla! Documentation™

Manchmal ist es notwendig, speziell formatierte Felder in eine zu übersetzende Zeichenfolge aufzunehmen; besonders dann, wenn es sich um Zahlen handelt, die für Datums- und Uhrzeitangaben oder wenn andere genaue Formatierungsanweisungen erforderlich sind. Wenn die Zeichenketten nicht übersetzt werden sollen, könnten die Standard-PHP-Funktionen printf und sprintf verwendet werden. Die printf-Funktion gibt eine Zeichenfolge aus, die mit eingebetteten Formatierungsanweisungen formatiert wurde. Die sprintf-Funktion gibt eine Zeichenfolge zurück, die mit denselben eingebetteten Formatierungsanweisungen formatiert wurde.

Die JText-Klasse stellt Wrapper-Methoden für die Funktionen printf und sprintf bereit, mit denen statischer Text übersetzt und formatierte Felder mit derselben Syntax wie die PHP-Funktionen eingebettet werden können.

Angenommen, Sie haben die Zeichenfolge „Donations of 12.45 GBP have been received“, in der der Betrag von einer Variablen, beispielsweise $donations stammt, so können Sie die Zeichenfolge folgendermaßen in zwei Teile aufteilen:

JText::_( 'Donations of' ) . “ $donations GBP “ . JText::_( 'have been received' )

mit den sprachspezifischen Zeichenfolgen

DONATIONS OF=Donations of
HAVE BEEN RECEIVED=have been received

Das funktioniert jedoch nicht in Sprachen, in denen sich die eingebetteten Daten nicht an einer ähnlichen Stelle wie in der übersetzten Zeichenfolge befinden. Verwenden Sie stattdessen besser die sprintf-Methode.

JText::sprintf( 'Donations have been received', $donations )

mit der sprachspezifischen Zeichenfolge

DONATIONS HAVE BEEN RECEIVED=Donations of %.2f GBP have been received

You can include more than one format specifier in a translation string. Substitutions are carried out in order so this works as expected

JText::sprintf( 'String with numbers in it', $num1, $num2, $num3 )

with language definition string

STRING WITH NUMBERS IN IT=First %d, second %d, third %d

Syntax of format specifiers

The format specifier consists of a percent sign (%), followed by one or more of these elements, in order:

Order	Type	Values	Description
1.	Sign	+ or -	Optional. Forces a sign (+ or -) to be used on a number. By default, only the – sign is used on a number if it's negative. This specifier forces positive numbers to have the + sign attached as well.
2.	Padding	<space> or 0 or '<char>	Optional. Character to be used for padding the results to the correct string size. May be a space character or a 0 (zero character). The default is to pad with spaces. An alternative padding character can be specified by prefixing it with a single quote ().
3.	Alignment	<null> or -	Optional. Determines if the result should be left-justified or right-justified. The default is right-justified; a - character here will make it left-justified.
4.	Width	Number	Optional. Number of characters (minimum) that the conversion should result in.
5.	Precision	Number	Optional. Number of decimal digits that should be displayed for floating-point numbers. When using this specifier on a string, it acts as a cutoff point, setting a maximum character limit to the string.
6.	Type	Mandatory. The type of the argument data. Possible types are:
		%	A literal percent character. No argument is required
		b	The argument is treated as an integer and presented as a binary number.
		c	The argument is treated as an integer and presented as the character with that ASCII value.
		d	The argument is treated as an integer and presented as a signed decimal number.
		e	The argument is treated as scientific notation (e.g. 1.2e+2). The precision specifier stands for the number of digits after the decimal point since PHP 5.2.1. In earlier versions, it was taken as the number of significant digits (one less).
		u	The argument is treated as an integer and presented as an unsigned decimal number.
		f	The argument is treated as a float and presented as a floating-point number (locale aware).
		F	The argument is treated as a float and presented as a floating-point number (non-locale aware).
		o	The argument is treated as an integer and presented as an octal number.
		s	The argument is treated and presented as a string.
		x	The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
		X	The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).

Format argument swapping

The format string supports argument numbering and even swapping. This is useful where two or more data items must be embedded in a string but differences in language structure means that the order of use of the data items is not the same.

For example, suppose we have the following code:

echo JText::sprintf( 'Balls in the bucket', $number, $location );

with this language translation string

BALLS IN THE BUCKET=There are %d balls in the %s

Then if

$number = 3
$location = 'hat'

this would output “There are 3 balls in the hat”. But consider if you wanted to change the translation to

BALLS IN THE BUCKET=The %s contains %d balls

This would now output “The 3 contains hat balls” which is clearly nonsense. Rather than change the code, you can indicate in the translation string which argument each of the placeholders refer to. Change the translation to

BALLS IN THE BUCKET=The %2$s contains %1$d balls

and the output becomes “The hat contains 3 balls” as expected.

An added benefit of being able to number the arguments is that you can repeat the placeholders without adding more arguments in the code. For example, change the translation to

BALLS IN THE BUCKET=The %2$s contains %1$d balls, so there are %1$d balls in the %2$s

and this will correctly output “The hat contains 3 balls, so there are 3 balls in the hat”.