Merge branch 'master' into new-readme

Author: aomarks

README.md

@@ -146,11 +146,30 @@
 
 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.
+
+Throws if called more than once.
 
-In runtime mode, this function must be called once, before any calls to `msg()`.
+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:
 
@@ -168,37 +187,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:
 
-In transform mode, calls to this function are replaced with `undefined`.
+- `sourceLocale: string`: Required locale code in which source templates in this
+  project are written, and the active locale.
 
-### `localeReady() => Promise`
+Example:
 
-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.
+```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'};
+```
 
-In transform mode, calls to this function are replaced with
-`Promise.resolve(undefined)`.
+### `getLocale() => string`
+
+Return the active locale code.
+
+### `setLocale(locale: string) => 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.
+
+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.
+
+Throws if the given locale is not contained by the configured `sourceLocale` or
+`targetLocales`.
 
 ### `msg(id: string, template, ...args) => string|TemplateResult`
 
@@ -249,21 +296,76 @@ template for each emitted locale. For example:
 html`Hola <b>${getUsername()}!</b>`;
 ```
 
-### `LOCALE_CHANGED_EVENT: string`
+### `LOCALE_STATUS_EVENT`
+
+Name of the [`lit-localize-status` event](#lit-localize-status-event).
 
-Whenever the locale changes and templates have finished loading, an event by
-this name (`"lit-localize-locale-changed"`) is dispatched to `window`.
+## `lit-localize-status` event
+
+In runtime mode, whenever a locale change starts, finishes successfully, or
+fails, lit-localize will dispatch a `lit-localize-status` event to `window`.
 
 You can listen for this event to know when your application should be
 re-rendered following a locale change. See also the
 [`Localized`](#localized-mixin) mixin, which automatically re-renders
 `LitElement` classes using this event.
 
-```typescript
-import {LOCALE_CHANGED_EVENT} from 'lit-localize';
+### Event types
+
+The `detail.status` string property tells you what kind of status change has occured,
+and can be one of: `loading`, `ready`, or `error`:
+
+#### `loading`
+
+A new locale has started to load. The `detail` object also contains:
+
+- `loadingLocale: string`: Code of the locale that has started loading.
+
+A `loading` status can be followed by a `ready`, `error`, or `loading` status.
+
+In the case that a second locale is requested before the first one finishes
+loading, a new `loading` event is dispatched, and no `ready` or `error` event
+will be dispatched for the first request, because it is now stale.
 
-window.addEventListener(LOCALE_CHANGED_EVENT, () => {
-  renderApplication();
+#### `ready`
+
+A new locale has successfully loaded and is ready for rendering. The `detail` object also contains:
+
+- `readyLocale: string`: Code of the locale that has successfully loaded.
+
+A `ready` status can be followed only by a `loading` status.
+
+#### `error`
+
+A new locale failed to load. The `detail` object also contains the following
+properties:
+
+- `errorLocale: string`: Code of the locale that failed to load.
+- `errorMessage: string`: Error message from locale load failure.
+
+An `error` status can be followed only by a `loading` status.
+
+### Event example
+
+```typescript
+// Show/hide a progress indicator whenever a new locale is loading,
+// and re-render the application every time a new locale successfully loads.
+window.addEventListener('lit-localize-status', (event) => {
+  const spinner = document.querySelector('#spinner');
+  if (event.detail.status === 'loading') {
+    console.log(`Loading new locale: ${event.detail.loadingLocale}`);
+    spinner.removeAttribute('hidden');
+  } else if (event.detail.status === 'ready') {
+    console.log(`Loaded new locale: ${event.detail.readyLocale}`);
+    spinner.addAttribute('hidden');
+    renderApplication();
+  } else if (event.detail.status === 'error') {
+    console.error(
+      `Error loading locale ${event.detail.errorLocale}: ` +
+        event.detail.errorMessage
+    );
+    spinner.addAttribute('hidden');
+  }
 });
 ```
 

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';
 
@@ -152,7 +152,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);
     }