Writing translatable PHP functions for WordPress

Excerpt from the WordPress developer manual:

Under Escaping Output is the safeguarding of output data by removing unwanted data/characters, such as incorrect HTML or script tags. This mechanism helps to ensure that the data is secured for the end user before rendering.

WordPress contains numerous help functions that you can use for the most common scenarios.

Pay close attention to what each function does, as some remove HTML while others allow it. You should use the most appropriate function for the content and context you want to output. The escape function should always be used during the output (php echo), not before.

Escaping functions at a glance

esc_attr()

Is used for everything else that is output in the attribute of an HTML element.

esc_html()

Is always used when an HTML element includes a section with data that is displayed (removes html).

esc_js()

To be used for inline javascript.

esc_textarea()

For encoding text for use in a textarea element.

esc_url()

Used for all URLs, including those in the src and href attributes of an HTML element.

esc_url_raw()

Used when a URL is stored in the database or in other cases where unencoded URLs are required.

wp_kses()

Use for all untrusted HTML elements (post text, comment text, etc.)

wp_kses_post()

Alternative version of wp_kses() that automatically allows all HTML content that is allowed in posts.

wp_kses_data()

Alternative version of wp_kses(), which only allows the HTML code permitted in post comments.

Ensure multilingualism when escaping

If the output is carried out as in the following example, we ensure that

1. The sentences remain intact (no sentence breaks).
2. correct separation is ensured.
3. the option of arranging contact and e-mail links (or something similar) differently within the translated sentence.

// Example url (could have come from an insecure user input via a form, for example).
$contact_url = 'https://www.example.com/contact/';
// escaping $contact_url
$contact_url = esc_url( $contact_url );

// Example e-mail address (could have come from an insecure user input via a form, for example).
$contact_email = 'info@mydomain.com';
// escaping, sanitizing & hiding of $contact_email.
// Yes, you should still sanitize and escape the email address even if you use the antispambot() function
$contact_email = esc_url( sprintf( 'mailto:%s', antispambot( sanitize_email( $contact_email ) ) ), array( 'mailto' ) );

esc_html_e( 'Dear guest, we were unable to find any details regarding your request.', 'text-domain' );
echo "<br><br>";

printf(
    esc_html__( 'Please contact us through our %1$s or via %2$s.', 'text-domain' ),
    sprintf(
        '<a href="/en/%s/">%s</a>',
        $contact_url,
        esc_html__( 'Contact Page', 'text-domain' )
        ),
    sprintf(
        '<a href="/en/%s/">%s</a>',
        $contact_email,
        esc_html__( 'Email', 'text-domain' )
        )
    );

This gives the translator two complete sentences and two individual words to translate. A translator therefore only has to take care of the following simple lines (while the CODE takes care of the rest):

esc_html_e( 'Dear guest, we were unable to find any details regarding your request.', 'text-domain' );
// ...
esc_html__( 'Please contact us through our %1$s or via %2$s', 'text-domain' )
// ...
esc_html__( 'Contact Page', 'text-domain' )
// ...
esc_html__( 'Email', 'text-domain' )

Further information can be found here: Multilingualism for WordPress themes (eng) and Multilingualism for plugins (eng)

If you have any questions, please feel free to use the comment function at the bottom of this page.