New article "Correct grammar with the Proofreader API" #3647
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mikehoffms
changed the title
mikehoffms
reviewed
Nov 20, 2025
mikehoffms
reviewed
Nov 20, 2025
mikehoffms
reviewed
Nov 20, 2025
mikehoffms
reviewed
Nov 20, 2025
mikehoffms
reviewed
Dec 1, 2025
mikehoffms
reviewed
Dec 18, 2025
mikehoffms
reviewed
Jan 30, 2026
| ms.service: microsoft-edge | ||
| ms.date: 01/30/2026 | ||
| --- | ||
| # Correct grammar, spelling, and punctuation errors in text with the Proofreader API |
Collaborator
There was a problem hiding this comment.
too much detail crammed into title, dup'ing the purpose of 1st sentence.
Design terse title in conjunction with verbose 1st sentence.
mikehoffms
reviewed
Jan 30, 2026
| ms.service: microsoft-edge | ||
| ms.date: 01/30/2026 | ||
| --- | ||
| # Correct grammar, spelling, and punctuation errors in text with the Proofreader API |
Collaborator
There was a problem hiding this comment.
Suggested change
| # Correct grammar, spelling, and punctuation errors in text with the Proofreader API | |
| # Correct grammar and spelling with the Proofreader API |
alts:
- Correct grammar and spelling with the Proofreader API
- Correct grammar, spelling, and punctuation errors in text with the Proofreader API
- Correct grammar and spelling in text with the Proofreader API
mikehoffms
reviewed
Jan 30, 2026
|
|
||
|
|
||
| <!-- ====================================================================== --> | ||
| ## Alternatives to and benefits of the Proofreader API |
Collaborator
There was a problem hiding this comment.
Too many different topics or distinct concerns in the heading.
Change to h2 "Benefits" section + h2 or h4 "alternatives" section.
Use separation of concerns, per section.
What's the clear message, of the heading?
Contradictory topics/ messages conveyed: "How to avoid using X, and, Benefits of X." Focus only on marketing the benefits, first. Then separately, afterwards, alternatives. Concept here is:
"Decide which API to use; pros and cons". - That's an alternative design for the heading.
Suggested change
| ## Alternatives to and benefits of the Proofreader API | |
| ## Decide which API to use | |
| ## Benefits of the Proofreader API | |
| #### Benefits of the Proofreader API | |
| ... | |
| ## Alternatives to the Proofreader API | |
| #### Alternatives to the Proofreader API |
mikehoffms
reviewed
Jan 30, 2026
| <!-- ====================================================================== --> | ||
| ## The Phi-4-mini model | ||
|
|
||
| The Proofreader API uses the Phi-4-mini model — a powerful small language model that excels at text-based tasks — built into Microsoft Edge. To learn more about Phi-4-mini and its capabilities, see the model card at [microsoft/Phi-4-mini-instruct](https://huggingface.co/microsoft/Phi-4-mini-instruct). |
Collaborator
There was a problem hiding this comment.
avoid nested thoughts. make 2 sentences.
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Disclaimer | ||
|
|
||
| Like other language models, the Phi family of models can potentially behave in ways that are unfair, unreliable, or offensive. To learn more about the model's AI considerations, see [Responsible AI Considerations](https://huggingface.co/microsoft/Phi-4-mini-instruct#responsible-ai-considerations). |
Collaborator
There was a problem hiding this comment.
confusing at "the model's AI considerations", what does that mean?
Ans: worries & concerns re: AI.
The link text is clear. The redundant lead-in introduces confusion.
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Hardware requirements | ||
|
|
||
| The Proofreader API developer preview is intended to work on devices with hardware capabilities that produce SLM outputs with predictable quality and latency. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The Proofreader API developer preview is intended to work on devices with hardware capabilities that produce SLM outputs with predictable quality and latency. | |
| The Proofreader API developer preview is intended to work on devices that have hardware capabilities that produce Small Language Model (SLM) outputs that have predictable quality and latency. |
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| The Proofreader API developer preview is intended to work on devices with hardware capabilities that produce SLM outputs with predictable quality and latency. | ||
|
|
||
| The Proofreader API is currently limited to: |
Collaborator
There was a problem hiding this comment.
Add "Requires..." to each list item? maybe the lead-in is the problem and should say Requirements:. Compare sibling articles.
Per timeless docs, don't say "currently".
The lead-in is contradictory of some list items:
The Proofreader API is currently limited to: ... At least 20 GB available
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| The Proofreader API developer preview is intended to work on devices with hardware capabilities that produce SLM outputs with predictable quality and latency. | ||
|
|
||
| The Proofreader API is currently limited to: |
Collaborator
There was a problem hiding this comment.
Suggested change
| The Proofreader API is currently limited to: | |
| The Proofreader API has the following requirements: |
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Model availability | ||
|
|
||
| An initial download of the model will be required the first time a website calls a built-in AI API. You can monitor the model download by using the monitor option when creating a new Proofreader API session. To learn more, see [Monitor the progress of the model download](#monitor-the-progress-of-the-model-download), below. |
Collaborator
There was a problem hiding this comment.
Suggested change
| An initial download of the model will be required the first time a website calls a built-in AI API. You can monitor the model download by using the monitor option when creating a new Proofreader API session. To learn more, see [Monitor the progress of the model download](#monitor-the-progress-of-the-model-download), below. | |
| An initial download of the model is required the first time a website calls a built-in AI API. You can monitor the model download by using the monitor option when creating a new Proofreader API session. See [Monitor the progress of the model download](#monitor-the-progress-of-the-model-download), below. |
- corp style guide: favor present tense.
- https://developers.google.com/style/timeless-documentation
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| 1. To check if your device meets the hardware requirements for the Proofreader API developer preview, open a new tab, go to `edge://on-device-internals`, and check the **Device performance class** value. | ||
|
|
||
| If your device performance class is **High** or greater, the Proofreader API should be supported on your device. If you continue to notice issues, please [file a new issue](https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/new?template=proofreader-api.md). |
Collaborator
There was a problem hiding this comment.
Suggested change
| If your device performance class is **High** or greater, the Proofreader API should be supported on your device. If you continue to notice issues, please [file a new issue](https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/new?template=proofreader-api.md). | |
| If your device performance class is **High** or greater, the Proofreader API is expected to be supported on your device. If you continue to notice issues, please [file a new issue](https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/new?template=proofreader-api.md). |
avoid such ambig use of 'should', are you directing me to support the API?
https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/should-vs-must - "Don't use should to indicate probability. If you can't make a definitive statement, use might, or rephrase.
alt wording ideas @captainbrosset ?
- "should" is confusing
- "expected" is a little awkward, but is clear and direct.
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| The output is generated in the response section of the page: | ||
|
|
||
|  |
Collaborator
There was a problem hiding this comment.
Suggested change
|  | |
|  |
mikehoffms
reviewed
Jan 30, 2026
|  | ||
|
|
||
| See also: | ||
| * [/built-in-ai/](https://github.com/MicrosoftEdge/Demos/tree/main/built-in-ai/) - Source code and Readme for the Built-in AI playgrounds demo. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * [/built-in-ai/](https://github.com/MicrosoftEdge/Demos/tree/main/built-in-ai/) - Source code and Readme for the Built-in AI playgrounds demo. | |
| * [/built-in-ai/](https://github.com/MicrosoftEdge/Demos/tree/main/built-in-ai/) - Readme and source code for the Built-in AI playgrounds demo. |
from experience: read the Readme first, before trying to run demo or view source code. But that was a different context:
In that other case, the article presented combined links like:
[the running demo] | [the Readme]
yet it was required that you read the Readme, and do some setup, before attempting to view the real Demo running. You could only see an empty demo page, until doing a step in the Readme.
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Check if the API is enabled | ||
|
|
||
| Before using the Proofreader API in your website's code, check that the API is enabled by testing the presence of the `Proofreader` object: |
Collaborator
There was a problem hiding this comment.
Suggested change
| Before using the Proofreader API in your website's code, check that the API is enabled by testing the presence of the `Proofreader` object: | |
| Before using the Proofreader API in your website's code, check that the API is enabled, by testing for the presence of the `Proofreader` object: |
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Check if the model can be used | ||
|
|
||
| The Proofreader API can only be used if the device supports running the model, and once the language model and model runtime have been downloaded by Microsoft Edge. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The Proofreader API can only be used if the device supports running the model, and once the language model and model runtime have been downloaded by Microsoft Edge. | |
| The Proofreader API can only be used if the device supports running the model, and after the language model and model runtime have been downloaded by Microsoft Edge. |
https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/o/once - "Don't use once as a synonym for after."
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| The Proofreader API can only be used if the device supports running the model, and once the language model and model runtime have been downloaded by Microsoft Edge. | ||
|
|
||
| To check if the API can be used, use the API's `availability()` method: |
Collaborator
There was a problem hiding this comment.
Suggested change
| To check if the API can be used, use the API's `availability()` method: | |
| To check if the API can be used, use the `availability()` method: |
i think the context is pretty clear, i assume, that we're presenting each method that's in the API.
eg below, we don't say "the API's create() method", just "the create() method".
mikehoffms
reviewed
Jan 30, 2026
| <!-- ====================================================================== --> | ||
| ## See a working example | ||
|
|
||
| To see the Proofreader API in action, and review existing code that uses these APIs: |
Collaborator
There was a problem hiding this comment.
Suggested change
| To see the Proofreader API in action, and review existing code that uses these APIs: | |
| To see the Proofreader API in action, and examine existing code that uses these APIs: |
don't say "review" when user has never seen something before and wants to view it for first time.
avoid see / see; this is a case where consistency feels like an awkward repeated same word (see / see would be distracting)
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| 1. In Microsoft Edge Canary or Dev browser, open a tab or window and go to the [Proofreader API playground](https://microsoftedge.github.io/Demos/built-in-ai/playgrounds/proofreader-api/). | ||
|
|
||
| 1. In the information banner at the top, check the status: it initially reads **On-device API and model downloading.**: |
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. In the information banner at the top, check the status: it initially reads **On-device API and model downloading.**: | |
| 1. In the information banner at the top, check the status. The status initially reads **On-device API and model downloading**: |
mikehoffms
reviewed
Jan 30, 2026
|
|
||
|  | ||
|
|
||
| After the model has downloaded, the information banner reads **On-device API and model available**, indicating that the API and model can be used: |
Collaborator
There was a problem hiding this comment.
Suggested change
| After the model has downloaded, the information banner reads **On-device API and model available**, indicating that the API and model can be used: | |
| After the model has been downloaded, the information banner reads **On-device API and model available**, indicating that the API and model can be used: |
the model does not drive its own downloading (it sort of does)
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| After the model has downloaded, the information banner reads **On-device API and model available**, indicating that the API and model can be used: | ||
|
|
||
|  |
Collaborator
There was a problem hiding this comment.
unclear link text: "Status indicator showing API and model ready"
Suggested change
|  | |
|  |
mikehoffms
reviewed
Jan 30, 2026
|
|
||
|  | ||
|
|
||
| If the model download doesn't start, restart Microsoft Edge and try again. |
Collaborator
There was a problem hiding this comment.
Suggested change
| If the model download doesn't start, restart Microsoft Edge and try again. | |
| If the model doesn't start downloading, restart Microsoft Edge and try again. |
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| The Proofreader API is only supported on devices that meet certain hardware requirements. For more information, see [Hardware requirements](#hardware-requirements), above. | ||
|
|
||
| 1. Optionally change the settings in the page, such as the text to proofread and the expected input language. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. Optionally change the settings in the page, such as the text to proofread and the expected input language. | |
| 1. Optionally change the content and settings in the page. For example, modify the text to proofread, or change the expected input language. |
doubt it's a "setting". Clarify: do you SELECT an input lang, or type-in to specify the input lang?
mikehoffms
reviewed
Jan 30, 2026
| | **Option** | **Description** | | ||
| | --- | --- | | ||
| | `monitor` | A function that's used to monitor the progress of the model download. See [Monitor the progress of the model download](#monitor-the-progress-of-the-model-download), below. | | ||
| | `expectedInputLanguages` | An array of strings listing the languages which the input text is expected to contain. For example: `["en"]`. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | `expectedInputLanguages` | An array of strings listing the languages which the input text is expected to contain. For example: `["en"]`. | | |
| | `expectedInputLanguages` | An array of strings. Each string is a language that the input text is expected to contain. For example: `["en"]`. | |
@captainbrosset pls list more than 1 item in the array
mikehoffms
reviewed
Jan 30, 2026
| <!-- ---------- --> | ||
| ###### Monitor the progress of the model download | ||
|
|
||
| You can follow the progress of the model download by using the `monitor` option. This is useful when the model has not yet been fully downloaded onto the device where it will be used, to inform users of your website that they should wait. |
Collaborator
There was a problem hiding this comment.
Suggested change
| You can follow the progress of the model download by using the `monitor` option. This is useful when the model has not yet been fully downloaded onto the device where it will be used, to inform users of your website that they should wait. | |
| You can follow the progress of the model download by using the `monitor` option. This is useful when the model has not yet been fully downloaded onto the device where it will be used, to inform users to wait. |
point got obscured by excess words
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Run the Proofreader API | ||
|
|
||
| To generate text, by using the Proofreader API, after you have created the corresponding model session, use the `session.proofread()` method. This method returns a promise that resolves once the Proofreader API has finished generating corrected text. |
Collaborator
There was a problem hiding this comment.
Suggested change
| To generate text, by using the Proofreader API, after you have created the corresponding model session, use the `session.proofread()` method. This method returns a promise that resolves once the Proofreader API has finished generating corrected text. | |
| To generate revised text by using the Proofreader API, after you have created the corresponding model session, use the `session.proofread()` method. This method returns a promise that resolves after the Proofreader API has finished generating corrected text. |
style guide don't use once as syn for after
mikehoffms
reviewed
Jan 30, 2026
| <!-- ------------------------------ --> | ||
| #### Use the result of the Proofreader API | ||
|
|
||
| The `session.proofread()` method returns a promise that resolves to an object with the following properties: |
Collaborator
There was a problem hiding this comment.
style guide favor not using 'with' wildcard
Suggested change
| The `session.proofread()` method returns a promise that resolves to an object with the following properties: | |
| The `session.proofread()` method returns a promise that resolves to an object that has the following properties: |
mikehoffms
reviewed
Jan 30, 2026
| | `correctedInput` | The corrected text, as a string. | | ||
| | `corrections` | An array of correction objects. | | ||
|
|
||
| The properties of the correction objects are listed below: |
Collaborator
There was a problem hiding this comment.
- don't doc the docs; doc the tech
- favor singular
Suggested change
| The properties of the correction objects are listed below: | |
| A correction object has the following properties: |
mikehoffms
reviewed
Jan 30, 2026
| // AbortController signal object by using the signal option. | ||
| const session = await Proofreader.create({ signal: controller.signal }); | ||
|
|
||
| // Later, perhaps when the user interacts with the UI, destroy the session by |
Collaborator
There was a problem hiding this comment.
Suggested change
| // Later, perhaps when the user interacts with the UI, destroy the session by | |
| // Later, such as when the user interacts with the UI, destroy the session by |
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| * **Network independence:** Beyond the initial model download, there's no network latency when prompting the model, and the model can also be used when the device is offline. | ||
|
|
||
| * **Improved privacy:** The data input to the model never leaves the device and is not collected to train AI models. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * **Improved privacy:** The data input to the model never leaves the device and is not collected to train AI models. | |
| * **Improved privacy:** The data that's input to the model never leaves the device, and isn't collected (such as to train AI models). |
mikehoffms
reviewed
Jan 30, 2026
|
|
||
| * **Shared one-time cost:** The browser-provided model is downloaded when the API is called for the first time, and then the model is shared across all websites that run in the browser, reducing network costs for the user and developer. | ||
|
|
||
| * **Simplified usage for web developers:** The built-in model can be run by using straightforward web APIs and doesn't require AI/ML expertise or using third-party frameworks. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * **Simplified usage for web developers:** The built-in model can be run by using straightforward web APIs and doesn't require AI/ML expertise or using third-party frameworks. | |
| * **Simplified usage for web developers:** The built-in model can be run by using straightforward web APIs, and doesn't require AI/ML expertise or using third-party frameworks. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Related PRs:
Rendered article for review:
/web-platform/proofreader-api.mdOther articles
TOC
~/toc.ymlPrompt a built-in language model with the Prompt API
/web-platform/prompt-api.mdSummarize, write, and rewrite text with the Writing Assistance APIs
/web-platform/writing-assistance-apis.mdAB#60242099