npm package: @nexusui/scripts
Description: nexus scripts
Latest version: 0.0.8

# NexusUI Scripts

This package includes NexusUI scripts. Currently only localization related scripts are included.

## Installation

Add the library as a `devDependency` to your project:

```
# With yarn
yarn add @nexusui/scripts -D

# With npm
npm install @nexusui/scripts --save-dev
```

## Usage

### Localization script

Details about working with the localization scripts are provided below. Also you can get detail steps about [working with the translation service](https://hexmet.sharepoint.com/sites/MIDesign/SitePages/Localization-Working-with-the-Translation-Service.aspx)

#### 1) Configuration and preparation
  * Add the following two scripts to your package.json
    ```
    "scripts": {
      "locales-init": "nexus-localize init",
      "locales-translate": "nexus-localize translate --key FULL-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX"
    }
    ```
  * Replace the sample --key with a `FULL key` provided by Language Wire (LW).
  * Run the `locales-init` script once. You can then delete it from your script list. The script will generate the `locales` folder in the `src` directory and include the `de-DE.json`, `en-GB.json`, `en-US.json`, `fr-FR.json`, `it-IT.json`, `es-ES.json`, `pt-BR.json`, `zh-CN.json`, `zh-TW.json`, `ja.json`, `ko.json` and `project.json`  files.
  * Update the title and purchaseOrderNumber in `src/locales/project.json` with your team's information. Include your team/project name in the title and include submitter/approver in the briefing. Change the `targetLanguages` you want to support.
  * Examples:
  
    `project.json` for **Blue Jays Team**, supporting **10** target languages. 
    ```
    {
      "title": "[Blue Jays] - Nexus SDC App Translation",
      "briefing": "[Blue Jays] - Nexus SDC App | Jaime Lannister - approver| Cersei Lannister - submitter",
      "purchaseOrderNumber": "BlueJays-Order-123456",
      "targetLanguages": [
        "en-GB",
        "de-DE",
        "fr-FR",
        "it-IT",
        "es-ES",
        "pt-BR",  
        "zh-CN",
        "zh-TW",
        "ko",
        "ja"
      ]
    }
    ```

    `project.json` for **Avalanche Team** , supporting **17** target languages. 
    ```
    {
      "title": "[Avalanche] - Nexus Metrology Reporting App Translation",
      "briefing": "[Avalanche] - Nexus SDC App | Jaime Lannister - approver| Cersei Lannister - submitter",
      "purchaseOrderNumber": "Avalanche-Order-123456",
      "targetLanguages": [
        "en-GB",
        "de-DE",
        "fr-FR",
        "it-IT",
        "es-ES",
        "pt-BR",
        "pl",
        "sv-SE",
        "nl-NL",
        "tr",
        "cs",
        "hu",
        "ru",
        "zh-CN",
        "zh-TW",
        "ko",
        "ja"
      ],
    }
    ```


#### 2) Update the `en-US.json` resource file with your resource strings
  * Example `en-US.json`
    ```  
    {
      "hello": "Hello",
      "welcomeNexus": "Hello, welcome to {{0}} project."
    }
    ```

#### 3) Send your updated `en-US.json` to Language Wire
  * Run the command `npm run locales-translate` or `yarn locales-translate`
  * The script will deliver your `en-US.json` file to the Language Wire (LW) service, and auto update `project.json` file.

#### 4) Commit your changes
  * The file submission to Language Wire will trigger a quote creation. Once the quote is approved the translation will begin. This means that you will not get translated files back immediately. Commit all of your file changes in the `locales` folder to your repo, especially the `project.json` since it stores the service credentials for your request. 
  Example `project.json` file：

    ```
    {
      "briefing": "[Blue Jays] - Nexus SDC App | Jaime Lannister - approver| Cersei Lannister - submitter",
      "correlationId": "XXXXXXXXX",
      "deadline": "2022-08-01T06:30:00Z",
      "invoicingAccount": 143778,
      "isDemo": false,
      "product": 27,
      "purchaseOrderNumber": "BlueJays-Order-123456",
      "sourceDocuments": [15411744],
      "targetLanguages": [
        "en-GB",
        "de-DE",
        "fr-FR",
        "it-IT",
        "es-ES",
        "pt-BR",  
        "zh-CN",
        "zh-TW",
        "ko",
        "ja"
      ],
      "terminology": 95388,
      "title": "[Blue Jays] - Nexus SDC App Translation",
      "workArea": 80
    }
    ```

#### 5) Retrieve localized files and update local resource files
  * Once LW has translated the files you can retrieve the files by running the translate script again `npm run locales-translate` or `yarn locales-translate`. The script will request the files from LW and update the local language files (`en-GB.json` `de-DE.json` `fr-FR.json` `it-IT.json`, `es-ES.json`, `pt-BR.json`, `zh-CN.json`, `zh-TW.json`, `ko.json`, `ja.json`) and `project.json`. Then commit all the files update to your repo. If LW has not completed the translation request, the response message will indicate that the request is still in progress. 

#### 6) Requesting translations
  * Anytime you want to request a translation, just repeat steps 3, 4, and 5 above. You can run the translate script anytime and it will first check the last response and then send the next request, without any negative side effects.


#### Script parameters

* `nexus-localize init` 

  |  Parameter        | Default        |Required        |
  |  ----             | ----           |----            |
  |  --localesDir     | src/locales    |false           |
  
  - The default location for the `locales` folder is under `src`. If you would prefer to specify a custom location you can use the `--localesDir` parameter to specify the location.
    ```
    nexus-localize init --localesDir \"utils/locales\"
    ```
  
* `nexus-localize translate`

  |  Parameter        | Default        |Required        |Comments                                        |
  |  ----             | ----           |----            |----                                            |
  |  --key            |                |true            |languageWire key                                |
  |  --localesDir     | src/locales    |false           |locales dir                                     |
  |  --sourceLanguage | en-US          |false           |source language you prefer                      |
  |  --expiryDurationDays | 15         |false           |expiry duration days **(Worked from v0.03)**    |

  - You must provide a full Language Wire key for your application. 
    ```
    nexus-localize translate --key FULL-XXXXXXXX-XXXX-XXXX-A117-0E0D01398971
    ```

  - If you defined a custom location for your `locales` folder, meaning it is not under the `src` directory, then you need to specify that location by using the parameter `--localesDir`.
    ```
    nexus-localize translate --key FULL-XXXXXXXX-XXXX-XXXX-A117-0E0D01398971 --localesDir \"src/utils/locales\"
    ```

  - The default source language is `en-US`.  If your initial development language is another language, you can use the `--sourceLanguage` parameter to set the source file language to that language. The script will then send that language resource file to Language Wire, and retrieve the response for all other resource files. Below is an example specifying that the source language is German. This example would send the `de-DE.json` file to Language Wire.
    ```
    nexus-localize translate --key FULL-XXXXXXXX-XXXX-XXXX-A117-0E0D01398971 --sourceLanguage=de-DE
    ```

  - The default deadline is 15 days later. If you want to change to 10 days, you can use `--expiryDurationDays` parameter to set the expiry duration days. 
    ```
    nexus-localize translate --key FULL-XXXXXXXX-XXXX-XXXX-A117-0E0D01398971 --expiryDurationDays=10
    ```