docs: minor migration guide updates

docs/guide/upgrading.md

@@ -18,7 +18,7 @@ v9 has not yet been released. This page contains a work-in-progress list of brea
 
 ## General Breaking Changes
 
-### Node 14 and 16 No Longer Supported
+### Node 14 and 16 Not Supported
 
 Support for Node.js versions 14 and 16 has been discontinued as these versions have reached their [end-of-life](https://github.com/nodejs/Release). Faker.js 9.0 requires a minimum of Node.js version 18.
 
@@ -44,26 +44,25 @@ If you are unable to upgrade to TS5, you have to keep using Faker v8.
 
 ### Fix Tree Shaking
 
-Prior to this version, users had to resort to workarounds by importing specific faker instances from dedicated paths to overcome tree shaking issues.
+Prior to this version, users had to resort to a workaround by importing specific faker instances from dedicated paths to overcome an issue which caused all locales to be bundled even if only one was used.
 
 ```ts
 import { faker } from '@faker-js/faker/locale/de';
 ```
 
-With the implementation of this fix, such workarounds should no longer be necessary.
-That means that you should be able to import different localized faker instances from the root of your package.
+With the implementation of this fix, this workaround should no longer be necessary. You should be able to import different localized faker instances from the root of your package, and the bundle will only include the specific locales.
 
 ```ts
 import { fakerDE, fakerES, fakerFR } from '@faker-js/faker';
 ```
 
-The dedicated import paths will still stay for now, to allow a gradual migration for our users.
+The dedicated import paths are kept in v9, to allow a gradual migration for our users.
 
-While the implementation of this change does not constitute as breaking according to semantic versioning guidelines, it does impact the behavior of users bundlers.
+While the implementation of this change does not constitute as breaking according to semantic versioning guidelines, it does impact the behavior of users' bundlers.
 
-### Use High Precision RNG by default
+### Use High Precision RNG by Default
 
-TLDR: Many Faker methods will return a different result in v9 compared to v8 for the same seed.
+TLDR: Many Faker methods return a different result in v9 compared to v8 for the same seed.
 
 In v9 we switch from a 32 bit random value to a 53 bit random value.
 We don't change the underlying algorithm much, but we now consume two seed values each step instead of one.
@@ -116,7 +115,7 @@ If you have seeded tests, you have to update most test snapshots or similar comp
 
 If you are using vitest, you can do that using `pnpm vitest run -u`.
 
-#### Keeping the old behavior
+#### Keeping the Old Behavior
 
 You can keep the old behavior, if you create your own `Faker` instance
 and pass a `Randomizer` instance from the `generateMersenne32Randomizer()` function to it.
@@ -134,19 +133,19 @@ const faker = new Faker({
 });
 ```
 
-### Using `tsup` for the build process
+### Using `tsup` for the Build Process
 
-We only support exports defined via `package.json` but after the switch to `tsup`, there are now complete restructures in the dist folder resulting it minified and chunked files for cjs.
+After the switch to `tsup`, the dist folder now contains minified and chunked files for CJS. However, as we support exports defined via `package.json` this should not affect your code.
 
 ## Removals of Deprecated Code
 
 A large number of methods which were deprecated in v8 are completely removed in v9. To prepare for the upgrade, it is recommended to first upgrade to the latest version of v8 (e.g. `npm install --save-dev faker@8`) and fix any deprecation warnings issued by your code.
 
-The following sections will contain more information about these changes.
+The following sections contain more information about these changes.
 
 ### Constructor and JS Backwards-Compatibility Methods
 
-Removed deprecated faker constructor, so it is not possible anymore to just pass a locale string identifier.
+Removed deprecated faker constructor, so you can no longer just pass a locale string identifier.
 
 Also removed the accessors and method that were only for JS backwards compatibility.
 
@@ -281,7 +280,7 @@ faker.helpers.regexpStyleStringParse('a{3,6}'); // aaaaa
 faker.helpers.fromRegExp('a{3,6}'); // aaaaa
 ```
 
-However, please note that `faker.helpers.fromRegExp` is not an exact replacement for `faker.helpers.regexpStyleStringParse` as `fromRegExp` cannot handle numeric ranges. This will now need to be handled separately.
+However, please note that `faker.helpers.fromRegExp` is not an exact replacement for `faker.helpers.regexpStyleStringParse` as `fromRegExp` cannot handle numeric ranges. This now needs to be handled separately.
 
 ```ts
 faker.helpers.regexpStyleStringParse('a{3,6}[1-100]'); // "aaaa53", etc.
@@ -294,7 +293,7 @@ Prior to v9, Faker provided a [`faker.helpers.unique()`](https://v8.fakerjs.dev/
 
 Please see the [unique values guide](/guide/unique) for alternatives.
 
-For example, many simple use cases can use [`faker.helpers.uniqueArray`](https://v8.fakerjs.dev/api/helpers.html#uniqueArray). Or you can migrate to a third party package such as `enforce-unique`:
+For example, many simple use cases can use [`faker.helpers.uniqueArray`](https://v8.fakerjs.dev/api/helpers.html#uniqueArray). Or you can migrate to a third party package such as [`enforce-unique`](https://www.npmjs.com/package/enforce-unique):
 
 Basic example:
 
@@ -351,7 +350,7 @@ const city = enforcer.enforce(faker.location.city, {
 ```
 
 ::: tip Note
-`enforce-unique` does not support the `exclude` or `store` options. If you were previously using these, you may wish to build your own unique logic instead.
+`enforce-unique` does not support the `store` option. If you were previously using this, you may wish to build your own unique logic instead.
 :::
 
 ### Image Module
@@ -376,9 +375,9 @@ Removed deprecated image methods
 | `faker.image.technics()`  | `faker.image.urlLoremFlickr({ category: 'technics' })` or `faker.image.url()`  |
 | `faker.image.transport()` | `faker.image.urlLoremFlickr({ category: 'transport' })` or `faker.image.url()` |
 
-#### image providers
+#### Image Providers
 
-Removed deprecated image providers from `faker.image`. They already returned broken image URLs anyways.
+Removed deprecated image providers from `faker.image`. They already returned broken image URLs anyway.
 
 | old                                         | replacement                                              |
 | ------------------------------------------- | -------------------------------------------------------- |
@@ -476,7 +475,7 @@ Removed deprecated random module
 
 ### Locale Aliases
 
-Removed deprecated locale aliases
+Removed deprecated locale aliases `cz`, `en_IND`, `ge` and `global`.
 
 | old                                                     | replacement                                            |
 | ------------------------------------------------------- | ------------------------------------------------------ |
@@ -519,9 +518,9 @@ Removed deprecated type aliases
 
 ## Breaking Changes to Specific Methods
 
-### Changed Default Mode from Birthdate
+### Birthdate New Default Mode
 
-Previously, the method had defaults that were unclear in their specific impact.
+Previously, the `faker.date.birthdate()` method had defaults that were unclear in their specific impact.
 Now, the method requires either none or all of the `min`, `max` and `mode` options.
 
 We also improved the error messages in case of invalid min/max age/year ranges.
@@ -536,14 +535,14 @@ Now, this throws an error raising awareness of that bad value.
 
 This affects the `refDate` parameter of the `anytime()`, `birthdate()`, `past()`, `future()`, `recent()` and `soon()`, methods as well as the `from` and `to` parameters of `between()` and `betweens()`.
 
-### Prices now return more price-like values
+### Prices Now Return More Price-Like Values
 
-The `faker.commerce.price` method now produces values, that also return fractional values.
+The `faker.commerce.price()` method now produces values that also return fractional values.
 
 Old price: 828.00
 New price: 828.59
 
-The last digit of the price will adjusted to be more price-like:
+The last digit of the price is adjusted to be more price-like:
 
 - 50% of the time: `9`
 - 30% of the time: `5`
@@ -552,7 +551,7 @@ The last digit of the price will adjusted to be more price-like:
 
 We plan to rethink this method some more in the future: [#2579](https://github.com/faker-js/faker/issues/2579)
 
-### Randomized Image Option Defaults
+### Images Have Random Options by Default
 
 `faker.image.url()` now returns an image url with a random width and height by default. To obtain the previous behavior, pass `{width: 640, height: 480}`.
 
@@ -562,11 +561,11 @@ We plan to rethink this method some more in the future: [#2579](https://github.c
 
 `faker.image.dataUri()` now returns an image url with a random width and height by default, additionally the type of the image is now random. To obtain the previous behavior, pass `{width: 640, height: 480, type: 'svg-uri'}`.
 
-### Require `from` and `to` in `faker.date.between()` and `betweens()`
+### Require `from` and `to` in `faker.date.between` and `betweens`
 
-Previously, in `faker.date.between()` and `faker.date.betweens()` if the `from` or `to` parameter was omitted (in Javascript) or an invalid date (in Javascript or Typescript), they would default to the current date or reference date. Now, both boundaries must now be given explictly. If you still need the old behavior, you can pass `Date.now()` or the reference date for `from` or `to`.
+Previously, in `faker.date.between()` and `faker.date.betweens()` if the `from` or `to` parameter was omitted (in Javascript) or an invalid date (in Javascript or Typescript), they would default to the current date or reference date. Now, both boundaries must now be given explicitly. If you still need the old behavior, you can pass `Date.now()` or the reference date for `from` or `to`.
 
-### Stricter Checking for Function Signature passed to `faker.helpers.multiple` Method
+### Stricter Checking for Function Signature Passed to `faker.helpers.multiple` Method
 
 The `faker.helpers.multiple` method takes a function reference as its first parameter. Previously you may have written code like this to generate multiple values.
 
@@ -608,7 +607,7 @@ faker.helpers.multiple((_, index) => ({ id: index, ...}), ...); // [{id: 0, ...}
 ### Stricter Enum Value Usage
 
 Some methods would previously fallback to a default value for an option when an unknown value was passed for a enum parameter.
-Now, these methods will return undefined instead.
+Now, these methods return undefined instead.
 This only affects usage in Javascript, as in Typescript this usage would already throw a compile-time error.
 
 For example:
@@ -626,9 +625,9 @@ This affects:
 - The `variant` property of `faker.location.countryCode()` must be one of `alpha-2`, `alpha-3`, `numeric` if provided
 - The `casing` property of `faker.string.alpha()` and `faker.string.alphanumeric()` must be one of `'upper' | 'lower' | 'mixed'` if provided
 
-### faker.phone.number `style` replaces explicit `format`
+### Phone Number `style` Replaces Explicit `format`
 
-`faker.phone.number()` generates a phone number for the current locale. However, previously there was little control over the generated number, which might or might not include country codes, extensions, white space and punctuation.
+`faker.phone.number()` generates a phone number for the current locale. Previously there was little control over the generated number, which might or might not include country codes, extensions, white space and punctuation.
 
 If you wanted more control over the number, it was previously necessary to pass an explicit `format` parameter. This has now been removed. Instead, you can consider one of two options: