[localize] Split localize CLI into extract and build commands (lit#1668)

Previously the lit-localize CLI always does both extraction and project building. It's nice to separate these steps, in particular because of the next PR, which directly exposes locale transformers for use with @rollup/plugin-typescript (or other tools).

With this change, running lit-localize extract will generate XLIFF files (translation requests), and then building is done either with lit-localize build or from within a Rollup configuration.

Author: aomarks

packages/localize/CHANGELOG.md

@@ -32,6 +32,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   msg(str`Hello ${name}`);
   ```
 
+- **[BREAKING]** The `lit-localize` CLI now must always take one of two
+  commands: `extract` or `build`. Previously, both of these steps were always
+  performed.
+
 ## [0.6.1] - 2020-12-09
 
 ### Fixed

packages/localize/README.md

@@ -153,10 +153,10 @@ lit-localize supports two output modes: _transform_ and _runtime_.
    }
    ```
 
-5. Run the `lit-localize` CLI:
+5. Run the `lit-localize` CLI with the `extract` command:
 
    ```bash
-   npx lit-localize
+   npx lit-localize extract
    ```
 
 6. Take a look at the generated XLIFF file `xliff/es-419.xlf`. Note that we have
@@ -181,10 +181,10 @@ lit-localize supports two output modes: _transform_ and _runtime_.
    </trans-unit>
    ```
 
-8. Run `lit-localize` again:
+8. Run the `lit-localize` CLI with the `build` command:
 
    ```bash
-   npx lit-localize
+   npx lit-localize build
    ```
 
 9. Now take a look at the generated file `es-419/index.js`:
@@ -511,30 +511,20 @@ In transform mode, applications of the `Localized` mixin are removed.
 
 ## CLI
 
-Running the `lit-localize` command-line program does the following:
+### Usage
 
-1. Reads your [config file](#config-file) according to the `--config` flag.
-
-2. Analyzes all TypeScript files covered by your `tsconfig.json`, and discovers
-   all calls to the `msg` function.
-
-3. Creates or updates an XLIFF (`.xlf`) file for each of your target locales,
-   with a `<source>` tag corresponding to each `msg` call.
-
-4. Reads existing `<target>` tags from existing XLIFF files for each `msg` call.
-
-5. When in _transform_ mode, compiles your TypeScript project for each locale,
-   where all `msg` calls are replaced with the corresponding static, localized
-   version from that locale's XLIFF file.
-
-6. When in _runtime_ mode, generates a `<locale>.ts` file for each locale, which
-   can be dynamically loaded by the `@lit/localize` module.
+```sh
+lit-localize command [--flags]
+```
 
-It takes the following flags:
+| Command   | Description                                                                                                                                                                                                                                                                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `extract` | Extract templates from `msg()` calls across all source files included by your `tsconfig.json`, and create or update XLIFF (`.xlf`) files containing translation requests.                                                                                                                                                                      |
+| `build`   | Read translations and build the project according to the configured mode.<br><br>In _transform_ mode, compile your TypeScript project for each locale, replacing `msg` calls with localized templates.<br><br>In _runtime_ mode, generate a `<locale>.ts` file for each locale, which can be dynamically loaded by the `@lit/localize` module. |
 
 | Flag       | Description                                                                 |
 | ---------- | --------------------------------------------------------------------------- |
-| `--help`   | Display this list of flags.                                                 |
+| `--help`   | Display help about usage.                                                   |
 | `--config` | Path to JSON [config file](#config-file). Defaults to `./lit-localize.json` |
 
 ## Config file

packages/localize/examples/runtime/README.md

@@ -18,10 +18,10 @@ This package demonstrates an application that uses [lit-localize](https://github
 ## Setup
 
 ```bash
-git clone https://github.com/PolymerLabs/lit-localize.git
-cd lit-localize/examples/runtime
+git clone https://github.com/Polymer/lit-next.git
+cd lit-next/packages/localize/examples/transform
 npm install
-npx lit-localize
+npx lit-localize build
 npx tsc
 npx es-dev-server --node-resolve
 ```

packages/localize/examples/runtime/package-lock.json

@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "private": true,
   "scripts": {
-    "build": "rm -rf lib/* && lit-localize && tsc",
+    "build": "rm -rf lib/* && lit-localize build && tsc",
     "serve": "es-dev-server --node-resolve --preserve-symlinks"
   },
   "dependencies": {

packages/localize/examples/runtime/package.json

@@ -13,10 +13,10 @@ mode.
 ## Setup
 
 ```bash
-git clone https://github.com/PolymerLabs/lit-localize.git
-cd lit-localize/examples/transform
+git clone https://github.com/Polymer/lit-next.git
+cd lit-next/packages/localize/examples/transform
 npm install
-npx lit-localize
+npx lit-localize build
 npx es-dev-server --node-resolve
 ```
 

packages/localize/examples/transform/README.md

@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "private": true,
   "scripts": {
-    "build": "rm -rf lib/* && lit-localize",
+    "build": "rm -rf lib/* && lit-localize build",
     "serve": "es-dev-server --node-resolve --preserve-symlinks"
   },
   "dependencies": {