Merge branch 'master' into transform-more

Author: aomarks

README.md

@@ -2,17 +2,29 @@
 
 [![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): Return the active locale code.
+- [`setLocale`](#setLocale): 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.
 
 The `configuration` object must have the following properties:
 
@@ -30,15 +42,37 @@ 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)`
+
+Set configuration parameters for lit-localize when in transform mode. Returns an
+object with functions:
+
+- [`getLocale`](#getLocale): Return the active locale code.
+
+(Note that [`setLocale`](#setLocale) is not available, because changing locales
+at runtime is not supported in transform mode.)
+
+Throws if called more than once.
+
+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',
+});
+```
 
 ### `getLocale(): string`
 
@@ -50,17 +84,17 @@ code string for each emitted locale.
 ### `setLocale(locale: string)`
 
 Set the active locale code, and begin loading templates for that locale using
-the `loadLocale` function that was passed to `configureLocalization`.
-
-In transform mode, calls to this function are replaced with `undefined`.
-
-### `localeReady(): Promise`
+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(
@@ -168,7 +168,7 @@ class Transformer {
       !(
         ts.isStringLiteral(arg1) ||
         ts.isTemplateLiteral(arg1) ||
-        isLitExpression(arg1) ||
+        isLitTemplate(arg1) ||
         ts.isArrowFunction(arg1)
       )
     ) {
@@ -189,19 +189,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 {
@@ -216,7 +216,7 @@ class Transformer {
         const templateLiteralBody = translation.contents
           .map((content) =>
             typeof content === 'string'
-              ? escapeStringLiteral(content)
+              ? escapeStringToEmbedInTemplateLiteral(content)
               : content.untranslatable
           )
           .join('');
@@ -228,6 +228,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.
@@ -339,7 +340,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)
         );
@@ -377,18 +378,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
-    // module that doesn'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 module 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_') {
+    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 (