Docs: Edit 2.2.0 docs (#1099)

* Edit changelog and release notes

* Edit the Internationalization overview guide

* Edit the File import guide

* Rename i18n-overview to i18n-features

* Rename importing-files -> file-import guide

Co-authored-by: Kuba Sekowski <jakub.sekowski@handsontable.com>

Author: Jakub Wiśniewski

CHANGELOG.md

@@ -9,11 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [2.2.0] - 2022-11-17
 
 ### Added
-- Added American English (`enUS`) language pack. This is a convenience alias, since the function names provided by it are identical to the ones in the existing British English (`enGB`) language pack. [#1025](https://github.com/handsontable/hyperformula/issues/1025)
+- Added an American English (`enUS`) language pack. It's a convenience alias: it contains the same translations as the existing British English (`enGB`) language pack. [#1025](https://github.com/handsontable/hyperformula/issues/1025)
 
 ### Fixed
-- Fixed functions VLOOKUP and HLOOKUP to handle duplicates according to the specification. [#1072](https://github.com/handsontable/hyperformula/issues/1072)
-- Fixed function MATCH to handle ranges ordered descending according to the specification. [#1063](https://github.com/handsontable/hyperformula/issues/1063)
+- Fixed functions VLOOKUP and HLOOKUP to handle duplicates in the way specified by the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html#HLOOKUP) standard. [#1072](https://github.com/handsontable/hyperformula/issues/1072)
+- Fixed the MATCH function to handle descending ranges in the way specified by the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html#MATCH) standard. [#1063](https://github.com/handsontable/hyperformula/issues/1063)
 
 ## [2.1.0] - 2022-09-08
 

README.md

@@ -25,8 +25,8 @@
 
 HyperFormula is a headless spreadsheet built on top of TypeScript. It is a parser and evaluator of Excel formulas for web applications. You can use it in a browser or as a service, with Node.js as your back-end technology.
 - High-speed Excel formula parsing and evaluating
-- A library of [380+ built-in functions](https://hyperformula.handsontable.com/guide/built-in-functions.html)
-- Support for [internationalization](https://hyperformula.handsontable.com/guide/i18n-overview.html) with 17 built-in languages
+- A library of nearly [400 built-in functions](https://hyperformula.handsontable.com/guide/built-in-functions.html)
+- Support for [internationalization](https://hyperformula.handsontable.com/guide/i18n-features.html) with 17 built-in languages
 - Support for [custom functions](https://hyperformula.handsontable.com/guide/custom-functions.html)
 - Function syntax compatible with [Microsoft Excel](https://hyperformula.handsontable.com/guide/compatibility-with-microsoft-excel.html) and [Google Sheets](https://hyperformula.handsontable.com/guide/compatibility-with-google-sheets.html)
 - [Support for Node.js](https://hyperformula.handsontable.com/guide/server-side-installation.html#install-with-npm-or-yarn)

docs/.vuepress/config.js

@@ -203,7 +203,7 @@ module.exports = {
           title: 'Internationalization',
           collapsable: false,
           children: [
-            ['/guide/i18n-overview', 'Internationalization overview'],
+            ['/guide/i18n-features', 'Internationalization features'],
             ['/guide/localizing-functions', 'Localizing functions'],
             ['/guide/date-and-time-handling', 'Date and time handling'],
           ]
@@ -227,7 +227,7 @@ module.exports = {
             ['/guide/custom-functions', 'Custom functions'],
             ['/guide/performance', 'Performance'],
             ['/guide/known-limitations', 'Known limitations'],
-            ['/guide/importing-files', 'Importing XLSX/CSV files'],
+            ['/guide/file-import', 'File import'],
           ]
         },
         {

docs/guide/built-in-functions.md

@@ -28,17 +28,11 @@ The latest version of HyperFormula has an extensive collection of **{{ $page.fun
 _Some categories such as compatibility, cube, and database
 are yet to be supported._
 
-## Language packs
+## Internationalization
 
-HyperFormula provides translation packs for 16 languages thus making
-it easier to create localized applications. The supported languages
-are: English (default), Czech, Danish, Dutch, Finnish, French,
-German, Hungarian, Italian, Norwegian, Polish, Portuguese, Russian,
-Spanish, Swedish, and Turkish.
+Each of HyperFormula's built-in function names (and [errors](types-of-errors.md)) is available in [17 language versions](localizing-functions.md#list-of-supported-languages).
 
-The package includes localization of function names and error values
-(such as #REF! or #NAME!). To support more languages or properties
-create your own [custom language pack](localizing-functions).
+To support more languages or properties, create a [custom language pack](localizing-functions).
 
 ## Custom functions
 

docs/guide/compatibility-with-google-sheets.md

@@ -66,7 +66,7 @@ Related options:
 
 ### Date and time formats
 
-In Google Sheets, date and time formats depend on the spreadsheet's configured locale and are [shared across all users](https://support.google.com/docs/answer/58515), whereas in HyperFormula you can [set them up freely](date-and-time-handling.md).
+In Google Sheets, date and time formats depend on the spreadsheet's locale and are [shared across all users](https://support.google.com/docs/answer/58515), whereas in HyperFormula you can [set them up freely](date-and-time-handling.md).
 
 Options related to date and time formats:
 - [`dateFormats`](../api/interfaces/configparams.md#dateformats)

docs/guide/date-and-time-handling.md

@@ -7,25 +7,21 @@ The formats for the default date and time parsing functions can be set using con
 
 ## Example
 
-By default, HyperFormula uses European date and time format configuration:
+By default, HyperFormula uses the European date and time formats.
 
 ```javascript
-const options = {
-    dateFormats: ['DD/MM/YYYY', 'DD/MM/YY'], // set by default
-    timeFormats: ['hh:mm', 'hh:mm:ss.sss'], // set by default
-};
+dateFormats: ['DD/MM/YYYY', 'DD/MM/YY'], // set by default
+timeFormats: ['hh:mm', 'hh:mm:ss.sss'], // set by default
 ```
 
-To use the formats popular in the USA, set:
+To use the US date and time formats, set:
 
 ```javascript
-const options = {
-    dateFormats: ['MM/DD/YYYY', 'MM/DD/YY', 'YYYY/MM/DD'], // date formats used in the USA
-    timeFormats: ['hh:mm', 'hh:mm:ss.sss'], // set by default
-};
+dateFormats: ['MM/DD/YYYY', 'MM/DD/YY', 'YYYY/MM/DD'], // US date formats
+timeFormats: ['hh:mm', 'hh:mm:ss.sss'], // set by default
 ```
 
-## Custom functions for handling date and time 
+## Custom date and time handling
 
 HyperFormula offers the possibility to extend the number of supported
 date/time formats as well as the behavior of this functionality by exposing
@@ -45,8 +41,8 @@ library like [Moment.js](https://momentjs.com/), or by writing your
 own custom function that returns a [`DateTime`](../api/globals.md#datetime) object.
 
 The configuration of date formats and stringify options may impact some built-in functions.
-For instance, `VALUE` function transforms strings
-into numbers, which means it uses [`parseDateTime`](../api/interfaces/configparams.md#parsedatetime). `TEXT` function
+For instance, the `VALUE` function transforms strings
+into numbers, which means it uses [`parseDateTime`](../api/interfaces/configparams.md#parsedatetime). The `TEXT` function
 works the other way round - it accepts a number and returns a string,
 so it uses `stringifyDateTime`. Any change here might give you
 different results. Criteria-based functions (`SUMIF`, `AVERAGEIF`, etc.) perform comparisons, so they also need to

docs/guide/importing-files.md docs/guide/file-import.mddocs/guide/importing-files.md renamed to docs/guide/file-import.md

@@ -1,21 +1,24 @@
-# Importing XLSX/CSV files into HyperFormula
+# File import
 
-Use HyperFormula to calculate the formulas exported from other spreadsheets.
+Import XLSX and CSV files into HyperFormula.
 
 ## Overview
 
-HyperFormula itself has no file import functionality. Rather, the [factory methods](../api/classes/hyperformula.md#factories) use standard JavaScript data types for easy integration with any data importing solution.
+HyperFormula has no built-in file import functionality. But its [factory methods](../api/classes/hyperformula.md#factories) use standard JavaScript data types, for easy integration with any way of importing data.
 
-If you want to work with XLSX or CSV files, you can decide to use one of the [file parsing libraries](https://www.npmjs.com/search?q=xlsx) and then pass the result to HyperFormula as a JavaScript array.
-Popular choices include [ExcelJS](https://www.npmjs.com/package/exceljs) or [xlsx](https://www.npmjs.com/package/xlsx) packages for the XLSX file format, and [PapaParse](https://www.npmjs.com/package/papaparse) or [csv-parse](https://www.npmjs.com/package/csv-parse) for the CSV file format.
+## Import CSV files
 
-## Example: Importing XLSX files into HyperFormula in Node
+To import CSV files, use a third-party [CSV parser](https://www.npmjs.com/search?q=csv) (e.g., [PapaParse](https://www.npmjs.com/package/papaparse) or [csv-parse](https://www.npmjs.com/package/csv-parse)). Then pass the result to HyperFormula as a JavaScript array.
 
-This example uses [ExcelJS](https://www.npmjs.com/package/exceljs), but the same feature can be implemented with any other XLSX parsing library.
+## Import XLSX files
 
-::: tip
-The full source code for this example is available on [GitHub](https://github.com/handsontable/hyperformula-demos/tree/2.2.x/read-excel-file)
-:::
+To import XLSX files, use a third-party [XLSX parser](https://www.npmjs.com/search?q=xlsx) (e.g., [ExcelJS](https://www.npmjs.com/package/exceljs) or [xlsx](https://www.npmjs.com/package/xlsx)). Then pass the result to HyperFormula as a JavaScript array.
+
+### Example: Import XLSX files in Node
+
+This example uses [ExcelJS](https://www.npmjs.com/package/exceljs) to import XLSX files into HyperFormula. 
+
+See full example on [GitHub](https://github.com/handsontable/hyperformula-demos/tree/2.2.x/read-excel-file).
 
 ```js
 const ExcelJS = require('exceljs');

docs/guide/i18n-features.md

@@ -0,0 +1,114 @@
+# Internationalization features
+
+Configure HyperFormula to match the languages and regions of your users.
+
+**Contents:**
+[[toc]]
+
+## Function names and errors
+
+Each of HyperFormula's [built-in functions](built-in-functions.md) and [errors](types-of-errors.md) is available in [17 languages](localizing-functions.md#list-of-supported-languages).
+
+You can easily [switch between languages](localizing-functions.md) ([`language`](../api/interfaces/configparams.md#language)).
+
+When adding a [custom function](custom-functions.md), you can define the function's [name](custom-functions.md#_3-add-your-function-s-names) in every language that you support.
+
+To support more languages, add a [custom language pack](localizing-functions.md).
+
+## Date and time formats
+
+To match a region's calendar conventions, you can set multiple date formats ([`dateFormats`](../api/interfaces/configparams.md#dateformats)) and time formats ([`timeFormats`](../api/interfaces/configparams.md#timeformats)).
+
+By default, HyperFormula uses the European date and time formats. [You can easily change them](date-and-time-handling.md#example).
+
+You can also add custom ways of [handling dates and times](date-and-time-handling.md#custom-date-and-time-handling).
+
+## Number format
+
+To match a region's number format, configure HyperFormula's decimal separator ([`decimalSeparator`](../api/interfaces/configparams.md#decimalseparator)) and thousands separator ([`thousandSeparator`](../api/interfaces/configparams.md#thousandseparator)).
+
+By default, HyperFormula uses the European number format (`1000000.00`):
+
+```js
+decimalSeparator: '.', // set by default
+thousandSeparator: '', // set by default
+```
+
+To use the US number format (`1,000,000.00`), set:
+
+```js
+decimalSeparator: '.', // set by default
+thousandSeparator: ',',
+```
+
+::: tip
+  In HyperFormula, both [`decimalSeparator`](../api/interfaces/configparams.md#decimalseparator) and [`thousandSeparator`](../api/interfaces/configparams.md#thousandseparator) must be different from [`functionArgSeparator`](../api/interfaces/configparams.md#functionargseparator).
+  In some cases it might cause compatibility issues with other spreadsheets, e.g., [Microsoft Excel](compatibility-with-microsoft-excel.md#separators) or [Google Sheets](compatibility-with-google-sheets.md#separators).
+:::
+
+## Currency symbol
+
+To match your users' currency, you can configure multiple currency symbols ([`currencySymbol`](../api/interfaces/configparams.md#currencysymbol)).
+
+The default currency symbol is `$`. To add `USD` as an alternative, set:
+
+```js
+currencySymbol: ['$', 'USD'],
+```
+
+## String comparison rules
+
+To make sure that language-sensitive strings are compared in line with your users' language (e.g., `Préservation` vs. `Preservation`), set HyperFormula's [string comparison rules](types-of-operators.md#comparing-strings) ([`localeLang`](../api/interfaces/configparams.md#localelang)).
+
+The value of [`localeLang`](../api/interfaces/configparams.md#localelang) is processed by [`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator), a JavaScript standard object.
+
+The default setting is:
+
+```js
+localeLang: 'en', // set by default
+```
+
+To set the `en-US` string comparison rules, set:
+
+```js
+localeLang: 'en-US',
+```
+
+To further customize string comparison rules, use these options:
+- [`caseSensitive`](../api/interfaces/configparams.md#casesensitive)
+- [`accentSensitive`](../api/interfaces/configparams.md#accentsensitive)
+- [`caseFirst`](../api/interfaces/configparams.md#casefirst)
+- [`ignorePunctuation`](../api/interfaces/configparams.md#ignorepunctuation)
+
+## Compatibility with other spreadsheet software
+
+For information on compatibility with locale-dependent syntax in other spreadsheet software, see:
+- [Compatibility with Microsoft Excel](compatibility-with-microsoft-excel.md)
+- [Compatibility with Google Sheets](compatibility-with-google-sheets.md)
+
+## `en-US` configuration
+
+This configuration aligns HyperFormula with the `en-US` locale. Due to the configuration of [separators](#number-format), it might not be fully compatible with formulas coming from other spreadsheet software.
+
+```js
+language: 'enUS',
+dateFormats: ['MM/DD/YYYY', 'MM/DD/YY', 'YYYY/MM/DD'],
+timeFormats: ['hh:mm', 'hh:mm:ss.sss'], // set by default
+decimalSeparator: '.', // set by default
+thousandSeparator: ',',
+functionArgSeparator: ';', // might cause incompatibility with other spreadsheets
+currencySymbol: ['$', 'USD'],
+localeLang: 'en-US',
+```
+
+## `en-US` demo
+
+This demo shows HyperFormula configured for the `en-US` locale.
+
+<iframe
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.2.x/i18n?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+  title="handsontable/hyperformula-demos: basic-operations"
+  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+  sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
+</iframe>