Merge pull request #22 from DHTMLX/formulas-descriptions-popup-4885

[update] add sections for popup with formula description into related guides

Author: mafanya23

docs/assets/formula_popup.png

@@ -1311,9 +1311,17 @@ Check the example in our [snippet tool](https://snippet.dhtmlx.com/wux2b35b).
 
 ## Getting cell formula
 
-Starting with v4.1, you can get the formula applied to a cell via the [getFormula()](api/spreadsheet_getformula_method.md) method. The method takes the id of the cell as a parameter:
+Starting with v4.1, you can get the formula applied to a cell via the [`getFormula()`](api/spreadsheet_getformula_method.md) method. The method takes the id of the cell as a parameter:
 
-```js
+~~~js
 var formula = spreadsheet.getFormula("B2");
 // -> "ABS(C2)"
-```
+~~~
+
+## Popup with formula description
+
+When you enter a formula, a popup with description of the function and its parameters appears. 
+
+![Popup with formula description](assets/formula_popup.png)
+
+You can modify the default locale for the popup with formula parameters and add a custom locale. Check the details in the [Localization](localization.md/#default-locale-for-formulas) guide.

docs/functions.md

@@ -27,7 +27,7 @@ const en = {
     italic: "Italic",
     underline: "Underline",
     strikethrough: "Strikethrough",
-    
+
     link: "Link",
 
     halign: "Horizontal align",
@@ -53,11 +53,24 @@ const en = {
 
     columns: "Columns",
     rows: "Rows",
-    addColumn: "Add column",
+    addColumn: "Add column left",
     removeColumn: "Remove column",
     fitToData: "Fit to data",
-    addRow: "Add row",
+    addRow: "Add row above",
     removeRow: "Remove row",
+    row: "row",
+    col: "col",
+    freeze: "Freeze",
+    freezeToCol: "Freeze up to column {col}",
+    freezeToRow: "Freeze up to row {row}",
+    unfreezeRows: "Unfreeze rows",
+    unfreezeCols: "Unfreeze columns",
+    hideCol: "Hide column {col}",
+    hideCols: "Hide columns {col}",
+    showCols: "Show columns",
+    hideRows: "Hide rows {row}",
+    hideRow: "Hide row {row}",
+    showRows: "Show rows",
 
     format: "Format",
     common: "Common",
@@ -72,6 +85,22 @@ const en = {
 
     help: "Help",
 
+    custom: "Custom",
+
+    border: "Border",
+    border_all: "All borders",
+    border_inner: "Inner borders",
+    border_horizontal: "Horizontal borders",
+    border_vertical: "Vertical borders",
+    border_outer: "Outer borders",
+    border_color: "Border color",
+    border_left: "Left border",
+    border_top: "Top border",
+    border_right: "Right border",
+    border_bottom: "Bottom border",
+    border_clear: "Clear borders",
+    border_style: "Border style",
+
     // Tabbar
     deleteSheet: "Delete",
     renameSheet: "Rename",
@@ -91,15 +120,16 @@ const en = {
     ascSort: "Sort A to Z",
     descSort: "Sort Z to A",
 
-    // Actions
+    //Actions
     copy: "Copy",
     edit: "Edit",
     insert: "Insert",
     remove: "Remove",
     linkCopied: "Link copied to clipboard",
 
-    // Filter 
-    e:"Is empty",
+
+    //filter
+    e: "Is empty",
     ne: "Is not empty",
     tc: "Text contains",
     tdc: "Text doesn't contain",
@@ -114,17 +144,18 @@ const en = {
     lt: "Less than",
     leq: "Less or equal to",
     eq: "Is equal to",
-    neq:"Is not equal to",
+    neq: "Is not equal to",
     ib: "Is between",
     inb: "Is not between",
 
     none: "None",
-    empty: "Empty",
     value: "Value",
     values: "By values",
     condition: "By condition",
     and: "And",
 
+    blank: "(Blank)",
+
     // Buttons
     cancel: "Cancel",
     save: "Save",
@@ -142,14 +173,115 @@ const en = {
     spanPasteError: "You can't paste merges that cross the boundary of a frozen region",
     spanMergeLockedError: "You can't merge locked cells!",
     spanUnmergeLockedError: "You can't unmerge locked cells!",
+    spanOverFilteredRow: "You can't merge cells over a filtered row.",
+    removeAlert: "You can't remove last $name!",
 };
 ~~~
 
 ## Custom locale
 
 To apply a different locale you need to:
 
-- provide translation for all text labels in Spreadsheet, e.g. the Russian locale looks like this
-- apply the new locale by calling the **dhx.i18n.setLocale()** method before initializing Spreadsheet
+- provide translations for all text labels in Spreadsheet, e.g. for the Russian locale:
+
+~~~jsx
+const ru = {
+    // language settings
+};
+~~~
+
+- apply the new locale by calling the `dhx.i18n.setLocale()` method before initializing Spreadsheet:
+
+~~~jsx
+dhx.i18n.setLocale("spreadsheet", ru);
+const spreadsheet = new dhx.Spreadsheet("spreadsheet_container");
+~~~
+
+## Default locale for formulas
+
+The i18n locale for the Spreadsheet popup with formulas is contained in the `dhx.i18n.formulas` object. The default locale for formulas is the following:
+
+~~~jsx
+const en = {
+    SUM: [
+        [
+            "Number1",
+            "Required. The first value to sum."
+        ],
+        [
+            "Number2",
+            "Optional. The second value to sum."
+        ],
+        [
+            "Number3",
+            "Optional. The third value to sum."
+        ]
+    ],
+    AVERAGE: [
+        [
+            "Number1",
+            "Required. A number or cell reference that refers to numeric values."
+        ],
+        [
+            "Number2",
+            "Optional. A number or cell reference that refers to numeric values."
+        ]
+    ],
+    // more formulas' descriptions
+};
+~~~
+
+You can check the full default locale for formulas in the [HTML tab of the related snippet](https://snippet.dhtmlx.com/yn5hyyim).
+
+## Custom locale for formulas
+
+To apply a custom locale for Spreadsheet formulas, you need to use the `dhx.i18n.setLocale()` method in the following way:
+
+~~~jsx
+dhx.i18n.setLocale(
+    "formulas", 
+    locale: {   
+        // the structure of the formulas in the locale
+        name: [param: string, description: string][]
+    }
+): void;
+~~~
+
+You should pass the following parameters to the method:
+
+<table>
+    <tbody>
+        <tr>
+            <td><b>Parameter</b></td>
+            <td align="center"><b>Description</b></td>
+        </tr>
+        <tr>
+            <td>"formulas"</td>
+            <td>(*required*) the name of the locale for formulas</td>
+        </tr>
+        <tr>
+            <td>locale</td>
+            <td>(*required*) the locale object that contains formulas' descriptions as <i>key:value</i> pairs, where:<ul><li>the <b>key</b> is the name of the function</li><li>the <b>value</b> is an array of parameters the function takes. Each parameter of the function is an array of two elements, where:<ul><li>the first element is the name of the parameter</li><li>the second element is the description of the parameter</li></ul></li></ul></td>
+        </tr>
+    </tbody>
+</table>
+
+Check the example below:
+
+~~~jsx
+const de = {
+    AVERAGE: [
+        ["Zahl1", "Erforderlich. Eine Zahl oder Zellreferenz, die sich auf numerische Werte bezieht."],
+        ["Zahl2", "Optional. Eine Zahl oder Zellreferenz, die auf numerische Werte verweist."]
+    ],
+    // other formulas' descriptions
+};
+
+dhx.i18n.setLocale("formulas", de);
+~~~
+
+## Example
+
+In this snippet you can see how to switch between locales:
 
 <iframe src="https://snippet.dhtmlx.com/yn5hyyim?mode=js" frameborder="0" class="snippet_iframe" width="100%" height="500"></iframe>