Joomla! Documentation™

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	Getal	Optioneel. Aantal decimale cijfers die getoond moeten worden bij floating-point getallen. Bij het gebruik van deze aanduiding in een string, fungeert het als een afkappunt, het maximum aantal tekens van de string.
6.	Type	Verplicht. Het type van het argument. Mogelijke types zijn:
		%	Een percentage teken. Geen argument vereist
		b	Het argument wordt behandeld als een integer en gepresenteerd als een binair getal.
		c	Het argument wordt behandeld als een integer en gepresenteerd als het teken met de ASCII-waarde.
		d	Het argument wordt behandeld als een integer en gepresenteerd als een decimaal getal met teken.
		e	Het argument wordt behandeld als de wetenschappelijke notatie (bijvoorbeeld 1.2e+2). De precisie specificatie staat voor het aantal cijfers na de decimale punt sinds PHP 5.2.1. In eerdere versies was het het aantal significante cijfers (een minder).
		u	Het argument wordt behandeld als een integer en gepresenteerd als decimaal getal zonder teken.
		f	Het argument wordt behandeld als een float en gepresenteerd als een floating-point getal (lokaal).
		F	Het argument wordt behandeld als een float en gepresenteerd als een floating-point getal (niet-lokaal).
		o	Het argument wordt behandeld als een integer en gepresenteerd als een octaal getal.
		s	Het argument wordt behandeld en gepresenteerd als een string.
		x	Het argument wordt behandeld als een integer en gepresenteerd als een hexadecimaal getal (met kleine letters).
		X	Het argument wordt behandeld als een integer en gepresenteerd als een hexadecimaal getal (met hoofdletters).

Opmaak argument verwisseling

De opmaak-string ondersteunt argument nummering en zelfs verwisseling. Dit is handig als twee of meer items opgenomen moeten worden in een string, maar door verschil in de taalstructuur betekent dat de volgorde van de het gebruik van de items niet hetzelfde is.

Stel bijvoorbeeld dat we de volgende code hebben:

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

met deze taalstring:

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

Dan als

$number = 3
$location = 'hat'

zou dit opleveren “There are 3 balls in the hat”. Maar stel dat u de vertaling wilt veranderen in:

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

Dan zou dit opleveren “The 3 contains hat balls” wat onzin is. Beter dan de code te veranderen, kunt u in de taalstring aangeven naar welk argument de plaatsvervanger verwijst. Verander de vertaling in:

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

en het resultaat wordt zoals verwacht “The hat contains 3 balls”.

Een extra voordeel van het kunnen nummeren van de argumenten is dat u de vervangers kunt herhalen zonder meer argumenten in de code toe te voegen. Verander de vertaling bijvoorbeeld in:

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

en dit zal het resultaat zijn “The hat contains 3 balls, so there are 3 balls in the hat”.