When to use __() and esc_html_e?

Question

Can anyone explain why I would use __() over esc_html_e()?

Answer 1

__() is primarily for simple text that doesn't contain markup that needs to be escaped. It differs from _e() in that the former returns the translated text while the latter echoes the translated text.

esc_html_e() and esc_html__() are similar, but they are used for strings that do contain markup. They each escape the provided string, and then call on their corresponding _e() or __() counterparts depending on which one you use.

Escaping HTML is necessary if you're accepting strings provided from user input. XSS attacks are probably the most common types of attacks on sites that accept user input and render it on the page. An attacker can easily provide <script> tags and execute arbitrary Javascript on your page if the input is not properly cleaned or escaped.

Answer 2

Just like the docs state, esc_html_e() retrieves a translated string, escapes it, and echoes the result. __() returns a translated string. The source for each of these functions makes this crystal clear:

function __( $text, $domain = 'default' ) {
    return translate( $text, $domain );
}

function esc_html_e( $text, $domain = 'default' ) {
    echo esc_html( translate( $text, $domain ) );
}