Font Library: Ensure name/description are localized

[swissspidy]

Changes the data format as per the suggestion on the ticket.

In practice not really a fan of using _doing_it_wrong() everywhere instead of using proper exceptions, but alas.

Trac ticket: https://core.trac.wordpress.org/ticket/60509

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props swissspidy, mmaattiiaass, grantmkin, youknowriad.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[swissspidy]

cc @matiasbenedetto

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[matiasbenedetto]

Noting that after this PR lands we need to update the font-collection JSON schema: https://github.com/WordPress/gutenberg/blob/trunk/schemas/json/font-collection.json

[swissspidy]

Noting that after this PR lands we need to update the font-collection JSON schema: WordPress/gutenberg@trunk/schemas/json/font-collection.json

Speaking of schema, the code references https://schemas.wp.org/trunk/font-collection.json but that doesn't actually exist yet.

[creativecoder]

Speaking of schema, the code references https://schemas.wp.org/trunk/font-collection.json but that doesn't actually exist yet.

The schema is present at https://github.com/WordPress/gutenberg/blob/trunk/schemas/json/font-collection.json, but it seems the redirect isn't working correctly for that one. Both block.json and theme.json schemas redirect from schemas.wp.org/* to raw.githubusercontent.com/WordPress/gutenberg/*

[creativecoder]

Given how this is evolving, potentially trimming down the collection json file to only contain font_families, I wonder if it makes sense to have font_families as a separate parameter:

wp_register_font_collection( $slug, $font_families, $args ), where $font_families is an array of font families, or a path/url to a json file. The main benefit I see is that it helps highlight that defining the font_families is the most important part of the collection data, and makes it more visible that there are 2 possible formats (PHP array or json) with it not nested next to the other collection info.

[youknowriad]

wp_register_font_collection( $slug, $font_families, $args ), where $font_families is an array of font families, or a path/url to a json file. The main benefit I see is that it helps highlight that defining the font_families is the most important part of the collection data, and makes it more visible that there are 2 possible formats (PHP array or json) with it not nested next to the other collection info.

Personally, I think we should stick with wp_register_font_collection( $slug, $args ) for consistency with all the registration APIs in core. I don't mind if the font_families key is either a url or a static collection.

[swissspidy]

So, who can help update the JSON file, the schema, and fix the schema redirect?

[matiasbenedetto]

So, who can help update the JSON file, the schema, and fix the schema redirect?

I requested the schema redirect here: https://meta.trac.wordpress.org/ticket/7476#ticket

[matiasbenedetto]

Personally, I think we should stick with wp_register_font_collection( $slug, $args ) for consistency with all the registration APIs in core. I don't mind if the font_families key is either a url or a static collection.

OK, so the signature of the function will be like this, right?

wp_register_font_collection(
  $slug: string,
  $data: array<{
     name: string,
     description?: string,
     font_families: array|string,
     categories?: array
 }>

Both of these use cases will be allowed.

1. Provide the font families as a JSON file URL or path.

$categories = array(
    array(
        "name" => __( 'Sans Serif' ),
        "slug" => "sans-serif"
    ),
);

wp_register_font_collection(
	'google-fonts',
	array(
		'font_families'         => 'https://s.w.org/images/fonts/17.7/collections/google-fonts-with-preview.json',
		'name'        => __( 'Google Fonts' ),
		'description' => __( 'Install from Google Fonts. Fonts are copied to and served from your site.' ),
		'categories'  => $categories,
	)
);

2. Provide font families as a PHP array:

$ubuntu = array(
    'fontFamily' => 'Ubuntu, system-ui',
    'name'        => 'Ubuntu',
    'slug'          => 'ubuntu',
);

wp_register_font_collection(
	'my-collection',
	array(
		'name' => __( 'My Collection' ),
		'description' => __( 'My custom fonts collection.' ),
		'categories' => $categories,
		'font_families' => [ $ubuntu ],
	)
);

[matiasbenedetto]

So, who can help update the JSON file, the schema, and fix the schema redirect?

@swissspidy you can find an updated version of the file in this PR: WordPress/google-fonts-to-wordpress-collection#21. To test, these changes, you are able to link the PR version of that JSON file https://raw.githubusercontent.com/WordPress/google-fonts-to-wordpress-collection/e9037d48ec56988dbaa7036186619415ef6761f7/releases/core-6.5.beta/google-fonts-with-preview.json.

[swissspidy]

Thanks for the help!

The signature

wp_register_font_collection(
  $slug: string,
  $data: array<{
     name: string,
     description?: string,
     font_families: array|string,
     categories?: array
 }>

sounds good to me 👍

I just updated the PR accordingly.

It uses https://raw.githubusercontent.com/WordPress/google-fonts-to-wordpress-collection/e9037d48ec56988dbaa7036186619415ef6761f7/releases/core-6.5.beta/google-fonts-with-preview.json for testing, but since the data structure is still the same as https://s.w.org/images/fonts/17.7/collections/google-fonts-with-preview.json, just with fewer keys, I should be able to just change it back with no issues. So nicely backward compatible.

[swissspidy]

@matiasbenedetto @youknowriad @creativecoder I think this is now ready

[matiasbenedetto]

This is testing well on my end.
My tests consisted in adding font collections in both ways as described here:
#6130 (comment)

✔️ Both worked as expected.
✔️ No extra properties apart from font_families were loaded from the JSON
✔️ If a font collection doesn't have font_families set, a warning is raised.

Thanks, @swissspidy, for working on this.

I think it's ready to be merged.
cc. @youknowriad

[youknowriad]

Once this is committed, let's also make sure to synchronize the Gutenberg plugin properly. Thanks all for addressing this one.

[swissspidy]

Committed in https://core.trac.wordpress.org/changeset/57686

[matiasbenedetto]

Porting the changes from this PR to Gutenberg: WordPress/gutenberg#59256