Joomla! Documentation™

Sometimes it is necessary to include specially formatted fields within a string to be translated. This usually happens where numbers are involved but can occur for dates and times or when precise formatting instructions are required. If the strings were not to be translated the standard PHP functions printf and sprintf could be used. The printf function outputs a string formatted using embedded formatting instructions; the sprintf function returns a string formatted using the same embedded formatting instructions.

The JText class provides wrapper methods for the printf and sprintf functions allowing static text to be translated while also allowing formatted fields to be embedded using the same syntax as the PHP functions.

For example, suppose you have the string “Donations of 12.45 GBP have been received” where the amount comes from a variable, $donations”, say. You could split the string into two like this:

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

con cadenas de definición de idiomas

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

pero esto no funciona bien en los idiomas donde los datos insertados no están en un lugar similar en la cadena traducida. En su lugar utilice el método de "sprintf" de esta forma

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

con cadena de definición de idioma

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 )

con cadena de definición de idioma

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

Sintaxis de los especificadores de formato

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

Orden	Tipo	Valores	Descripción
1.	Símbolo	+ ó -	Opcional. Fuerza un símbolo (+ ó -) en un número. De forma predeterminada sólo se utiliza el símbolo - en un número si es negativo. Este especificador fuerza que los números positivos tengan el símbolo + también.
2.	Relleno	<space> o 0 <translate>or</translate> '<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.	Alineación	<null> <translate>or</translate> -	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.	Ancho	Número	Opcional. Número de caracteres (como mínimo) que deben resultar de la conversión.
5.	Precisión	Número	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.	Tipo	Obligatorio. El tipo de los datos argumento. Los tipos posibles son:
		%	Un carácter de porcentaje literal. No requiere argumento
		b	El argumento se trata como un entero y se presenta como un número binario.
		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.

Por ejemplo, supongamos que tenemos el siguiente código:

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

con esta traducción de la cadena de idioma

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”.