Update README.md

Author: FelipeLuz

README.md

@@ -1,58 +1,105 @@
 # .NET Bad Word Detector
 
-This is a fast and robust library that detects offensive language within text strings. It currently supports only English language, more languages will be added soon.
+This is a fast and robust library that detects offensive language within text strings. It currently supports English, Portuguese, and Spanish languages.
 
 ## How It Works
 
-This library uses a logistic regression [ML.NET](https://dotnet.microsoft.com/en-us/apps/machinelearning-ai/ml-dotnet) model trained on thousands of human-labeled words. The trained model then was loaded as a resource for this lib and it is consulted on every new prediction. 
+This library uses a logistic regression [ML.NET](https://dotnet.microsoft.com/en-us/apps/machinelearning-ai/ml-dotnet) model trained on thousands of human-labeled words. The trained model is embedded as a resource in this library and is consulted on every prediction.
 
-## Why to use this library?
+## Why Use This Library?
 
-Up to this moment all .NET profanity detection libraries use hard-coded lists of bad words to detect profanity, for instance, [ProfanityDetector](https://github.com/stephenhaunts/ProfanityDetector) uses this [list stored in memory](https://github.com/stephenhaunts/ProfanityDetector/blob/main/ProfanityFilter/ProfanityFilter/ProfanityList.cs), there are obvious glaring issues with this approach, and while they might be performant, these list based libraries are not comprehensive, they are easily outperformed by misspelling and by the human creativity to replace letters for meaningless chars creating new words that are perceived as curse words (e.g. house and h0us3).
+Unlike other .NET profanity detection libraries that rely solely on static hard-coded lists of bad words — such as [ProfanityDetector](https://github.com/stephenhaunts/ProfanityDetector) — which uses [this list stored in memory](https://github.com/stephenhaunts/ProfanityDetector/blob/main/ProfanityFilter/ProfanityFilter/ProfanityList.cs), this library uses a machine learning approach that can detect creative substitutions and misspellings (e.g., "h0us3" instead of "house"). This makes it much harder to bypass.
 
 ## Performance
 
-In a single prediction this library was 618 times faster than the most downloaded .NET package for detecting profanity. For 100 successive predictions it was around 24 times faster.
+In benchmarks, this library was up to **618 times faster** than the most downloaded .NET package for detecting profanity. For 100 successive predictions, it was approximately **24 times faster**.
 
-| Package                | 1 Prediction | 10 Predicitons | 100 predictions |
-|------------------------|--------------|----------------|-----------------|
-| .Net Bad Word Detector | 0.0462 ms    | 1.5508 ms      | 4.1887 ms       |
+| Package                | 1 Prediction | 10 Predictions | 100 Predictions |
+| ---------------------- | ------------ | -------------- | --------------- |
+| .NET Bad Word Detector | 0.0462 ms    | 1.5508 ms      | 4.1887 ms       |
 | ProfanityDetector      | 28.5823 ms   | 42.4606 ms     | 102.0750 ms     |
 
-PC specs: Dell Inspiron 13, I7 8th gen, 16 GB.
+**PC specs:** Dell Inspiron 13, i7 8th gen, 16 GB RAM.
 
-## How to install
+## Installation
 
 ```bash
 dotnet add package DotnetBadWordDetector
 ```
 
-## How to use it
+## How to Use
+
+### Create the detector
 
 ```csharp
+using DotnetBadWordDetector;
+
+// English only (default)
 var detector = new ProfanityDetector();
 
-if(detector.IsProfane("foo bar")){
-    //do something
+// Or load all supported languages: English, Spanish, and Portuguese
+var detectorAll = new ProfanityDetector(allLocales: true);
+```
+
+---
+
+### Check if a word is offensive
+
+```csharp
+if (detector.IsProfane("example")) {
+    // Word is classified as offensive
 }
+```
+
+---
+
+### Check if a phrase contains any offensive words
 
+```csharp
+if (detector.IsPhraseProfane("this is an example")) {
+    // Phrase contains at least one offensive word
+}
 ```
-It is strongly suggested to keep the library always loaded in memory to increase its performance, it uses very little memory (less than 100 KB).
-## Accuracy, AUC and F1 score
+
+---
+
+### Get the probability that a word or phrase is offensive
+
+```csharp
+float probWord = detector.GetProfanityProbability("example");
+float probPhrase = detector.GetPhraseProfanityProbability("this is an example");
+```
+
+---
+
+### Mask offensive words in a phrase
+
+```csharp
+string cleanText = detector.MaskProfanity("this is an example", '*');
+```
+
+This will replace any detected offensive words with asterisks or your chosen character.
+
+## Model Quality
 
 ```bash
 Model quality metrics evaluation
 --------------------------------
 Accuracy: 98.43%
-Auc: 99.49%
-F1Score: 97.25%
+AUC: 99.49%
+F1 Score: 97.25%
 ```
 
-## Caveat
-
-This library is not perfect, it is not 100% precise, and it is context-free, e.g. it can not detect profane phrases consisted of decent words. Also people diverge on what is considered profane.
+## Notes
 
+This library is not perfect: it is not 100% accurate and it is context-free — meaning it cannot detect profane phrases made of individually inoffensive words.
+Definitions of "profanity" can vary by culture. This library uses human-labeled data, which might not align perfectly with all contexts.
 
+## Tips
 
+* Keep the detector instance in memory for better performance — it uses very little memory (less than 100 KB).
+* Be cautious when enabling all locales together, as it may produce more false positives in multilingual texts.
 
+## Contributing
 
+Contributions are welcome! Feel free to open an issue or submit a pull request with suggestions for new features, languages, or improvements.