[localize] New msg signature with options object (lit#1442)

Changes the lit-localize msg signature, the first step in adding support for automatic localize message IDs (lit#1437).

Before:

msg(id: string, template: string|TemplateResult|Function, ...args: any[])
After:

msg(template: string|TemplateResult|Function, options: {id: string: args?: any[]})
In the next PR, id will become optional.

Also fixes the json-schema build issue.

Author: aomarks

packages/localize/CHANGELOG.md

@@ -5,7 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-<!-- ## Unreleased -->
+## Unreleased
+
+### Changed
+
+- **[BREAKING]** The signature for the `msg` function has changed:
+
+  Before:
+
+  ```ts
+  msg(id: string, template: string|TemplateResult|Function, ...args: any[])
+  ```
+
+  After:
+
+  ```ts
+  msg(template: string|TemplateResult|Function, options: {id: string: args?: any[]})
+  ```
 
 ## [0.5.1] - 2020-11-09
 

packages/localize/README.md

@@ -33,7 +33,7 @@ Wrap your template with the `msg` function to make it localizable:
 ```typescript
 import {html} from 'lit-html';
 import {msg} from '@lit/localize';
-render(msg('greeting', html`Hello <b>World</b>!`), document.body);
+render(msg(html`Hello <b>World</b>!`, {id: 'greeting'}), document.body);
 ```
 
 Run `lit-localize` to extract all localizable templates and generate an XLIFF
@@ -130,7 +130,7 @@ lit-localize supports two output modes: _transform_ and _runtime_.
    import {msg} from '@lit/localize';
 
    render(
-     html`<p>${msg('greeting', html`Hello <b>World</b>!`)}</p>`,
+     html`<p>${msg(html`Hello <b>World</b>!`, {id: 'greeting'})}</p>`,
      document.body
    );
    ```
@@ -216,8 +216,7 @@ The `@lit/localize` module exports the following functions:
 > signatures to identify calls to `msg` and other APIs during analysis of your
 > code. Casting a lit-localize function to a type that does not include its
 > annotation will prevent lit-localize from being able to extract and transform
-> templates from your application. For example, a cast like
-> `(msg as any)("greeting", "Hello")` will not be identified. It is safe to
+> templates from your application. For example, a cast like `(msg as any)("Hello", {id: "greeting"})` will not be identified. It is safe to
 > re-assign lit-localize functions or pass them as parameters, as long as the
 > distinctive type signature is preserved. If needed, you can reference each
 > function's distinctive type with e.g. `typeof msg`.
@@ -324,46 +323,49 @@ promise resolves.
 Throws if the given locale is not contained by the configured `sourceLocale` or
 `targetLocales`.
 
-### `msg(id: string, template, ...args) => string|TemplateResult`
+### `msg(template: string|TemplateResult|Function, options: {id: string, args?: any[]}) => string|TemplateResult`
 
 Make a string or lit-html template localizable.
 
-The `id` parameter is a project-wide unique identifier for this template.
+The `options.id` parameter is a project-wide unique identifier for this template.
 
 The `template` parameter can have any of these types:
 
 - A plain string with no placeholders:
 
   ```typescript
-  msg('greeting', 'Hello World!');
+  msg('Hello World!', {id: 'greeting'});
   ```
 
 - A lit-html
   [`TemplateResult`](https://lit-html.polymer-project.org/api/classes/_lit_html_.templateresult.html)
   that may contain embedded HTML:
 
   ```typescript
-  msg('greeting', html`Hello <b>World</b>!`);
+  msg(html`Hello <b>World</b>!`, {id: 'greeting'});
   ```
 
 - A function that returns a [template
   literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
   string that may contain placeholders. Placeholders may only reference
-  parameters of the function, which will be called with the 3rd and onwards
-  parameters to `msg`.
+  parameters of the function. The function will be invoked with the
+  `options.args` array as its parameters:
 
   ```typescript
-  msg('greeting', (name) => `Hello ${name}!`, getUsername());
+  msg((name) => `Hello ${name}!`, {id: 'greeting', args: [getUsername()]});
   ```
 
 - A function that returns a lit-html
   [`TemplateResult`](https://lit-html.polymer-project.org/api/classes/_lit_html_.templateresult.html)
   that may contain embedded HTML, and may contain placeholders. Placeholders may
-  only reference parameters of the function, which will be called with the 3rd
-  and onwards parameters to `msg`:
+  only reference parameters of the function. The function will be invoked with
+  the `options.args` array as its parameters:
 
   ```typescript
-  msg('greeting', (name) => html`Hello <b>${name}</b>!`, getUsername());
+  msg((name) => html`Hello <b>${name}</b>!`, {
+    id: 'greeting',
+    args: [getUsername()],
+  });
   ```
 
 In transform mode, calls to this function are replaced with the static localized
@@ -465,7 +467,7 @@ class MyElement extends Localized(LitElement) {
   render() {
     // Whenever setLocale() is called, and templates for that locale have
     // finished loading, this render() function will be re-invoked.
-    return html`<p>${msg('greeting', html`Hello <b>World!</b>`)}</p>`;
+    return html`<p>${msg(html`Hello <b>World!</b>`, {id: 'greeting'})}</p>`;
   }
 }
 ```

packages/localize/examples/runtime/package.json

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

packages/localize/examples/runtime/src/locale-codes.ts

@@ -8,19 +8,18 @@ export const sourceLocale = `en`;
 
 /**
  * The other locale codes that this application is localized into. Sorted
- * longest first, then lexicographically.
+ * lexicographically.
  */
 export const targetLocales = [
   `es-419`,
   `zh_CN`,
 ] as const;
 
 /**
- * All valid project locale codes. Sorted longest first, then
- * lexicographically.
+ * All valid project locale codes. Sorted lexicographically.
  */
 export const allLocales = [
+  `en`,
   `es-419`,
   `zh_CN`,
-  `en`,
 ] as const;

packages/localize/examples/runtime/src/locales/es-419.ts

@@ -8,6 +8,6 @@
     /* eslint-disable @typescript-eslint/no-explicit-any */
 
     export const templates = {
-      greeting: html`Hola <b>Mundo</b>!`,
+      'greeting': html`Hola <b>Mundo</b>!`,
     };
 

packages/localize/examples/runtime/src/locales/zh_CN.ts

@@ -8,6 +8,6 @@
     /* eslint-disable @typescript-eslint/no-explicit-any */
 
     export const templates = {
-      greeting: html`你好, <b>世界!</b>`,
+      'greeting': html`你好, <b>世界!</b>`,
     };
 

packages/localize/examples/runtime/src/x-greeter.ts

@@ -4,7 +4,7 @@ import {Localized} from '@lit/localize/localized-element.js';
 
 export class XGreeter extends Localized(LitElement) {
   render() {
-    return html`<p>${msg('greeting', html`Hello <b>World</b>!`)}</p>`;
+    return html`<p>${msg(html`Hello <b>World</b>!`, {id: 'greeting'})}</p>`;
   }
 }
 customElements.define('x-greeter', XGreeter);

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

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

packages/localize/examples/transform/package.json

@@ -8,19 +8,18 @@ export const sourceLocale = `en`;
 
 /**
  * The other locale codes that this application is localized into. Sorted
- * longest first, then lexicographically.
+ * lexicographically.
  */
 export const targetLocales = [
   `es-419`,
   `zh_CN`,
 ] as const;
 
 /**
- * All valid project locale codes. Sorted longest first, then
- * lexicographically.
+ * All valid project locale codes. Sorted lexicographically.
  */
 export const allLocales = [
+  `en`,
   `es-419`,
   `zh_CN`,
-  `en`,
 ] as const;

packages/localize/examples/transform/src/locale-codes.ts

@@ -3,7 +3,7 @@ import {msg} from '@lit/localize';
 
 export class XGreeter extends LitElement {
   render() {
-    return html`<p>${msg('greeting', html`Hello <b>World</b>!`)}</p>`;
+    return html`<p>${msg(html`Hello <b>World</b>!`, {id: 'greeting'})}</p>`;
   }
 }
 customElements.define('x-greeter', XGreeter);

packages/localize/examples/transform/src/x-greeter.ts

@@ -47,7 +47,7 @@
   "dependencies": {
     "fs-extra": "^9.0.0",
     "glob": "^7.1.6",
-    "jsonschema": "^1.2.6",
+    "jsonschema": "^1.4.0",
     "lit-element": "^2.3.1",
     "lit-html": "^1.2.1",
     "minimist": "^1.2.5",
@@ -62,7 +62,6 @@
     "@types/diff": "^4.0.2",
     "@types/fs-extra": "^9.0.1",
     "@types/glob": "^7.1.1",
-    "@types/jsonschema": "^1.1.1",
     "@types/minimist": "^1.2.0",
     "@types/mocha": "^8.0.2",
     "@types/node": "^14.0.1",

packages/localize/package-lock.json

@@ -127,7 +127,7 @@ export function readConfigFileAndWriteSchema(configPath: string): Config {
 
   // eslint-disable-next-line @typescript-eslint/no-var-requires
   const schema = require('../config.schema.json');
-  const result = jsonSchema.validate(parsed, schema, {propertyName: 'config'});
+  const result = jsonSchema.validate(parsed, schema);
   if (result.errors.length > 0) {
     throw new KnownError(
       `Error validating config file ${configPath}:\n\n` +