Sara|Hojjat / update readme (binary-com#6699)

* docs: update readme structure

* docs: update scripts doc

* docs: update other docs

* docs: update node version recommendation

* docs: update preview link

README.md

@@ -1,110 +1,164 @@
-Binary-Static 
-=============
+# Binary-Static
 
 This repository contains the static HTML, Javascript, CSS, and images content of the [Binary.com](http://www.binary.com) website.
 
-## Installation
+![build](https://img.shields.io/circleci/build/github/binary-com/binary-static) ![node](https://img.shields.io/badge/node-%3E%3D12.22.3-blue.svg) ![npm](https://img.shields.io/badge/npm-%3E%3D6.14.13-blue.svg) ![sass](https://img.shields.io/badge/Sass-CC6699?style=flat&logo=sass&logoColor=white)
 
-In order to work on your own version of the Binary.com Javascript and CSS, please **fork this project**.
+**In this document**
 
-You will also need to install the following on your development machine:
+- [Other Documents](#other-documents)
+- [Pre-installation](#pre-installation)
+- [Preview on your local machine](#preview-on-your-local-machine)
+- [Test link deployment](#test-link-deployment)
+- [Manage releases](#manage-releases)
+
+## Other Documents
+
+- [Scripts](scripts/README.md)
+- [Javascript](src/javascript/README.md)
+- [Sass](src/sass/README.md)
+- [Templates](src/templates/README.md)
+
+## Pre-installation
+
+Before running or contribute to this project, you need to have the setup of the following packages in your environment
 
 - Ruby, RubyGems
 - Sass (`sudo gem install sass`)
-- Node.js (10.14.2 or higher is recommended) and NPM (see <https://nodejs.org/en/download/package-manager/>)
-- Go to project root, then run `npm install`
+- Node.js (12.22.3 is recommended)
+- NPM (see <https://nodejs.org/en/download/package-manager/>)
 - Grunt (`sudo npm install -g grunt-cli`)
 
-### Use a custom domain
-In order to use your custom domain, please put it in a file named `CNAME` inside `scripts` folder of your local clone of binary-static.
+## Quickstart
+
+1.  **Fork the project**
+
+    In order to work on your own version of the Binary.com application, please fork the project to your own repo.
+
+2.  **Clone using SSH**
+
+    ```sh
+    git clone [email protected]:your-github-username/binary-com.git
+    ```
+
+3.  **Enter project directory**
+
+    ```sh
+    cd binary-com
+    ```
+
+4.  **Install your dependencies:**
 
+    ```sh
+    npm ci
+    ```
 
-How to work with this project
-=============================
+5.  **To start developing:**
 
-## Test link deployments
+    ```sh
+    npm run start
+    ```
+
+6.  **Open the source code and start editing!**
+
+    Your site is now running at [https://localhost:443](https://localhost:443)
+
+## Preview on your local machine
+
+- To preview your changes locally, run `sudo grunt serve`
+- It will watch for Javascript or CSS changes and will rebuild on every change you make.
+- To test changes made to templates, you need to re-compile them:
+  - `grunt shell:compile_dev` to re-compile all templates.
+  - `grunt shell:compile_dev --path=about-us` to re-compile only template(s) which serve about-us path in URL.
+- To fix eslint errors run `npm run eslint`
+
+## Test link deployment
 
 There are two types of test link deployment preview:
 
 1. Automatic deployment
 
-Upon creating PR, `vercel` (https://vercel.com/) will auto-generate test link inside the PR. you can use that to preview test link for the changes you have made.
+Upon creating PR, `Vercel` (https://vercel.com/) will auto-generate the test link inside the PR. you can use that to preview the test link for the changes you have made.
 
 2. Manual deployments
 
 You can manually deploy your test link using gh-pages with the following configurations:
+
 ### Deploy to your gh-pages for the first time
 
-1. Register your application [here](https://developers.binary.com/applications/). This will give you the ability to redirect back to your github pages after login.
-Use `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/logged_inws.html` for the Redirect URL and `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/redirect.html` for the Verification URL.
+1.  Register your application [here](https://developers.binary.com/applications/). This will give you the ability to redirect back to your Github pages after login.
+    Use `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/logged_inws.html` for the Redirect URL and `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/redirect.html` for the Verification URL.
 
-    If you're using a custom domain, replace the github URLs above with your domain.
+        If you're using a custom domain, replace the Github URLs above with your domain.
 
-2. In `src/javascript/config.js`: Insert the `Application ID` of your registered application in `user_app_id`.
-  * **NOTE:** In order to avoid accidentally committing personal changes to this file, use `git update-index --assume-unchanged src/javascript/config.js`
+2.  In `src/javascript/config.js`: Insert the `Application ID` of your registered application in `user_app_id`.
 
-3. Run `grunt dev`
+- **NOTE:** In order to avoid accidentally committing personal changes to this file, use `git update-index --assume-unchanged src/javascript/config.js`
 
+3. Run `grunt dev`
 
 ### Deploy js/css and template changes together
 
-```
+```sh
 grunt dev
 ```
 
-
 ### Deploy only js/css changes
 
-```
+```sh
 grunt deploy
 ```
 
-
 ### Deploy some template changes
 
-```
+```sh
 grunt dev --path=about-us
 ```
 
-
 ### Using sub-folders
+
 There are times that you are working on various branches at the same time, and you want to deploy/test each branch separately on your gh-pages, you can simply use `--branch=branchname` for grunt commands:
+
 - `grunt dev --branch=branchname`
-This will deploy your changes to a sub-folder named: `br_branchname` and it can be browsed at: https://YOUR_GITHUB_USERNAME.github.io/binary-static/br_branchname/
+  This will deploy your changes to a sub-folder named: `br_branchname` and it can be browsed at: https://YOUR_GITHUB_USERNAME.github.io/binary-static/br_branchname/
 
 In order to remove the created folders from your gh-pages, you can use either:
+
 - `grunt dev --cleanup`: removes all `br_*` folders and deploys to the root folder.
 
   or
+
 - `grunt shell:remove_folder --folder=br_branchname1,br_branchname2,...`: only removes the specified folder(s) from your gh-pages.
 
   or
+
 - `grunt shell:remove_folder --keep --folder=br_branchname1,br_branchname2,...`: only keeps the specified folder(s) on your gh-pages and removes everything else. Just add the `--keep` flag.
 
-## Preview on your local machine
-- To preview your changes locally, run `sudo grunt serve`
-- It will watch for js/css changes and rebuild on every change you make.
-- To test changes made to templates, you need to re-compile them:
-  - `grunt shell:compile_dev` to re-compile all templates.
-  - `grunt shell:compile_dev --path=about-us` to re-compile only template(s) which serve about-us path in URL.
-- To fix eslint errors run `npm run eslint`
+### Use a custom domain
 
-## Release
+In order to use your custom domain, please put it in a file named `CNAME` inside `scripts` folder of your local clone of binary-static.
 
-```
+## Manage releases
+
+```sh
 git tag ${RELEASE_TARGET}_vYYYYMMDD_${INTEGER} -m 'some message'
 ```
 
 > `RELEASE_TARGET` could be one of **staging** or **production** for staging and production release respectively.
 
-Example: 
+Example:
 
-```
+```sh
 git tag production_v20191010_0 -m 'release fixes to production'
 ```
 
 Push the tag:
 
-```
+```sh
 git push origin staging_v20191010_0
 ```
+
+## Manage translations
+
+- Automatic: this will be done automatically with [Github action](.github/workflows/sync_crowdin_translations.md)
+- Manual: If you need to add translation manually use [manual translation doc](scripts/README.md#Updating-the-translations)

scripts/README.md

@@ -1,54 +1,67 @@
+# Scripts
+
+**In this documents**
+
+- [Updating the Translations](#updating-the-translations)
+- [Updating the Sitemap](#updating-the-sitemap)
+
 ## Updating the Translations
 
 ### Initial setup:
-* Please make sure you have done `npm install`.
-* Install `Homebrew` by `ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
-* Install and follow the instructions here: https://support.crowdin.com/cli-tool/#installation
-* **Important:** Please use version 3 of the crowdin cli-tool
-* Get [Crowdin API Key](https://crowdin.com/project/binary-static/settings#api) and add this line to your _.bash_profile_: `export CROWDIN_API_KEY='put API Key here'`<br/>
-**IMPORTANT!** This key gives full access to all your Crowdin project data. Treat this just like a password and never push it to any public repo.
+
+- Please make sure you have done `npm install`.
+- Install `Homebrew` by `ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
+- Install and follow the instructions here: https://support.crowdin.com/cli-tool/#installation
+- **Important:** Please use version 3 of the crowdin cli-tool
+- Get [Crowdin API Key](https://crowdin.com/project/binary-static/settings#api) and add this line to your _.bash_profile_: `export CROWDIN_API_KEY='put API Key here'`<br/>
+  **IMPORTANT!** This key gives full access to all your Crowdin project data. Treat this just like a password and never push it to any public repo.
 
 ### To update the translations:
-* Simply run `./scripts/update_translations.sh` in root folder of project to do these tasks:<br/>
-(It is possible to confirm/skip each task by answering y/n to questions, only first one is mandatory):
-  * Check out and update the translations branch
-  * Update master and merge into translations
-  * Update the source file (messages.pot) and push to Crowdin
-  * Download translation files from Crowdin to `src/translations` and update javascript texts `src/javascript/_autogenerated/[LangCode].js`
-  * Commit changes and push to origin
-  * Open github to submit the PR
+
+- Simply run `./scripts/update_translations.sh` in root folder of project to do these tasks:<br/>
+  (It is possible to confirm/skip each task by answering y/n to questions, only the first one is mandatory):
+  - Check out and update the translations branch
+  - Update master and merge into translations
+  - Update the source file (`messages.pot`) and push it to Crowdin
+  - Download translation files from Crowdin to `src/translations` and update javascript texts `src/javascript/_autogenerated/[LangCode].js`
+  - Commit changes and push to origin
+  - Open Github to submit the PR
 
 ### Extracting texts from js code:
+
 Texts that are used in js code will automatically be extracted during the translation update process (3rd step above: Updating the source file).
 
 In order to make sure that no strings are missed by the extractor code while pushing to translations, please:
 
 1. Refactor the code so that the first argument passed to the `localize()` method is a string literal.
-    i.e.
-    ```js
-    const text = localize(is_started ? 'Sell at market' : 'Sell');
-    ```
-    would change to:
-    ```js
-    const text = is_started ? localize('Sell at market') : localize('Sell');
-    ```
+   i.e.
+   ```js
+   const text = localize(is_started ? 'Sell at market' : 'Sell');
+   ```
+   would change to:
+   ```js
+   const text = is_started ? localize('Sell at market') : localize('Sell');
+   ```
 2. If there is no way to have the string literal in js code (i.e. API texts which are not translated), add them to `scripts/js_texts/static_strings_app.js`.
 
-    Note: Regarding API texts, even if the string is translated automatically somewhere else we should still include it here to avoid missing it if that other string gets removed.
+   Note: Regarding API texts, even if the string is translated automatically somewhere else we should still include it here to avoid missing it if that other string gets removed.
 
 3. At the end, when you're sure that a string has already been taken care of, just put this comment `/* localize-ignore */` right after the first argument of `localize()` call to ignore it from tests.
 
 ### `js_texts` folder contents:
+
 ```
 js_texts:
     ├── extracted_strings_app.js
     └── static_strings_app.js
 ```
-- `extracted_strings_app.js`: Contains extracted strings. It's for debugging purpose only and shouldn't be changed manually.
+
+- `extracted_strings_app.js`: Contains extracted strings. It's for debugging purposes only and shouldn't be changed manually.
 - `static_strings_app.js` to handle those strings that don't exist in js code. e.g. API texts that are not localised, etc.
 
 During the translation update process, the source file `messages.pot` will be updated with all texts from both the above files.
 
 ## Updating the Sitemap
-* List of paths to include in `sitemap.xml` is here: [config/sitemap_urls.js](config/sitemap_urls.js)
-* Once the paths are updated in the above file, run `./scripts/sitemap.js` or `grunt shell:sitemap` to generate new `sitemap.xml` files in `src/root_files` according to each section.
+
+- The list of paths to include in `sitemap.xml` is here: [config/sitemap_urls.js](config/sitemap_urls.js)
+- Once the paths are updated in the above file, run `./scripts/sitemap.js` or `grunt shell:sitemap` to generate new `sitemap.xml` files in `src/root_files` according to each section.