Add natural language linting

.github/linters/.textlintrc

@@ -0,0 +1,41 @@
+{ 
+  "rules": {
+    "terminology": {
+      "severity" : "warning",
+      "exclude": [
+        "back[- ]end(\\w*)",
+        "bug[- ]fix(es)?",
+        "client ?side",
+        "end-?user(s)?",
+        "indexes\\b",
+        "front[- ]end(\\w*)",
+        "Mac ?OS",
+        "OS X",
+        "readme(s)?",
+        "server ?side",
+        "smartphone(s)?",
+        "spell-?check(er|ing)?",
+        "style-?sheet(s)?",
+        "web-?page(s)?",
+        "web[- ]?site(s)?",
+        "white[- ]space",
+        "ZIP"
+      ],
+      "terms": [
+        ["backend(\\w*)", "back end$1"],
+        ["bug[- ]fix", "bugfix"],
+        ["bug-?fixes", "bug fixes"],
+        ["indices\\b", "indexes"],
+        ["frontend(\\w*)", "front end$1"],
+        "macOS",
+        "ReadMe",
+        ["smart[- ]phone(s)?", "smartphone$1"],
+        ["spell[- ]?check(er|ing)", "spelling checker$1"],
+        "UNIX",
+        ["web[- ]page(s)?", "webpage$1"],
+        ["web[- ]site(s)?", "website$1"],
+        ["white-?space", "white space"]
+      ]
+   }
+  }
+}

.github/super-linter.env

@@ -1,5 +1,8 @@
 IGNORE_GITIGNORED_FILES=true
-VALIDATE_MARKDOWN=true
 MARKDOWN_CONFIG_FILE=.markdownlint.yml
-VALIDATE_YAML=true
+VALIDATE_ALL_CODEBASE=true
+VALIDATE_GITHUB_ACTIONS=true
 VALIDATE_JSON=true
+VALIDATE_MARKDOWN=true
+VALIDATE_NATURAL_LANGUAGE=true
+VALIDATE_YAML=true

.github/workflows/test-pull-request.yml

@@ -1,85 +1,89 @@
 ---
-###########################
-###########################
-## Pull request testing ##
-###########################
-###########################
-name: Latest Pull Request
-
-# Documentation:
-# - Workflow: https://help.github.com/en/articles/workflow-syntax-for-github-actions
-# - SuperLinter: https://github.com/github/super-linter
-# - Link validation: https://github.com/remarkjs/remark-validate-links
-
-######################################################
-# Start the job on a pull request to the main branch #
-######################################################
-on: pull_request
-
-###############
-# Set the Job #
-###############
-jobs:
-  validate:
-    # Set the agent to run on
-    runs-on: ubuntu-latest
-
-    ############################################
-    # Grant status permission for MULTI_STATUS #
-    ############################################
-    permissions:
-      contents: read
-      packages: read
-      statuses: write
-
-    ##################
-    # Load all steps #
-    ##################
-    steps:
-      ##########################
-      # Checkout the code base #
-      ##########################
-      - name: Checkout Code
-        uses: actions/checkout@v4
-        with:
-          # Full git history is needed to get a proper list of changed files
-          # within `super-linter`
-          fetch-depth: 0
-      - run: cat ".github/super-linter.env" >> "$GITHUB_ENV"
-
-      ################################
-      # Run Linters against code base #
-      ################################
-      - name: Lint Code Base
-        #
-        # Use full version number to avoid cases when a next
-        # released version is buggy
-        # About slim image: https://github.com/github/super-linter#slim-image
-        uses: super-linter/super-linter/[email protected]
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEFAULT_BRANCH: main
-          VALIDATE_ALL_CODEBASE: false
-          VALIDATE_GITHUB_ACTIONS: true
-
-      - name: Setup Node
-        uses: actions/setup-node@v3
-        with:
-          node-version-file: '.nvmrc'
-          cache: 'yarn'
-          cache-dependency-path: 'yarn.lock'
-
-      - name: Enable Corepack for Yarn
-        run: corepack enable
-
-      - name: Install Dependencies
-        run: yarn install
-        env:
-          YARN_ENABLE_IMMUTABLE_INSTALLS: false
-
-      - name: Check links
-        run: yarn test
-
-      - name: Build site
-        if: ${{ success() }}
-        run: yarn build
+  ###########################
+  ###########################
+  ## Pull request testing ##
+  ###########################
+  ###########################
+  name: Validate pull request
+
+  # Documentation:
+  # - Workflow: https://help.github.com/en/articles/workflow-syntax-for-github-actions
+  # - SuperLinter: https://github.com/github/super-linter
+  # - Link validation: https://github.com/remarkjs/remark-validate-links
+
+  ######################################################
+  # Start the job on a pull request to the main branch #
+  ######################################################
+  on: pull_request
+
+  ###############
+  # Set the Job #
+  ###############
+  jobs:
+    lint:
+      # Set the agent to run on
+      runs-on: ubuntu-latest
+
+      ############################################
+      # Grant status permission for MULTI_STATUS #
+      ############################################
+      permissions:
+        contents: read
+        packages: read
+        statuses: write
+
+      ##################
+      # Load all steps #
+      ##################
+      steps:
+        ##########################
+        # Checkout the code base #
+        ##########################
+        - name: Checkout Code
+          uses: actions/checkout@v4
+          with:
+            # Full git history is needed to get a proper list of changed files
+            # within `super-linter`
+            fetch-depth: 0
+        - name: Load super-linter configuration
+          run: cat .github/super-linter.env >> "$GITHUB_ENV"
+
+        ################################
+        # Run Linters against code base #
+        ################################
+        - name: Lint Code Base
+          #
+          # Use full version number to avoid cases when a next
+          # released version is buggy
+          # About slim image: https://github.com/github/super-linter#slim-image
+          uses: super-linter/super-linter/[email protected]
+          env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            DEFAULT_BRANCH: main
+    test_and_build:
+      runs-on: ubuntu-latest
+      needs: lint
+      steps:
+        - name: Checkout Code
+          uses: actions/checkout@v4
+
+        - name: Setup Node
+          uses: actions/setup-node@v3
+          with:
+            node-version-file: '.nvmrc'
+            cache: 'yarn'
+            cache-dependency-path: 'yarn.lock'
+
+        - name: Enable Corepack for Yarn
+          run: corepack enable
+
+        - name: Install Dependencies
+          run: yarn install
+          env:
+            YARN_ENABLE_IMMUTABLE_INSTALLS: false
+
+        - name: Check links
+          run: yarn test
+
+        - name: Build site
+          run: yarn build

.textlintrc

@@ -0,0 +1 @@
+.github/linters/.textlintrc

README.md

@@ -11,11 +11,11 @@ Our goal is to provide the Adobe Commerce and Magento Open Source communities wi
 ## Local development
 
 This is a [Gatsby](https://www.gatsbyjs.com/) project that uses the [Adobe I/O Theme](https://github.com/adobe/aio-theme).
-Ensure that your local environment matches the prerequisites described in the Adobe I/O Theme README.
+Ensure that your local environment matches the prerequisites described in the Adobe I/O Theme ReadMe.
 
 To build the site locally:
 
-1. Clone this repo.
+1. Clone this repository.
 1. Install project dependencies.
 
    ```bash

src/_includes/graphql/attribute-metadata.md

@@ -10,4 +10,4 @@ Attribute | Type | Description
 `label` | String | The label assigned to the attribute
 `sort_order` | Int | The relative position of the attribute
 `uid` | ID | The unique ID of an attribute
-`ui_input` | UiInputTypeInterface | Frontend UI properties of the attribute
+`ui_input` | UiInputTypeInterface | Front end UI properties of the attribute

src/_includes/graphql/payment-methods/payflow-link-workflow.md

@@ -4,7 +4,7 @@
 
 1. The client runs the [`placeOrder`](/src/pages/graphql/schema/cart/mutations/place-order.md) mutation, which creates an order and begins the authorization process.
 
-1. The application requests a secure token from the Paypal gateway.
+1. The application requests a secure token from the PayPal gateway.
 
 1. The gateway response includes a secure token, a secure token ID, and the URL to use for requesting the form in step 9. This token secures the data for a one-time transaction and is valid for 30 minutes.
 

src/_includes/graphql/payment-methods/paypal-express-checkout-workflow.md

@@ -1,4 +1,4 @@
-1. When the buyer clicks a PayPal button, the frontend executes the [`createPaypalExpressToken`](/src/pages/graphql/schema/checkout/mutations/create-paypal-express-token.md) mutation.
+1. When the buyer clicks a PayPal button, the front end executes the [`createPaypalExpressToken`](/src/pages/graphql/schema/checkout/mutations/create-paypal-express-token.md) mutation.
 
 1. The application requests a secure token from PayPal. The application gathers information in the specified cart and sends this information to PayPal as part of a request for a secure token.
 
@@ -10,7 +10,7 @@
 
 1. If the customer approves the payment, PayPal redirects the customer back to the payment confirmation page. The response includes the secure token and payer ID as GET parameters.
 
-1. Set the payment method. The frontend runs the [`setPaymentMethodOnCart`](/src/pages/graphql/schema/cart/mutations/set-payment-method.md) mutation. The payload includes the PayPal token, the payer ID, and the cart ID. The cart may have been updated since the token was requested, as shipping costs, taxes, and other adjustments might have been applied to the cart. The application submits the updated cart to PayPal.
+1. Set the payment method. The front end runs the [`setPaymentMethodOnCart`](/src/pages/graphql/schema/cart/mutations/set-payment-method.md) mutation. The payload includes the PayPal token, the payer ID, and the cart ID. The cart may have been updated since the token was requested, as shipping costs, taxes, and other adjustments might have been applied to the cart. The application submits the updated cart to PayPal.
 
 1. The application returns a `Cart` object.
 

src/pages/get-started/api-security.md

@@ -159,7 +159,7 @@ If you need to change the default limits for REST endpoints, then edit the `weba
 
 The maximum page size setting controls the pagination of various web API responses. By default, the maximum value is `300`. You can change the default in the Admin by selecting **Stores** > Settings > **Configuration** > **Services** > **Web API Input Limits** or **GraphQl Input Limits** >  **Maximum Page Size** field.
 
-[GraphQL security configuration](../graphql/usage/security-configuration.md describes how to set the maximum page size in GraphQL.
+[GraphQL security configuration](../graphql/usage/security-configuration.md) describes how to set the maximum page size in GraphQL.
 
 ## Default page size
 

src/pages/get-started/authentication/gs-authentication-oauth.md

@@ -101,7 +101,7 @@ You must include these request parameters in the `Authorization`  header in the
 
 Parameter | Description
 --- | ---
-`oauth_consumer_key` | The consumer key value that you retrieve after you register the integration.
+`oauth_consumer_key` | The consumer key-value that you retrieve after you register the integration.
 `oauth_nonce` | A random value that is uniquely generated by the application.
 `oauth_signature` | A generated value (signature)
 `oauth_signature_method` | The name of the signature method used to sign the request. Must be the value `HMAC-SHA256`.
@@ -128,7 +128,7 @@ To use the access token to make web API calls:
 
 You must include these request parameters in the `Authorization` request header in the call:
 
-*  `oauth_consumer_key`. The customer key value provided after the registration of the application.
+*  `oauth_consumer_key`. The customer key-value provided after the registration of the application.
 *  `oauth_nonce`. A random value, uniquely generated by the application.
 *  `oauth_signature_method`. The name of the signature method used to sign the request. Valid values are: `HMAC-SHA256`.
 *  `oauth_signature`. A generated value (signature).
@@ -137,7 +137,7 @@ You must include these request parameters in the `Authorization` request header
 
 ## The OAuth signature
 
-All OAuth handshake requests and Web Api requests include the signature as part of Authorization header. Its generated as follows:
+All OAuth handshake requests and Web API requests include the signature as part of Authorization header. Its generated as follows:
 
 You concatenate a set of URL-encoded attributes and parameters to construct the signature base string.
 

src/pages/get-started/authentication/gs-authentication-session.md

@@ -30,7 +30,7 @@ Similarly, if an admin is logged in to the Admin and the JavaScript widget invok
 
 Admin session-based authentication is not currently possible for API endpoints.
 
-The session based authentication functionality is restricted to AJAX calls. Direct browser requests cannot be made due to security vulnerabilities. A developer can create a custom storefront widget that can issue requests without additional authentication steps.
+The session based authentication functionality is restricted to Ajax calls. Direct browser requests cannot be made due to security vulnerabilities. A developer can create a custom storefront widget that can issue requests without additional authentication steps.
 
 ## Related topic
 

src/pages/get-started/gs-curl.md

@@ -156,7 +156,7 @@ $this->curl->setCookies($cookies);
 
 ### Example usage
 
-For example, the `Magento\Marketplace\Model\Partners` class gets partners info using cURL from the api of Magento connect.
+For example, the `Magento\Marketplace\Model\Partners` class gets partners info using cURL from the API of Magento connect.
 
 ```php
 namespace Magento\Marketplace\Model;
@@ -271,7 +271,7 @@ class Partners
 ```
 
 First off all the cURL client instance is created in `__construct`.
-Method `getPartners` uses the cURL client makes POST request using cURL, the `post` method takes the first parameter the URL to the api of `magento-connect`, second parameter is empty array, then the option `CURLOPT_REFERER` added by `setOptions` method of the cURL client.
+Method `getPartners` uses the cURL client makes POST request using cURL, the `post` method takes the first parameter the URL to the API of `magento-connect`, second parameter is empty array, then the option `CURLOPT_REFERER` added by `setOptions` method of the cURL client.
 As result the script call `getBody` method of the cURL client.
 
 #### Related topics

src/pages/get-started/gs-web-api-request.md

@@ -55,7 +55,7 @@ HTTP header | Description | Syntax
 `Authorization` | Required, except for calls made on behalf of a guest. Specifies the authentication token that proves you as the owner of a customer, admin, or integration account. You specify the token in the `Authorization` request header with the `Bearer` HTTP authorization scheme. | `Authorization: Bearer <TOKEN>` <br/><br/>`<TOKEN>` is the authentication token returned by the token service. See [Authentication](./authentication/).
 `Accept` | Optional. Specifies the format of the response body. Default is `JSON`. | `Accept: application/<FORMAT>` <br/><br/>`<FORMAT>` is either `JSON` or `XML`.
 `Content-Type` | Required for operations with a request body. Specifies the format of the request body. | `Content-Type:application/<FORMAT>` <br/><br/>`<FORMAT>` is either `JSON` or `XML`.
-`X-Captcha` | A shopper-entered CAPTCHA value. It is required when a shopper enters a CAPTCHA value on the frontend, unless an integration token is provided. Forms requiring CAPTCHA values are configured at **Stores** > **Configuration** > **Customers** > **Customer Configuration** > **CAPTCHA** > **Forms**. | String
+`X-Captcha` | A shopper-entered CAPTCHA value. It is required when a shopper enters a CAPTCHA value on the front end, unless an integration token is provided. Forms requiring CAPTCHA values are configured at **Stores** > **Configuration** > **Customers** > **Customer Configuration** > **CAPTCHA** > **Forms**. | String
 `X-ReCaptcha` | A value generated by the Google reCAPTCHA API. It is required when reCAPTCHA is enabled for certain forms, unless an integration token is provided. Forms requiring reCAPTCHA values are configured at **Stores** > **Security** > **Google reCAPTCHA Storefront** > **Storefront**. | String
 
 ### Call payload

src/pages/get-started/index.md

@@ -19,7 +19,7 @@ The Adobe Commerce and Magento Open Source web API framework provides integrator
 
 *  All accounts and integrations are assigned resources that they have access to. The API framework checks that any call has the authorization to perform the request.
 
-*  Any native or third-party service can be [configured as a web API](https://developer.adobe.com/commerce/php/development/components/web-api/services/) with a few lines of xml. To configure a web API, you define XML elements and attributes in a `webapi.xml` configuration file. If a service is not defined in a configuration file, it will not be exposed at all.
+*  Any native or third-party service can be [configured as a web API](https://developer.adobe.com/commerce/php/development/components/web-api/services/) with a few lines of XML. To configure a web API, you define XML elements and attributes in a `webapi.xml` configuration file. If a service is not defined in a configuration file, it will not be exposed at all.
 
 *  The framework is based on the CRUD (create, read, update, delete) & search model. The system does not currently support webhooks.
 
@@ -33,11 +33,11 @@ The APIs can be used to perform a wide array of tasks. For example:
 
 *  Create a shopping app. This can be a traditional app that a user downloads on a mobile device. You could also create an app that an employee uses on a showroom floor to help customers make purchases.
 
-*  Integrate with CRM (Customer Relationship Management) or ERP (Enterprise Resource Planning) backend systems, such as Salesforce or Xero.
+*  Integrate with CRM (Customer Relationship Management) or ERP (Enterprise Resource Planning) back-end systems, such as Salesforce or Xero.
 
 *  Integrate with a CMS (Content Management System). Currently, content tagging is not supported.
 
-*  Create JavaScript widgets in the storefront or on the Admin panel. The widget makes AJAX calls to access services.
+*  Create JavaScript widgets in the storefront or on the Admin panel. The widget makes Ajax calls to access services.
 
 ## How do I get started?