WordPress.org

Make WordPress Core

Opened 8 months ago

Last modified 8 months ago

#46305 new enhancement

Update emails w/ placeholders to use sprintf

Reported by: garrett-eclipse Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: I18N Keywords:
Focuses: coding-standards Cc:
PR Number:

Description

In #32263 several comments for 'Do not translate...' placeholders in email content were introduced. This has been the convention it seems throughout core.

This puts the onus on translators to read those comments as well as not accidentally change them or drop one of the surrounding # characters on many of them.

Can this simply be switched to sprintf functions with numeric placeholders and the translator comments be updated to indicate the placeholders. This seems a little nicer of an approach than simply saying don't do something and hoping for the best.

Here's all the instances I've found;
https://github.com/WordPress/WordPress/blob/56c162fbc9867f923862f64f1b4570d885f1ff03/wp-admin/ms-delete-site.php#L49-L67
https://github.com/WordPress/WordPress/blob/50ddffbac37fdae9298d1f11fe1dd7b8535fc839/wp-includes/user.php#L2015-L2029
https://github.com/WordPress/WordPress/blob/50ddffbac37fdae9298d1f11fe1dd7b8535fc839/wp-includes/user.php#L3036-L3052
https://github.com/WordPress/WordPress/blob/0b15142c0bb375fee19f9576356bf2aac2a56d2a/wp-includes/ms-functions.php#L1544-L1560
https://github.com/WordPress/WordPress/blob/0b15142c0bb375fee19f9576356bf2aac2a56d2a/wp-includes/ms-functions.php#L2275-L2289
https://github.com/WordPress/WordPress/blob/dcdfd7f412cb83f43116f6e37d7bfba4b4673cde/wp-admin/includes/file.php#L2204-L2218
https://github.com/WordPress/WordPress/blob/729c8e875fd84e29cb26103ee43eec7f67a61f6e/wp-admin/includes/misc.php#L1244-L1262
https://github.com/WordPress/WordPress/blob/c204ac4bc7972c9ca1e6b354ec8fb0851e255bc5/wp-includes/functions.php#L6473-L6486

Change History (3)

#1 @dd32
8 months ago

Something that's important to note, is that these strings are often manipulated through filters, either to remove placeholders, replace them with something else, or otherwise modify the content.

There are also a number of emails (not the ones shown here it seems) which are set through the network administration screens, so having these as placeholders is probably a bit simpler.

Although the onus is on Translators, translation tooling could possibly be a better place, for example, adding a GlotPress requirement that any placeholdery things ###[A-Z_]+### remain untranslated (I'm unsure if our GlotPress instance has a custom rule for that or not).

#2 @garrett-eclipse
8 months ago

Thanks @dd32

Correct me if I'm wrong but the approach I was thinking with sprintf should preserve the placeholders for the following filters and str_replace's that occur after the email_date/email_text string is created.

For example this string;
https://github.com/WordPress/WordPress/blob/c204ac4bc7972c9ca1e6b354ec8fb0851e255bc5/wp-includes/functions.php#L6473-L6486

Can be converted to sprintf as follows;

<?php
$email_text = sprintf(
        /* translators: 1: ###SITENAME###, 2: ###USER_EMAIL###, 3: ###DESCRIPTION###, 4: ###MANAGE_URL###, 5: ###SITEURL### */
        __(
                'Howdy,
A user data privacy request has been confirmed on%1$s:
User: %2$s
Request: %3$s
You can view and manage these data privacy requests here:
%4$s
Regards,
All at %1$s
%5$s'
        ),
        '###SITENAME###',
        '###USER_EMAIL###',
        '###DESCRIPTION###',
        '###MANAGE_URL###',
        '###SITEURL###'
);

This should leave the placeholders available in the string for filters, etc. While improving the translator experience as GlotPress already has a warning for placeholders missing;
Warning: Missing %1$s placeholder in translation.

That being said I understand the onus on rewriting these functions as the systems emails and others have followed this same convention. Irregardless if these emails change it would be a good call to implement a custom rule so I opened a #meta to prompt use of the gp_warning_placeholders_re filter to introduce a custom check on ###[A-Z_]+###.
Meta Ticket - https://meta.trac.wordpress.org/ticket/4196

#3 @dd32
8 months ago

Ah yes, that makes sense :) I put a warning into translate.wordpress.org either way.

Note: See TracTickets for help on using tickets.