Formatted fields in language translation strings/nl

Soms is het noodzakelijk om speciaal opgemaakte velden in een string die vertaald moet worden op te nemen. Dit is vaak het geval bij getallen maar kan ook optreden bij datums of tijden of wanneer precieze opmaak instructies noodzakelijk zijn. Als de strings niet vertaald hoeven worden, kunnen de standaard PHP functies printf en sprintf gebruikt worden. De printf functie levert een opgemaakte string gebruik makend van ingebouwde opmaak-instructies; de sprintf functie levert een opgemaakt string met dezelfde ingebouwde opmaak-instructies.

De JText class biedt wrapper-methoden voor de printf en sprintf functies die het mogelijk maakt statische tekst te vertalen terwijl het ook de mogelijkheid geeft opgemaakte velden op te nemen met dezelfde syntax als de PHP functies.

Veronderstel bijvoorbeeld dat u de string “Donations of 12.45 GBP have been received” heeft, waarbij het bedrag uit de variabele $donations komt. U moet de string dan zo in tweeën opsplitsen:

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

met de taalstrings

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

Maar dit werkt niet goed in talen waar de ingesloten gegevens niet op dezelfde plaats staan in de taalstring. Gebruik in plaats daarvan de sprintf methode als volgt

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

met de taalstring

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

Er kan meer dan een opmaak specificatie in een vertaalstring zitten. Vervanging wordt op volgorde uitgevoerd, het werkt dus zoals verwacht

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

met de taalstrings

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

Syntaxis van opmaak specificaties

De opmaak-specificatie bestaat uit een percentage-teken (%), gevolgd door een of meer van deze elementen, in de volgorde:

Volgorde	Type	Waarden	Beschrijving
1.	Teken	+ of -	Optioneel. Dwingt een teken (+ of -) bij een getal af. Standaard wordt alleen het – teken gebruikt bij een getal als het negatief is. Dit teken forceert dat positieve getallen een + teken toegevoegd krijgen.
2.	Uitvullen	<spatie> of 0 of '<char>	Optioneel. Teken dat gebruikt wordt om het resultaat uit te vullen tot de juiste string-lengte. Mag een spatie-teken zijn of een 0 (nul teken). De standaard is om uit te vullen met spaties. Een alternatief uitvul-teken kan worden opgegeven door een enkele quote (') voor te voegen.
3.	Uitlijning	<null> of -	Optionel. Bepaalt of het resultaat links- of rechts uitgelijnd moet worden. De standaard is rechts-uitgelijnd; een - teken hier maakt het links-uitgelijnd.
4.	Breedte	Getal	Optioneel. Het aantal tekens (minimum) waar de conversie toe moet leiden.
5.	Precisie	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”.