Skip to content

548 adjust applicability keyphrase density and distribution#22343

Merged
JorPV merged 36 commits intofeature/off-the-bat-analysisfrom
548-adjust-applicability-keyphrase-density-and-distribution
Sep 25, 2025
Merged

548 adjust applicability keyphrase density and distribution#22343
JorPV merged 36 commits intofeature/off-the-bat-analysisfrom
548-adjust-applicability-keyphrase-density-and-distribution

Conversation

@hannaw93
Copy link
Copy Markdown
Contributor

@hannaw93 hannaw93 commented Jun 11, 2025

Context

  • We want to remove the guard on the keyphrase density assessment, keyphrase distribution assessment, and keyphrase in subheadings assessment to show them even when there is no content added. This better shows our content analysis capabilities off the bat.

Summary

This PR can be summarized in the following changelog entry:

  • Makes the keyphrase density assessment and keyphrase in subheadings assessment available when no content has been added.
  • [shopify-seo] Makes the keyphrase density assessment and keyphrase in subheadings assessment available when no content has been added.
  • [yoast-doc-extension] Makes the keyphrase density assessment, keyphrase distribution assessment, and keyphrase in subheadings assessment available when no content has been added.
  • [yoastseo] Makes the keyphrase density, keyphrase distribution, and keyphrase in subheadings assessments available when no content has been added.
  • [yoastseo] Replaces the feedback string and score for when there is no keyphrase in the text for keyphrase distribution assessment.

Relevant technical choices:

  • For all 3 assessments we added a new condition that covers the case when no keyphrase was set and/or no text was added.

  • They keyphrase distribution had a feedback string set for when there is a keyphrase set, but it's not in the text ( Include your keyphrase or its synonyms in the text so that we can check keyphrase ). For efficiency, we removed that string and made sure our new string is used for that condition. The reason for that is the following:

    • Keeping the old consideration condition would lead to separate feedback for a text with a set keyphrase that's not in the text, and a separate feedback for a text with a keyphrase that was not set. That didn't seem valuable when the new feedback string (Please add both a keyphrase and some text containing the keyphrase or its synonyms) can cover both of these cases.
  • The choices of feedback strings are explained here.

Test instructions

Test instructions for the acceptance test before the PR gets merged

This PR can be acceptance tested by following these steps:

WordPress: Regular content

  • Install and activate Yoast SEO
  • Execute the following scenarios in non-Japanese language, e.g. English
Testing keyphrase density
  • Open a new (empty) post/page
  • Confirm that you see the keyphrase density assessment is shown with the following feedback: 🔴 Keyphrase density: Please add both a keyphrase and some text containing the keyphrase.
    • This is a new feedback string
  • Hover over the assessment title and confirm that you see "https://yoa.st/33v" (Shopify: "https://yoa.st/shopify12") along with other parameters in the bottom left corner of the window
  • Hover over the assessment call to action and confirm that you see "https://yoa.st/33w" (Shopify: "https://yoa.st/shopify13") along with other parameters in the bottom left corner of the window
  • Make sure both links lead to this page when clicked. Also confirm that the page is opened in a new window
  • Switch on cornerstone content and confirm that the bullet stays red. Switch it back to non-cornerstone content. (not relevant for Google docs)
  • Add a text to the post.
  • Make sure the feedback for the keyphrase density assessment does not change after adding text.
  • Add a keyphrase that is not part of the text to the keyphrase field.
  • Make sure the feedback string changes to 🔴 The keyphrase was found 0 times. That's less than the recommended minimum of 2 times for a text of this length. Focus on your keyphrase! .
  • Remove the keyphrase from the keyphrase field.
  • Confirm that the feedback changes back to 🔴 Keyphrase density: Please add both a keyphrase and some text containing the keyphrase.
Testing keyphrase distribution
  • Activate the Premium plugin.
  • Open a new (empty) post/page.
  • Confirm that you don't see the following feedback for Keyphrase distribution: Keyphrase distribution: Include your keyphrase or its synonyms in the text so that we can check keyphrase distribution.
    • This string is removed in this PR
  • Confirm that you see the keyphrase distribution assessment is shown with the following feedback: 🔴 Keyphrase distribution: Please add both a keyphrase and some text containing the keyphrase or its synonyms.
    • This is a new feedback string
  • Hover over the assessment title and confirm that you see "https://yoa.st/33q" (Shopify: "https://yoa.st/shopify30") along with other parameters in the bottom left corner of the window
  • Hover over the assessment call to action and confirm that you see "https://yoa.st/33u" (Shopify: "https://yoa.st/shopify31") along with other parameters in the bottom left corner of the window
  • Make sure both links lead to this page when clicked. Also confirm that the page is opened in a new window
  • Switch on cornerstone content and confirm that the bullet stays red. Switch it back to non-cornerstone content.
  • Add a long (above 300 words) text to the post. (The length is important to define what we expect at the last step of these instructions, where you add the keyphrase to the text)
  • Make sure the feedback for the keyphrase distribution assessment does not change after adding text.
  • Add a keyphrase that is not part of the text to the keyphrase field.
  • Make sure the feedback the keyphrase distribution assessment does not change after adding the text and a keyphrase that is not in the text.
  • Add an instance of the keyphrase to the text.
  • Confirm that the feedback changes to 🔴 Keyphrase distribution: Very uneven. Large parts of your text do not contain the keyphrase or its synonyms. Distribute them more evenly.
Testing keyphrase in subheading
  • Open a new (empty) post/page.
  • Confirm that you see the keyphrase in subheadings assessment is shown with the following feedback: 🔴 Keyphrase in subheading: Please add both a keyphrase and some text to receive relevant feedback.
    • This is a new feedback string
  • Hover over the assessment title and confirm that you see "https://yoa.st/33m" (Shopify: "https://yoa.st/shopify16") along with other parameters in the bottom left corner of the window
  • Hover over the assessment call to action and confirm that you see "https://yoa.st/33n" (Shopify: "https://yoa.st/shopify17") along with other parameters in the bottom left corner of the window
  • Make sure both links lead to this page when clicked. Also confirm that the page is opened in a new window
  • Add a short paragraph containing between 250-300 words (in Japanese: between 500-600 characters)
  • Set the focus keyphrase
  • Make sure the feedback for the keyphrase in subheading changes to 🟢 Keyphrase in subheading: You are not using any higher-level subheadings containing the keyphrase or its synonyms, but your text is short enough and probably doesn't need them.
  • Hover over the assessment title and confirm that you see "https://yoa.st/33m" (Shopify: "https://yoa.st/shopify16") along with other parameters in the bottom left corner of the window
  • Switch on the cornerstone content toggle
  • Confirm that the feedback changes to: 🔴 Keyphrase in subheading: You are not using any higher-level subheadings containing the keyphrase or its synonyms. Fix that!
  • Shorten the text so that now it contains less than 250 words (in Japanese: 500 characters)
  • Confirm that the feedback changes to: 🟢 Keyphrase in subheading: You are not using any higher-level subheadings containing the keyphrase or its synonyms, but your text is short enough and probably doesn't need them.
  • Switch off the cornerstone content toggle
  • Turn the short text into a long text by making sure it's above 300 words (in Japanese: 600 characters)
  • Make sure the feedback the keyphrase in subheadings assessment changes to 🔴 Keyphrase in subheading: You are not using any higher-level subheadings containing the keyphrase or its synonyms. Fix that!
  • Hover over the assessment title and confirm that you see "https://yoa.st/33m" (Shopify: "https://yoa.st/shopify16") along with other parameters in the bottom left corner of the window
  • Hover over the assessment call to action and confirm that you see "https://yoa.st/33n" (Shopify: "https://yoa.st/shopify17") along with other parameters in the bottom left corner of the window
Test in Japanese
  • Switch your site language to Japanese and repeat the steps above
  • Confirm that you get the same results
    Note for developers: You can test with the site language set to Japanese and and the user profile language to English if you want your site interface shown in English instead of Japanese.

WooCommerce products

  • Install and activate WooCommerce Yoast SEO
    • If you're building the plugin, please link the Free branch (see this page on how to do it)
  • Create a product
  • Execute the testing steps in WordPress: Regular content scenario
  • Confirm that you get the same results

Shopify

  • Install and activate Yoast SEO for Shopify
  • Create a product
  • Execute the testing steps in WordPress: Regular content scenario
  • Confirm that you get the same results

Google docs extension

  • Create a Google doc and build the app
  • Execute the testing steps in WordPress: Regular content scenario
    • Skip the steps for testing cornerstone content
  • Confirm that you get the same results

Relevant test scenarios

  • Changes should be tested with the browser console open
  • Changes should be tested on different posts/pages/taxonomies/custom post types/custom taxonomies
  • Changes should be tested on different editors (Default Block/Gutenberg/Classic/Elementor/other)
  • Changes should be tested on different browsers
  • Changes should be tested on multisite

Test instructions for QA when the code is in the RC

  • QA should use the same steps as above.

QA can test this PR by following these steps:

Impact check

This PR affects the following parts of the plugin, which may require extra testing:

  • N/A

UI changes

  • This PR changes the UI in the plugin. I have added the 'UI change' label to this PR.

Other environments

  • This PR also affects Shopify. I have added a changelog entry starting with [shopify-seo], added test instructions for Shopify and attached the Shopify label to this PR.

Documentation

  • I have written documentation for this change. For example, comments in the Relevant technical choices, comments in the code, documentation on Confluence / shared Google Drive / Yoast developer portal, or other.

Quality assurance

  • I have tested this code to the best of my abilities.
  • During testing, I had activated all plugins that Yoast SEO provides integrations for.
  • I have added unit tests to verify the code works as intended.
  • If any part of the code is behind a feature flag, my test instructions also cover cases where the feature flag is switched off.
  • I have written this PR in accordance with my team's definition of done.
  • I have checked that the base branch is correctly set.

Innovation

  • No innovation project is applicable for this PR.
  • This PR falls under an innovation project. I have attached the innovation label.
  • I have added my hours to the WBSO document.

Fixes https://github.com/Yoast/lingo-other-tasks/issues/548

@FAMarfuaty FAMarfuaty added the changelog: enhancement Needs to be included in the 'Enhancements' category in the changelog label Sep 9, 2025
@coveralls
Copy link
Copy Markdown

coveralls commented Sep 10, 2025

Pull Request Test Coverage Report for Build fd3d1fc9e34afe0042090e7c288ddbdd2705ea22

Details

  • 40 of 40 (100.0%) changed or added relevant lines in 4 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage increased (+0.03%) to 53.239%

Totals Coverage Status
Change from base Build a014d2bf2cb4fba4f6085de257b47041a76838a2: 0.03%
Covered Lines: 31750
Relevant Lines: 59878

💛 - Coveralls

return ( keyphraseCount.count / wordCount ) * 100;
return {
density: ( keyphraseCount.count / wordCount ) * 100,
textLength: wordCount,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also return the text length here so that we don't need to recalculate the length inside the assessment

@FAMarfuaty FAMarfuaty changed the base branch from trunk to feature/off-the-bat-analysis September 22, 2025 13:46
matches: 0,
percentReflectingTopic: 0,
text: text,
textLength: customCountLength ? customCountLength( text ) : getWords( text ).length,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also return the text length here so we don't need to recalculate it inside the assessment

Copy link
Copy Markdown
Contributor

@JorPV JorPV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CR ✅ Just two tiny typo adjustments to make.

* @param {number} [config.scores.okay] The score to return if keyword occurrences are somewhat unevenly distributed.
* @param {number} [config.scores.bad] The score to return if there is way too much text between keyword occurrences.
* @param {number} [config.scores.consideration] The score to return if there are no keyword occurrences.
* @param {number} [config.scores.noKeyphraseOrText] The score to return if there is way no text and/or no keyphrase set.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The score to return if there is way no text and/or no keyphrase set.

Typo: the word way doesn't make sense in this sentence.

} );
} );
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe remove this last extra line 😅

@JorPV
Copy link
Copy Markdown
Contributor

JorPV commented Sep 25, 2025

CR ✅ AT ✅ It works like magic 🪄

@JorPV JorPV merged commit d5def0a into feature/off-the-bat-analysis Sep 25, 2025
20 checks passed
@JorPV JorPV deleted the 548-adjust-applicability-keyphrase-density-and-distribution branch September 25, 2025 13:50
@FAMarfuaty FAMarfuaty added the Google Docs Add-on If this PR is also relevant or has an impact on the Google Docs Add-on label Dec 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog: enhancement Needs to be included in the 'Enhancements' category in the changelog Google Docs Add-on If this PR is also relevant or has an impact on the Google Docs Add-on

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants