Convert 'Sample Page', 'Hello World', and 'Privacy Policy' to block content

[danielbachhuber]

As a WordPress user, I'd expect that 'Sample Page', 'Hello World', and 'Privacy Policy' would work natively within the new editor. They're classic content right now, so let's make sure they're block content upon installation.

[desrosj]

45151.diff​ converts the Hello World post and Sample Page page to use the new block format. ThePrivacy Policy page needs a bit more thought, though.

The same function used to create the default Privacy Policy page is used to display the Privacy Policy Guide (site.com/wp-admin/tools.php?wp-privacy-policy-guide), which is not an editor page.

Looking into that now.

[desrosj]

45151.2.diff​ adds updates to the Privacy Policy default content function to output both a block editor formatted string and regular HTML formatted string.

It's a bit of a rewrite for the get_default_content() method, so open to other suggestions. Short of a rewrite, there would have been a lot more conditional statements and repetition added.

[garrett-eclipse]

Thanks @desrosj I haven't plugged this in for testing but from an initial code review;

• In your docblock for $blocks please provide the 'Default true.'
• Should we add a 'wp_get_default_privacy_policy_strings' filter for the array before the foreach so plugins/devs can manipulate the strings array adding additional headings and paragraphs without needing to think about the Block Editor formatting?
• If we do add a filter to the strings array should we make it a dictionary with keys so plugins can manipulate specific sections like 'Comments' more easily?
• Should the h2 replace set a level of 2 for the gutenberg markup?

[dimadin]

It should be noted that the content of example page was all in one string. This allowed customization of that text in translations, not literal translation, so you could have different text. Breaking it in paragraphs would limit l10n.

I don't know about other locales, but I have different examples in Serbian translation.

Can we detect paragraphs in string and then add block comments?

[desrosj]

45151.3.diff​ adds Default true to the function.

I think that adding a new filter should be explored in a new ticket. My goal here is to change the function only enough to achieve the goal of returning Privacy Policy starter content for both the block-based editor and the Privacy Policy Guide.

Should the h2 replace set a level of 2 for the gutenberg markup?

The default level for the heading block is 2, so we don't have to specify a level on <h2>s.

@dimadin If I am understanding correctly (which I may not be), you are asking for the privacy policy to be one translatable string. If so, that should be explored in a new ticket.

The privacy policy strings are currently split up into one string for each paragraph. This patch should maintain the existing behavior. The resulting single, combined string can still be filtered using the wp_get_default_privacy_policy_content filter.

[dimadin]

Replying to desrosj:

@dimadin If I am understanding correctly (which I may not be), you are asking for the privacy policy to be one translatable string.

No, I said that the text of "Sample Page" was one string. Your patches change that behavior so that one string is broken into few separate ones.

[desrosj]

Ah! Sorry about that, I misread. The sample page should still be one string. The only difference should be that the Block Editor HTML comments will now be included.

[SergeyBiryukov]

In 43820:

Upgrade/Install: Convert Sample Page, Hello World, and Privacy Policy to block content.

Props desrosj, garrett-eclipse, danielbachhuber.
Fixes #45151.

[SergeyBiryukov]

Reopening for trunk.

[dimadin]

@desrosj Sorry, it might be that it was late evening here and I was tired, but somehow I saw as if "Sample Page" string was split into multiple strings in your patches.

@SergeyBiryukov Should we inform translators about this change so that they know what is purpose of these HTML comments and that text copy wasn't changed so that they can use previous strings as a base?

[SergeyBiryukov]

Replying to dimadin:

Should we inform translators about this change so that they know what is purpose of these HTML comments and that text copy wasn't changed so that they can use previous strings as a base?

Good idea, I'll post on make/polyglots shortly.

[desrosj]

I am thinking that we can do better for the Sample Page content.

The current solution can remain for the beta and will ensure that a new install will have the correct sample content, but it will not result in ideal strings for translators.

After [43820], the string for translation would be:

<!-- wp:paragraph -->
<p>This is an example page. It's different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:</p>
<!-- /wp:paragraph -->

<!-- wp:quote -->
<blockquote class="wp-block-quote">
<p>Hi there! I'm a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like pi&#241;a coladas. (And gettin' caught in the rain.)</p>
</blockquote>
<!-- /wp:quote -- >

Trusting the markup to be preserved in translations is not a good idea, especially with more complex HTML comments.

I am proposing that we use numbered placeholder replacements containing the HTML comment and HTML tag to make translating these strings easier.

Patch incoming.

[desrosj]

45151.4.diff​ changes the translatable sample page content to not include the block editor markup. I don't feel strongly about the wording in the translator comments. @SergeyBiryukov feel free to change those to what you feel works best.

I am thinking that using printf() and sprintf() to insert block markup is going to become more and more common. Should we open a new ticket to discuss a best practice and document somewhere?

[SergeyBiryukov]

Replying to desrosj:

45151.4.diff​ changes the translatable sample page content to not include the block editor markup.

Looks good, could we also remove the markup from the "Hello world" post content?

I am thinking that using printf() and sprintf() to insert block markup is going to become more and more common. Should we open a new ticket to discuss a best practice and document somewhere?

I think it's addressed by "Do not put unnecessary HTML markup into the translated string" from ​i18n best practices, maybe additional examples would be helpful though?

[desrosj]

I can update the patch tomorrow.

I think it's addressed by "Do not put unnecessary HTML markup into the translated string" from i18n best practices, maybe additional examples would be helpful though?

Yes, maybe add something like "this includes block editor markup", or an example detailing inserting block comments with placeholders.

[garrett-eclipse]

Thanks @desrosj for starting this. I wonder if we've approached this from the wrong direction.

Prior to your changes the starter content they were within single translation functions __() using character returns instead of paragraph markup;
Welcome - ​https://github.com/WordPress/WordPress/blob/4.9.8/wp-admin/includes/upgrade.php#L174
First Page - ​https://github.com/WordPress/WordPress/blob/4.9.8/wp-admin/includes/upgrade.php#L224-L232

This contained no markup aside from links and it would be nice to leave it untouched for translators so they don't need to retranslate the string or worry about block markup.

Instead, maybe we can introduce the block markup after the initial string setup, either adding a new function to wpautop to enrich the string to block format or as a custom function run on the string to convert to block type if in the Block Editor (maybe allow Classic Editor to avoid running it).

This should remove any new markup from the strings and avoid any need for new translations as they already exist. It would also avoid translators breaking the markup accidentally.

I am not versed well enough in Gutenberg but I heard there was a process for converting classic posts to the block editor. Maybe this process or the logic there-in can be used for the default content??

If we can introduce the block markup after the string is defined we don't introduce new strings that contain markup which in my eyes would be a win.

Thank you

[swissspidy]

Having dozens of placeholders like that in a translatable string is way worse for translators than HTML comments. It's very error prone.

The approach outlined by @garrett-eclipse sounds interesting. We could give that a try.

Otherwise we should think about not putting the whole content into one translatable string but split it up. Then the HTML comments and tags don't need to be part of the translatable string.

[garrett-eclipse]

Thanks @swissspidy

Replying to swissspidy:

Otherwise we should think about not putting the whole content into one translatable string but split it up. Then the HTML comments and tags don't need to be part of the translatable string.

Concerning splitting up the strings it was flagged by @dimadin that 'breaking it in paragraphs would limit i10n as you wouldn't be able to change the flow of the entire message once it's broken into paragraphs. His note;

Replying to dimadin:

It should be noted that the content of example page was all in one string. This allowed customization of that text in translations, not literal translation, so you could have different text. Breaking it in paragraphs would limit l10n.

I don't know about other locales, but I have different examples in Serbian translation.

Can we detect paragraphs in string and then add block comments?

His concern was my main edge case I was considering when thinking we need to inject the tags after the string is setup. I'll connect with @desrosj and see if we can compile an attempt heading in that direction.

Cheers

[mnelson4]

Regarding putting the entire page into a single translated string, that seems to contradict "Best Practices for writing strings":

Split at paragraphs – merge related sentences, but do not include a whole page of text in one string.

see ​https://developer.wordpress.org/themes/functionality/internationalization/#best-practices-for-writing-strings

If that's wrong, and it's better to translate the entire page in one string, that documentation could definitely be improved.

[swissspidy]

If that's wrong, and it's better to translate the entire page in one string, that documentation could definitely be improved.

No, it's accurate. One entire string is really hard for users to translate and should be avoided. The cost of not having the flexibility to move around sections is negligible compared to that.

[dd32]

45151.6.diff​ is splitting the HTML out of the Sample Page and Hello World post strings, leaving pure translatable text (aside from the included link).

While having a generic "Convert this plain-HTML chunk to Block HTML" would be useful for these cases, the simplicity of these two cases doesn't really require it.

[ocean90]

Thanks @dd32. In 45151.7.diff​ I added "first page/post content" as translator comments for clarity.

[desrosj]

Ran 45151.7.diff​ through some testing and everything works great for me. 45151.8.diff​ adds translator comments to the privacy policy strings.

[pento]

In 43912:

Upgrade/Install: Split Sample Page, Hello World, and Privacy Policy content.

[43820] converted the content to blocks, but included block markers in the translateable strings, which made translations difficult to do accurately.

Props desrosj, dd32, ocean90.
See #45151.

[pento]

In 44168:

Upgrade/Install: Convert Sample Page, Hello World, and Privacy Policy to block content.

Merges [43820,43912] from the 5.0 branch to trunk.

Props desrosj, garrett-eclipse, danielbachhuber, dd32, ocean90.
Fixes #45151.

[garrett-eclipse]

Related - #48279