@uitranslator/cli/README.md

The UI Translator npm cli

# The UI Translator CLI
This tool is the midle man between developer setups and the UI Translator platform.

It's role consist of pushing all the content updates made on the developer's side to the UI Translator so that content professionals can take action on it.

## Summary
To get you started with the UI Translator, let's explore:

[1. Opening an account on the UI Translator](#1-open-an-account-on-the-ui-translator)

[2. Installing the UI Translator CLI](#2-install-the-ui-translator-cli-using-npm)

[3. Setting up the project](#3-setup-the-ui-translator-cli-on-your-project)

[4. Syncing the project local content](#4-sync-your-content)

[5. Testing the local content release readiness](#5-test-your-content)

[6. Release the local content](#6-release-the-content)

[7. Important notes not to be skipped](#7-important-notes)

## 1. Open an account on the UI Translator
To manage a project on the UI Translator, you will first need to create it. To do that, you need to create an account on the UI Translator using the web app.

Follow the steps below:

- Using your browser, open the UI Translator web app at https://app.uitranslator.com  

- Next, create a project  
This will open the project empty state with several source content onboarding options. we will get back to it to setup the CLI

## 2. Install the UI Translator CLI using npm
Because the UI Translator CLI is a node program, you will need to have [npm](https://npmjs.org) installed on your computer to proceed  
```shell
npm install -g @uitranslator/cli 
```

Verify the installation by issuing the command
```shell
uit
```
You should get the result below.
![UIT CLI Welcome screen](uit_welcome_page.png)

## 3. Setup the UI Translator CLI on your project
To let the CLI know which project on the UI Translator to link with and how to do that, you will follow an interractive setup.


- First, move the terminal working directory to your local project root folder.

`Example`:
```shell
cd your_project_folder_path
```

- Next, start the setup with the command:
```shell
uit setup
```
Fill the required informations(`your token` and the `project ID`), you can find this informations on the project empty page created at the step `1`, click on the `LINK YOUR DEVELOPMENT SETUP` button to reveal them.

## 4. Sync your content
Once your setup done, you will get a prompt from the CLI letting you know that you can sync or watch your content.

- Prefer the `watch` command to follow up on your content changes if you use the `manual method` and the `sync` command if you use the `automatic method`.
- Issue the chosen command
```shell
uit sync
```

You should see your content appear on the UI Translator dashboard!
It's know up to you to add the marketing/product team there so they can do whatever they want with that content.   

## 5. Test your content  
Once you sync the content, other content players in the team can take control over it and ammend it, or even add new translations.  
To make sure their changes don't break the layout, you can use the test command. It will let you know for every locale its release readiness(how ready that content is to be released).  
- You may check all the available translations at once with the special `all` locale code.  
- The source content is synced on every `sync` command but you can also test it with the `test command` by omitting the `locale` flag.
```shell
uit test --locale locale_code
```
Example:
```shell
uit test --locale fr
```
To test the French content.

## 6. Release the content
When you are ready to release that new feature of your software, you can check if it's corresponding content is ready with the `uit test -l all` command and if it is you can go on and release the content with:

```shell
uit release
``` 
You can add this command to your release tasks pipe line to always make sure that you have the content ready.


## 7. Important notes

### Content updated on sync
Every time you run `sync` your newly added content will be sent to the UIT dashboard and the updates made there will be sent back to you locally so you.

### Draft vs Source content file
Since the UI Translator does not allow releasing missing content, the difference between those files is that the source content file can not hold empty messages while the draft file can. So the source file contains all the messages from the draft that are not empty.

### Content not ready alert
Whenever the release command fails, the UI Translator creates a `Release candidate` with that content and alerts all the people involved about a `Content not ready` issue so that they can sort it in top priority.


### UI Translator is a localization(l10n) ~~internationalization (i18n)~~ tool
 Please keep in mind that you need to do the internationalization on your code, the UI Translator does not touch it or your framework configuration.  
 It helps you get the your CONTENT localized. You should first go through the i18n process and generate a source content before the UI Translator can do its thing.  

 ### The UI Translator is framework agnostic
 Whatever tools you use in your development, if you can internationalize(i18n), then the UI Translator can localize(l10n)! your content.

 ### Automatic vs Mannual extraction: choose ONE!
 `Automatic` or `Manual` content extraction method selected during the CLI setup function very differently.
 The recommended method is the `Automatic` which really free developers from any extra content work. However, you should make sure when you pick it that **ALL YOUR CONTENT IS AUTOMATICALLY EXTRACTABLE** if you can not fullfill that constraint, choose the `Manual` method, which basically means that the CLI will rely in what you put in the content draft.