Thoughts on Localizing and Escaping a string with HTML

So, let’s say my WordPress extension needs to generate a string like this 300 × 400px. I would probably choose to use the following html markup:

300 &#215; 400<abbr title="pixels">px</abbr>

Simple enough, but I would also like this string to be properly escaped and localized. In my current state of thinking, localization presents a new form of input. As any security-concious developer knows, all input must be escaped before sending it to it’s destination and translated text is no different. My first attempt at this (coded a few months ago) looked a bit like this:

function my_extension_format_dimensions_pixels( $width, $height ) {
	return sprintf( __( '%1$d &#215; %2$d<abbr title="pixels">px</abbr>', 'my_extension' ), $width, $height );
}

While this appears to work, I don’t feel that it fully meets the requirements stated above. Basically, it is not properly escaped. While I’m pretty new to localization in WordPress, I’ve been making it a point to enable my extensions to be translate in other languages. Situations like this present a bit of a headache for me though. The string has so many different parts to it. The presence of an html tag with an attribute as well as 2 numbers makes the above solution a bit short-sighted. I’m going to try to illustrate the steps that I would take to correct it and hopefully someone with more knowledge can tell me if I’m doing it wrong.

The first and probably easiest thing would be to deal with the numbers. I recently discovered the number_format_i18n() function while reading through trac. This function will convert a given integer to the format specified by the user-defined locale.

function my_extension_format_dimensions_pixels( $width, $height ) {
	return sprintf( __( '%1$s &#215; %2$s<abbr title="pixels">px</abbr>', 'my_extension' ), number_format_i18n( $width ), number_format_i18n( $height ) );
}

Here, I’ve filtered the values of $width and $height using number_format_i18n() as well as updated the placeholders to output strings. number_format_i18n() outputs a string and converting this to a decimal would probably be a bad idea.

If there were no html present in this string, I would probably just call it done and move onto the next task, but there is an html tag with an attribute and I’m starting to get confused.

I’m aware that WordPress provides a few convienient functions that will escape and translate data simultaneously. Normally, I would just filter this string through esc_html__() and all would be good, but since the string contains html, this is not really an option and here’s the proof:

$tests = array(
	'This is just a normal string',
	'This string has a special char in decimal notation: ×',
	'This string has <abbr title="Hypertext Markup Language">html</abbr>.'
	);
foreach ( $tests as $test ) {
	print '<br>' . esc_html__( $test );
}

If you run this code on a WordPress installation, you will notice that $test[0] and $test[1] display unchanged while $test[2] is ran through something similar to htmlentities(). This is precicely what I believe that esc_html__() should be doing. IMO it is meant to be used to prepare text to be used in html and not as html.

It appears at this stage that there is no super-easy way to do this. In my mind it may be a good solution to break the string into parts so that each part can be filtered properly. Here’s what I have for the next step:

function my_extension_format_dimensions_pixels( $width, $height ) {
	$tag = '<abbr title="' . esc_attr__( 'pixels', 'my_extension' ) . '">' . esc_html__( 'px', 'my_extension' ) . '</abbr>';
	return sprintf( __( '%1$s &#215; %2$s%3$s', 'my_extension' ), number_format_i18n( $width ), number_format_i18n( $height ), $tag );
}

I’ve moved the entire html tag outside of the translateable string and am filtering both the tag’s title attribute and contents with appropriate functions. Just to see what would happen, I decided to try esc_html__() instead of __() to escape the entire string and to my suprise, it actually worked without creating entities for the abbr tag.

function my_extension_format_dimensions_pixels( $width, $height ) {
	$tag = '<abbr title="' . esc_attr__( 'pixels', 'my_extension' ) . '">' . esc_html__( 'px', 'my_extension' ) . '</abbr>';
	return sprintf( esc_html__( '%1$s &#215; %2$s%3$s', 'my_extension' ), number_format_i18n( $width ), number_format_i18n( $height ), $tag );
}

This seems to work rather well at the moment but the question still remains…

Am I doing it wrong?

…and if so, what is the best method of approaching such a string. Strings like this present themselves quite a bit in my development. While I can sometimes work around them by deleting html from the strings, this is not always an option. Please let me know your thoughts, I want to get this stuff right and hopefully this post can help others too.