WordPress.org

Make WordPress Core

Opened 12 months ago

Closed 10 months ago

Last modified 9 days ago

#45151 closed enhancement (fixed)

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

Reported by: danielbachhuber Owned by: desrosj
Milestone: 5.0 Priority: normal
Severity: normal Version:
Component: Upgrade/Install Keywords: i18n-change has-patch commit fixed-5.0
Focuses: Cc:
PR Number:

Description

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.

Attachments (8)

45151.diff (3.6 KB) - added by desrosj 12 months ago.
45151.2.diff (38.6 KB) - added by desrosj 12 months ago.
45151.3.diff (38.6 KB) - added by desrosj 12 months ago.
45151.4.diff (3.1 KB) - added by desrosj 12 months ago.
45151.5.diff (4.4 KB) - added by desrosj 12 months ago.
45151.6.diff (6.4 KB) - added by dd32 11 months ago.
45151.7.diff (4.8 KB) - added by ocean90 11 months ago.
45151.8.diff (21.9 KB) - added by desrosj 11 months ago.

Download all attachments as: .zip

Change History (49)

#1 @earnjam
12 months ago

  • Owner set to desrosj
  • Status changed from new to assigned

@desrosj
12 months ago

#2 @desrosj
12 months ago

  • Keywords has-patch needs-refresh added; needs-patch removed

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.

This ticket was mentioned in Slack in #core-privacy by garrett-eclipse. View the logs.


12 months ago

@desrosj
12 months ago

#4 @desrosj
12 months ago

  • Keywords needs-testing 2nd-opinion added; needs-refresh removed

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.

Last edited 12 months ago by desrosj (previous) (diff)

This ticket was mentioned in Slack in #core-privacy by desrosj. View the logs.


12 months ago

#6 @garrett-eclipse
12 months ago

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?

#7 follow-up: @dimadin
12 months ago

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
12 months ago

#8 follow-up: @desrosj
12 months ago

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.

#9 in reply to: ↑ 8 @dimadin
12 months ago

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.

#10 @desrosj
12 months ago

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.

#11 @SergeyBiryukov
12 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 43820:

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

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

#12 @SergeyBiryukov
12 months ago

  • Keywords fixed-5.0 added
  • Resolution fixed deleted
  • Status changed from closed to reopened

Reopening for trunk.

#13 follow-up: @dimadin
12 months ago

@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?

#14 in reply to: ↑ 13 @SergeyBiryukov
12 months ago

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.

#15 @desrosj
12 months ago

  • Keywords needs-refresh added; needs-testing 2nd-opinion removed

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.

#16 @SergeyBiryukov
12 months ago

  • Keywords fixed-5.0 removed

@desrosj
12 months ago

#17 follow-up: @desrosj
12 months ago

  • Keywords needs-refresh removed

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?

#18 in reply to: ↑ 17 @SergeyBiryukov
12 months ago

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?

#19 @desrosj
12 months ago

  • Keywords needs-refresh added

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.

This ticket was mentioned in Slack in #polyglots by ocean90. View the logs.


12 months ago

@desrosj
12 months ago

#21 @desrosj
12 months ago

  • Keywords needs-refresh removed

#22 @garrett-eclipse
12 months ago

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

This ticket was mentioned in Slack in #core-i18n by mnelson4. View the logs.


12 months ago

#24 @swissspidy
12 months ago

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.

#25 in reply to: ↑ 7 @garrett-eclipse
12 months ago

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

This ticket was mentioned in Slack in #docs by mnelson4. View the logs.


12 months ago

This ticket was mentioned in Slack in #docs by mnelson4. View the logs.


12 months ago

#28 @mnelson4
12 months ago

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.

#29 @swissspidy
12 months ago

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.

#30 @desrosj
12 months ago

  • Keywords needs-patch added; has-patch removed

This ticket was mentioned in Slack in #core-privacy by desrosj. View the logs.


12 months ago

@dd32
11 months ago

#32 @dd32
11 months ago

  • Keywords i18n-change has-patch added; needs-patch removed

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
11 months ago

#33 @ocean90
11 months ago

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

This ticket was mentioned in Slack in #core-privacy by desrosj. View the logs.


11 months ago

@desrosj
11 months ago

#35 @desrosj
11 months ago

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

#36 @ocean90
11 months ago

  • Keywords commit added

#37 @pento
11 months ago

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.

#38 @pento
11 months ago

  • Keywords fixed-5.0 added

#39 @pento
10 months ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

This ticket was mentioned in Slack in #core-editor by joyously. View the logs.


9 days ago

Note: See TracTickets for help on using tickets.