Merge branch 'transform-more' into localized-element

Author: aomarks

README.md

@@ -2,17 +2,34 @@
 
 [![Published on npm](https://img.shields.io/npm/v/lit-localize.svg)](https://www.npmjs.com/package/lit-localize) [![Test Status](https://github.com/PolymerLabs/lit-localize/workflows/tests/badge.svg?branch=master)](https://github.com/PolymerLabs/lit-localize/actions?query=workflow%3Atests+branch%3Amaster+event%3Apush)
 
-WIP
-
 ## API
 
 The `lit-localize` module exports the following functions:
 
+> Note that lit-localize relies on distinctive, annotated TypeScript type
+> 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
+> 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`.
+
 ### `configureLocalization(configuration)`
 
-Set runtime localization configuration.
+Set configuration parameters for lit-localize when in runtime mode. Returns an
+object with functions:
+
+- [`getLocale`](#getlocale-string): Return the active locale code.
+- [`setLocale`](#setlocalelocale-string-promise): Set the active locale code.
 
-In runtime mode, this function must be called once, before any calls to `msg()`.
+Throws if called more than once.
+
+When in transform mode, the lit-localize CLI will error if this function is
+called. Use
+[`configureTransformLocalization`](#configuretransformlocalizationconfiguration)
+instead.
 
 The `configuration` object must have the following properties:
 
@@ -30,37 +47,65 @@ The `configuration` object must have the following properties:
 Example:
 
 ```typescript
-configureLocalization({
+const {getLocale, setLocale} = configureLocalization({
   sourceLocale: 'en',
   targetLocales: ['es-419', 'zh_CN'],
   loadLocale: (locale) => import(`/${locale}.js`),
 });
 ```
 
-In transform mode, this function is not required, and calls to it will be
-replaced with `undefined`.
+### `configureTransformLocalization(configuration)`
 
-### `getLocale() => string`
+Set configuration parameters for lit-localize when in transform mode. Returns an
+object with function:
 
-Return the active locale code.
+- [`getLocale`](#getlocale-string): Return the active locale code.
 
-In transform mode, calls to this function are transformed into the static locale
-code string for each emitted locale.
+(Note that [`setLocale`](#setlocalelocale-string-promise) is not available from
+this function, because changing locales at runtime is not supported in transform
+mode.)
 
-### `setLocale(locale: string)`
+Throws if called more than once.
 
-Set the active locale code, and begin loading templates for that locale using
-the `loadLocale` function that was passed to `configureLocalization`.
+The `configuration` object must have the following properties:
+
+- `sourceLocale: string`: Required locale code in which source templates in this
+  project are written, and the active locale.
+
+Example:
+
+```typescript
+const {getLocale} = configureLocalization({
+  sourceLocale: 'en',
+});
+```
+
+In transform mode, calls to this function are transformed to an object with a
+`getLocale` implementation that returns the static locale code for each locale
+bundle. For example:
+
+```typescript
+const {getLocale} = {getLocale: () => 'es-419'};
+```
+
+### `getLocale(): string`
 
-In transform mode, calls to this function are replaced with `undefined`.
+Return the active locale code.
+
+### `setLocale(locale: string): Promise`
 
-### `localeReady() => Promise`
+Set the active locale code, and begin loading templates for that locale using
+the `loadLocale` function that was passed to `configureLocalization`. Returns a
+promise that resolves when the next locale is ready to be rendered.
 
-Return a promise that is resolved when the next set of templates are loaded and
-available for rendering. Applications in runtime mode should always `await localeReady()` before rendering.
+Note that if a second call to `setLocale` is made while the first requested
+locale is still loading, then the second call takes precedence, and the promise
+returned from the first call will resolve when second locale is ready. If you
+need to know whether a particular locale was loaded, check `getLocale` after the
+promise resolves.
 
-In transform mode, calls to this function are replaced with
-`Promise.resolve(undefined)`.
+Throws if the given locale is not contained by the configured `sourceLocale` or
+`targetLocales`.
 
 ### `msg(id: string, template, ...args) => string|TemplateResult`
 

src/outputters/runtime.ts

@@ -14,7 +14,7 @@ import {applyPatches, Patches} from '../patches';
 import {Locale} from '../locales';
 import {Config} from '../config';
 import {KnownError} from '../error';
-import {escapeStringLiteral} from '../typescript';
+import {escapeStringToEmbedInTemplateLiteral} from '../typescript';
 import * as fs from 'fs';
 import * as pathLib from 'path';
 
@@ -444,7 +444,7 @@ function makeMessageString(
   const fragments = [];
   for (const content of contents) {
     if (typeof content === 'string') {
-      fragments.push(escapeStringLiteral(content));
+      fragments.push(escapeStringToEmbedInTemplateLiteral(content));
     } else {
       fragments.push(content.untranslatable);
     }

src/outputters/transform.ts

@@ -13,9 +13,9 @@ import {Message} from '../messages';
 import {Locale} from '../locales';
 import {Config} from '../config';
 import * as ts from 'typescript';
-import {isLitExpression, isMsgCall, isStaticString} from '../program-analysis';
+import {isLitTemplate, isMsgCall, isStaticString} from '../program-analysis';
 import {KnownError} from '../error';
-import {escapeStringLiteral} from '../typescript';
+import {escapeStringToEmbedInTemplateLiteral} from '../typescript';
 import * as pathLib from 'path';
 
 /**
@@ -103,7 +103,7 @@ class Transformer {
     }
 
     // html`<b>${msg('greeting', 'hello')}</b>` -> html`<b>hola</b>`
-    if (isLitExpression(node)) {
+    if (isLitTemplate(node)) {
       // If an html-tagged template literal embeds a msg call, we want to
       // collapse the result of that msg call into the parent template.
       return tagLit(
@@ -119,34 +119,43 @@ class Transformer {
     }
 
     if (ts.isCallExpression(node)) {
-      // configureLocalization(...) -> undefined
+      // configureTransformLocalization(...) -> {getLocale: () => "es-419"}
       if (
         this.typeHasProperty(
           node.expression,
-          '_LIT_LOCALIZE_CONFIGURE_LOCALIZATION_'
+          '_LIT_LOCALIZE_CONFIGURE_TRANSFORM_LOCALIZATION_'
         )
       ) {
-        return ts.createIdentifier('undefined');
-      }
-
-      // getLocale() -> "es-419"
-      if (this.typeHasProperty(node.expression, '_LIT_LOCALIZE_GET_LOCALE_')) {
-        return ts.createStringLiteral(this.locale);
-      }
-
-      // setLocale("es-419") -> undefined
-      if (this.typeHasProperty(node.expression, '_LIT_LOCALIZE_SET_LOCALE_')) {
-        return ts.createIdentifier('undefined');
+        return ts.createObjectLiteral(
+          [
+            ts.createPropertyAssignment(
+              ts.createIdentifier('getLocale'),
+              ts.createArrowFunction(
+                undefined,
+                undefined,
+                [],
+                undefined,
+                ts.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                ts.createStringLiteral(this.locale)
+              )
+            ),
+          ],
+          false
+        );
       }
 
-      // localeReady() -> Promise.resolve(undefined)
+      // configureLocalization(...) -> Error
       if (
-        this.typeHasProperty(node.expression, '_LIT_LOCALIZE_LOCALE_READY_')
+        this.typeHasProperty(
+          node.expression,
+          '_LIT_LOCALIZE_CONFIGURE_LOCALIZATION_'
+        )
       ) {
-        return ts.createCall(
-          ts.createPropertyAccess(ts.createIdentifier('Promise'), 'resolve'),
-          [],
-          [ts.createIdentifier('undefined')]
+        // TODO(aomarks) This error is not surfaced earlier in the analysis phase
+        // as a nicely formatted diagnostic, but it should be.
+        throw new KnownError(
+          'Cannot use configureLocalization in transform mode. ' +
+            'Use configureTransformLocalization instead.'
         );
       }
 
@@ -200,7 +209,7 @@ class Transformer {
       !(
         ts.isStringLiteral(arg1) ||
         ts.isTemplateLiteral(arg1) ||
-        isLitExpression(arg1) ||
+        isLitTemplate(arg1) ||
         ts.isArrowFunction(arg1)
       )
     ) {
@@ -221,19 +230,19 @@ class Transformer {
       if (
         !ts.isStringLiteral(arg1.body) &&
         !ts.isTemplateLiteral(arg1.body) &&
-        !isLitExpression(arg1.body)
+        !isLitTemplate(arg1.body)
       ) {
         throw new KnownError(
           'Expected function body to be a template or string'
         );
       }
-      if (isLitExpression(arg1.body)) {
+      if (isLitTemplate(arg1.body)) {
         isLitTagged = true;
         template = arg1.body.template;
       } else {
         template = arg1.body;
       }
-    } else if (isLitExpression(arg1)) {
+    } else if (isLitTemplate(arg1)) {
       isLitTagged = true;
       template = arg1.template;
     } else {
@@ -248,7 +257,7 @@ class Transformer {
         const templateLiteralBody = translation.contents
           .map((content) =>
             typeof content === 'string'
-              ? escapeStringLiteral(content)
+              ? escapeStringToEmbedInTemplateLiteral(content)
               : content.untranslatable
           )
           .join('');
@@ -260,6 +269,7 @@ class Transformer {
         // manipulation of placeholder contents. We should validate that the set
         // of translated placeholders is exactly equal to the set of original
         // source placeholders (order can change, but contents can't).
+        // See https://github.com/PolymerLabs/lit-localize/issues/49
         template = parseStringAsTemplateLiteral(templateLiteralBody);
       }
       // TODO(aomarks) Emit a warning that a translation was missing.
@@ -371,7 +381,7 @@ class Transformer {
         fragments.push(expression.text);
       } else if (ts.isTemplateLiteral(expression)) {
         fragments.push(...this.recursivelyFlattenTemplate(expression, false));
-      } else if (isLit && isLitExpression(expression)) {
+      } else if (isLit && isLitTemplate(expression)) {
         fragments.push(
           ...this.recursivelyFlattenTemplate(expression.template, true)
         );
@@ -410,18 +420,16 @@ class Transformer {
     const moduleSymbol = this.typeChecker.getSymbolAtLocation(
       node.moduleSpecifier
     );
-    if (!moduleSymbol) {
+    if (!moduleSymbol || !moduleSymbol.exports) {
       return false;
     }
-    // TODO(aomarks) Is there a better way to reliably identify the lit-localize
-    // modules that don't require this cast? We could export a const with a
-    // known name and then look through `exports`, but it doesn't seem good to
-    // polute the modules like that.
-    const file = (moduleSymbol.valueDeclaration as unknown) as {
-      identifiers: Map<string, unknown>;
-    };
-    for (const id of file.identifiers.keys()) {
-      if (id === '_LIT_LOCALIZE_MSG_' || id === '_LIT_LOCALIZE_LOCALIZED_') {
+    const exports = moduleSymbol.exports.values();
+    for (const xport of exports as typeof exports & {
+      [Symbol.iterator](): Iterator<ts.Symbol>;
+    }) {
+      const type = this.typeChecker.getTypeAtLocation(xport.valueDeclaration);
+      const props = this.typeChecker.getPropertiesOfType(type);
+      if (props.some((prop) => prop.escapedName === '_LIT_LOCALIZE_MSG_')) {
         return true;
       }
     }

src/program-analysis.ts

@@ -107,7 +107,7 @@ function extractMsg(
     };
   }
 
-  if (isLitExpression(contentsArg)) {
+  if (isLitTemplate(contentsArg)) {
     if (ts.isNoSubstitutionTemplateLiteral(contentsArg.template)) {
       // E.g. msg('foo', html`bar <b>baz</b>`)
       return {
@@ -186,7 +186,7 @@ function functionTemplate(
   if (
     !ts.isTemplateExpression(body) &&
     !ts.isNoSubstitutionTemplateLiteral(body) &&
-    !isLitExpression(body)
+    !isLitTemplate(body)
   ) {
     return createDiagnostic(
       file,
@@ -195,7 +195,7 @@ function functionTemplate(
         `or a lit-html template, without braces`
     );
   }
-  const template = isLitExpression(body) ? body.template : body;
+  const template = isLitTemplate(body) ? body.template : body;
   const parts: Array<string | {identifier: string}> = [];
   if (ts.isTemplateExpression(template)) {
     const spans = template.templateSpans;
@@ -220,8 +220,8 @@ function functionTemplate(
     // A NoSubstitutionTemplateLiteral. No spans.
     parts.push(template.text);
   }
-  const isLitTemplate = isLitExpression(body);
-  const contents = isLitTemplate
+  const isLit = isLitTemplate(body);
+  const contents = isLit
     ? replaceExpressionsAndHtmlWithPlaceholders(parts)
     : parts.map((part) =>
         typeof part === 'string'
@@ -235,7 +235,7 @@ function functionTemplate(
     file,
     descStack: descStack.map((desc) => desc.text),
     params,
-    isLitTemplate,
+    isLitTemplate: isLit,
   };
 }
 
@@ -480,7 +480,7 @@ export function isStaticString(
 /**
  * E.g. html`foo` or html`foo${bar}`
  */
-export function isLitExpression(
+export function isLitTemplate(
   node: ts.Node
 ): node is ts.TaggedTemplateExpression {
   return (