lighthouse 8.5.1 → 8.6.0-dev.20211016

package/shared/test/localization/format-test.js

@@ -0,0 +1,421 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+const path = require('path');
+
+const format = require('../../localization/format.js');
+const i18n = require('../../../lighthouse-core/lib/i18n/i18n.js');
+const constants = require('../../../lighthouse-core/config/constants.js');
+const locales = require('../../localization/locales.js');
+
+/* eslint-env jest */
+
+describe('format', () => {
+  describe('DEFAULT_LOCALE', () => {
+    it('is the same as the default config locale', () => {
+      expect(format.DEFAULT_LOCALE).toBe(constants.defaultSettings.locale);
+    });
+  });
+
+  describe('#getAvailableLocales', () => {
+    it('has all the available locales', () => {
+      const availableLocales = format.getAvailableLocales();
+      for (const locale of ['en', 'es', 'ru', 'zh']) {
+        expect(availableLocales).toContain(locale);
+      }
+
+      const rawLocales = Object.keys(locales).sort();
+      expect(availableLocales.sort()).toEqual(rawLocales);
+    });
+
+    it('contains the default locale', () => {
+      expect(format.getAvailableLocales()).toContain(format.DEFAULT_LOCALE);
+    });
+  });
+
+  describe('#getCanonicalLocales', () => {
+    it('contains some canonical locales', () => {
+      const canonicalLocales = format.getCanonicalLocales();
+      for (const locale of ['en-US', 'es', 'ru', 'zh']) {
+        expect(canonicalLocales).toContain(locale);
+      }
+    });
+
+    it('is a subset of the available locales', () => {
+      const canonicalLocales = format.getCanonicalLocales();
+      const availableLocales = format.getAvailableLocales();
+
+      for (const canonicalLocale of canonicalLocales) {
+        expect(availableLocales).toContain(canonicalLocale);
+      }
+
+      expect(canonicalLocales.length).toBeLessThan(availableLocales.length);
+    });
+  });
+
+  describe('#_formatPathAsString', () => {
+    it('handles simple paths', () => {
+      expect(format._formatPathAsString(['foo'])).toBe('foo');
+      expect(format._formatPathAsString(['foo', 'bar', 'baz'])).toBe('foo.bar.baz');
+    });
+
+    it('handles array paths', () => {
+      expect(format._formatPathAsString(['foo', 0])).toBe('foo[0]');
+    });
+
+    it('handles complex paths', () => {
+      const propertyPath = ['foo', 'what-the', 'bar', 0, 'no'];
+      expect(format._formatPathAsString(propertyPath)).toBe('foo[what-the].bar[0].no');
+    });
+
+    it('throws on unhandleable paths', () => {
+      expect(() => format._formatPathAsString(['Bobby "DROP TABLE'])).toThrow(/Cannot handle/);
+    });
+  });
+
+  describe('#replaceIcuMessages', () => {
+    it('replaces the references in the LHR', () => {
+      const fakeFile = path.join(__dirname, 'fake-file-number-2.js');
+      const UIStrings = {aString: 'different {x}!'};
+      const formatter = i18n.createMessageInstanceIdFn(fakeFile, UIStrings);
+
+      const title = formatter(UIStrings.aString, {x: 1});
+      const lhr = {audits: {'fake-audit': {title}}};
+
+      const icuMessagePaths = format.replaceIcuMessages(lhr, 'en-US');
+      expect(lhr.audits['fake-audit'].title).toBe('different 1!');
+
+      const expectedPathId = 'shared/test/localization/fake-file-number-2.js | aString';
+      expect(icuMessagePaths).toEqual({
+        [expectedPathId]: [{path: 'audits[fake-audit].title', values: {x: 1}}]});
+    });
+  });
+
+  describe('#getRendererFormattedStrings', () => {
+    it('returns icu messages in the specified locale', () => {
+      const strings = format.getRendererFormattedStrings('en-XA');
+      expect(strings.passedAuditsGroupTitle).toEqual('[Þåššéð åûðîţš one two]');
+      expect(strings.snippetCollapseButtonLabel).toEqual('[Çöļļåþšé šñîþþéţ one two]');
+    });
+
+    it('throws an error for invalid locales', () => {
+      expect(_ => format.getRendererFormattedStrings('not-a-locale'))
+        .toThrow(`Unsupported locale 'not-a-locale'`);
+    });
+  });
+
+  describe('#getFormatted', () => {
+    it('returns the formatted string', () => {
+      const UIStrings = {testMessage: 'happy test'};
+      const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+      const formattedStr = format.getFormatted(str_(UIStrings.testMessage), 'en');
+      expect(formattedStr).toEqual('happy test');
+    });
+
+    it('returns the formatted string with replacements', () => {
+      const UIStrings = {testMessage: 'replacement test ({errorCode})'};
+      const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+      const formattedStr = format.getFormatted(str_(UIStrings.testMessage,
+          {errorCode: 'BOO'}), 'en');
+      expect(formattedStr).toEqual('replacement test (BOO)');
+    });
+
+    it('throws an error for invalid locales', () => {
+      // Populate a string to try to localize to a bad locale.
+      const UIStrings = {testMessage: 'testy test'};
+      const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+      expect(_ => format.getFormatted(str_(UIStrings.testMessage), 'still-not-a-locale'))
+        .toThrow(`Unsupported locale 'still-not-a-locale'`);
+    });
+
+    it('does not alter the passed-in replacement values object', () => {
+      const UIStrings = {
+        testMessage: 'needs {count, number, bytes}KB test {str} in {timeInMs, number, seconds}s',
+      };
+      const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+      const replacements = {
+        count: 2555,
+        str: '*units*',
+        timeInMs: 314159265,
+      };
+      const replacementsClone = JSON.parse(JSON.stringify(replacements));
+
+      const formattedStr = format.getFormatted(str_(UIStrings.testMessage, replacements), 'en');
+      expect(formattedStr).toEqual('needs 2KB test *units* in 314,159.3s');
+
+      expect(replacements).toEqual(replacementsClone);
+    });
+
+    it('returns a message that is already a string unchanged', () => {
+      const testString = 'kind of looks like it needs ({formatting})';
+      const formattedStr = format.getFormatted(testString, 'pl');
+      expect(formattedStr).toBe(testString);
+    });
+
+    it('throws an error if formatting something other than IcuMessages or strings', () => {
+      expect(_ => format.getFormatted(15, 'lt'))
+        .toThrow(`Attempted to format invalid icuMessage type`);
+      expect(_ => format.getFormatted(new Date(), 'sr-Latn'))
+        .toThrow(`Attempted to format invalid icuMessage type`);
+    });
+  });
+
+  describe('#registerLocaleData', () => {
+    // Store original locale data so we can restore at the end
+    const moduleLocales = require('../../localization/locales.js');
+    const clonedLocales = JSON.parse(JSON.stringify(moduleLocales));
+
+    it('installs new locale strings', () => {
+      const localeData = {
+        'shared/test/localization/format-test.js | testString': {
+          'message': 'en-XZ cuerda!',
+        },
+      };
+      format.registerLocaleData('en-XZ', localeData);
+
+      const UIStrings = {testString: 'en-US string!'};
+      const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+      const formattedStr = format.getFormatted(str_(UIStrings.testString), 'en-XZ');
+      expect(formattedStr).toEqual('en-XZ cuerda!');
+    });
+
+    it('overwrites existing locale strings', () => {
+      const filename = 'lighthouse-core/audits/is-on-https.js';
+      const UIStrings = require('../../../lighthouse-core/audits/is-on-https.js').UIStrings;
+      const str_ = i18n.createMessageInstanceIdFn(filename, UIStrings);
+
+      // To start with, we get back the intended string..
+      const origTitle = format.getFormatted(str_(UIStrings.title), 'es-419');
+      expect(origTitle).toEqual('Usa HTTPS');
+      const origFailureTitle = format.getFormatted(str_(UIStrings.failureTitle), 'es-419');
+      expect(origFailureTitle).toEqual('No usa HTTPS');
+
+      // Now we declare and register the new string...
+      const localeData = {
+        'lighthouse-core/audits/is-on-https.js | title': {
+          'message': 'new string for es-419 uses https!',
+        },
+      };
+      format.registerLocaleData('es-419', localeData);
+
+      // And confirm that's what is returned
+      const newTitle = format.getFormatted(str_(UIStrings.title), 'es-419');
+      expect(newTitle).toEqual('new string for es-419 uses https!');
+
+      // Meanwhile another string that wasn't set in registerLocaleData just falls back to english
+      const newFailureTitle = format.getFormatted(str_(UIStrings.failureTitle), 'es-419');
+      expect(newFailureTitle).toEqual('Does not use HTTPS');
+
+      // Restore overwritten strings to avoid messing with other tests
+      moduleLocales['es-419'] = clonedLocales['es-419'];
+      const title = format.getFormatted(str_(UIStrings.title), 'es-419');
+      expect(title).toEqual('Usa HTTPS');
+    });
+  });
+
+  describe('#isIcuMessage', () => {
+    const icuMessage = {
+      i18nId: 'shared/test/localization/fake-file.js | title',
+      values: {x: 1},
+      formattedDefault: 'a default',
+    };
+
+    it('passes a valid LH.IcuMessage', () => {
+      expect(format.isIcuMessage(icuMessage)).toBe(true);
+    });
+
+    it('fails non-objects', () => {
+      expect(format.isIcuMessage(undefined)).toBe(false);
+      expect(format.isIcuMessage(null)).toBe(false);
+      expect(format.isIcuMessage('ICU!')).toBe(false);
+      expect(format.isIcuMessage(55)).toBe(false);
+      expect(format.isIcuMessage([
+        icuMessage,
+        icuMessage,
+      ])).toBe(false);
+    });
+
+    it('fails invalid or missing i18nIds', () => {
+      const badIdMessage = {...icuMessage, i18nId: 0};
+      expect(format.isIcuMessage(badIdMessage)).toBe(false);
+
+      const noIdMessage = {...icuMessage};
+      delete noIdMessage.i18nId;
+      expect(format.isIcuMessage(noIdMessage)).toBe(false);
+    });
+
+    it('fails invalid or missing formattedDefault', () => {
+      const badDefaultMessage = {...icuMessage, formattedDefault: -0};
+      expect(format.isIcuMessage(badDefaultMessage)).toBe(false);
+
+      const noDefaultMessage = {...icuMessage};
+      delete noDefaultMessage.formattedDefault;
+      expect(format.isIcuMessage(noDefaultMessage)).toBe(false);
+    });
+
+    it('passes missing values', () => {
+      const emptyValuesMessage = {...icuMessage, values: {}};
+      expect(format.isIcuMessage(emptyValuesMessage)).toBe(true);
+
+      const noValuesMessage = {...icuMessage};
+      delete noValuesMessage.values;
+      expect(format.isIcuMessage(noValuesMessage)).toBe(true);
+    });
+
+    it('fails invalid values types', () => {
+      const badValuesMessage = {...icuMessage, values: NaN};
+      expect(format.isIcuMessage(badValuesMessage)).toBe(false);
+      const nullValuesMessage = {...icuMessage, values: null};
+      expect(format.isIcuMessage(nullValuesMessage)).toBe(false);
+    });
+
+    it(`fails invalid values' values types`, () => {
+      const badValuesValuesMessage = {...icuMessage, values: {a: false}};
+      expect(format.isIcuMessage(badValuesValuesMessage)).toBe(false);
+    });
+  });
+
+  describe('#getIcuMessageIdParts', () => {
+    it('returns valid ICU message id parts', () => {
+      const {filename, key} = format.getIcuMessageIdParts('path/to/file.js | modeName');
+      expect(filename).toEqual('path/to/file.js');
+      expect(key).toEqual('modeName');
+    });
+
+    it('throws on invalid ICU message id', () => {
+      expect(() => {
+        format.getIcuMessageIdParts('path/to/file.js');
+      }).toThrow();
+    });
+  });
+
+  describe('Message values are properly formatted', () => {
+    // Message strings won't be in locale files, so will fall back to values given here.
+    const UIStrings = {
+      helloWorld: 'Hello World',
+      helloBytesWorld: 'Hello {in, number, bytes} World',
+      helloMsWorld: 'Hello {in, number, milliseconds} World',
+      helloSecWorld: 'Hello {in, number, seconds} World',
+      helloTimeInMsWorld: 'Hello {timeInMs, number, seconds} World',
+      helloPercentWorld: 'Hello {in, number, extendedPercent} World',
+      helloWorldMultiReplace: '{hello} {world}',
+      helloPlural: '{itemCount, plural, =1{1 hello} other{hellos}}',
+      helloPluralNestedICU: '{itemCount, plural, ' +
+        '=1{1 hello {in, number, bytes}} ' +
+        'other{hellos {in, number, bytes}}}',
+      helloPluralNestedPluralAndICU: '{itemCount, plural, ' +
+        '=1{{innerItemCount, plural, ' +
+          '=1{1 hello 1 goodbye {in, number, bytes}} ' +
+          'other{1 hello, goodbyes {in, number, bytes}}}} ' +
+        'other{{innerItemCount, plural, ' +
+          '=1{hellos 1 goodbye {in, number, bytes}} ' +
+          'other{hellos, goodbyes {in, number, bytes}}}}}',
+    };
+    const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+    it('formats a basic message', () => {
+      const helloStr = str_(UIStrings.helloWorld);
+      expect(helloStr).toBeDisplayString('Hello World');
+    });
+
+    it('formats a message with bytes', () => {
+      const helloBytesStr = str_(UIStrings.helloBytesWorld, {in: 1875});
+      expect(helloBytesStr).toBeDisplayString('Hello 2 World');
+    });
+
+    it('formats a message with milliseconds', () => {
+      const helloMsStr = str_(UIStrings.helloMsWorld, {in: 432});
+      expect(helloMsStr).toBeDisplayString('Hello 430 World');
+    });
+
+    it('formats a message with seconds', () => {
+      const helloSecStr = str_(UIStrings.helloSecWorld, {in: 753});
+      expect(helloSecStr).toBeDisplayString('Hello 753.0 World');
+    });
+
+    it('formats a message with seconds timeInMs', () => {
+      const helloTimeInMsStr = str_(UIStrings.helloTimeInMsWorld, {timeInMs: 753543});
+      expect(helloTimeInMsStr).toBeDisplayString('Hello 753.5 World');
+    });
+
+    it('formats a message with extended percent', () => {
+      const helloPercentStr = str_(UIStrings.helloPercentWorld, {in: 0.43078});
+      expect(helloPercentStr).toBeDisplayString('Hello 43.08% World');
+    });
+
+    it('throws an error when values are needed but not provided', () => {
+      expect(_ => format.getFormatted(str_(UIStrings.helloBytesWorld), 'en-US'))
+        // eslint-disable-next-line max-len
+        .toThrow(`ICU Message "Hello {in, number, bytes} World" contains a value reference ("in") that wasn't provided`);
+    });
+
+    it('throws an error when a value is missing', () => {
+      expect(_ => format.getFormatted(str_(UIStrings.helloWorldMultiReplace,
+        {hello: 'hello'}), 'en-US'))
+        // eslint-disable-next-line max-len
+        .toThrow(`ICU Message "{hello} {world}" contains a value reference ("world") that wasn't provided`);
+    });
+
+    it('formats a message with plurals', () => {
+      const helloStr = str_(UIStrings.helloPlural, {itemCount: 3});
+      expect(helloStr).toBeDisplayString('hellos');
+    });
+
+    it('throws an error when a plural control value is missing', () => {
+      expect(_ => i18n.getFormatted(str_(UIStrings.helloPlural), 'en-US'))
+        // eslint-disable-next-line max-len
+        .toThrow(`ICU Message "{itemCount, plural, =1{1 hello} other{hellos}}" contains a value reference ("itemCount") that wasn't provided`);
+    });
+
+    it('formats a message with plurals and nested custom ICU', () => {
+      const helloStr = str_(UIStrings.helloPluralNestedICU, {itemCount: 3, in: 1875});
+      expect(helloStr).toBeDisplayString('hellos 2');
+    });
+
+    it('formats a message with plurals and nested custom ICU and nested plural', () => {
+      const helloStr = str_(UIStrings.helloPluralNestedPluralAndICU, {itemCount: 3,
+        innerItemCount: 1,
+        in: 1875});
+      expect(helloStr).toBeDisplayString('hellos 1 goodbye 2');
+    });
+
+    it('throws an error if a string value is used for a numeric placeholder', () => {
+      expect(_ => str_(UIStrings.helloTimeInMsWorld, {
+        timeInMs: 'string not a number',
+      }))
+        // eslint-disable-next-line max-len
+        .toThrow(`ICU Message "Hello {timeInMs, number, seconds} World" contains a numeric reference ("timeInMs") but provided value was not a number`);
+    });
+
+    it('throws an error if a value is provided that has no placeholder in the message', () => {
+      expect(_ => str_(UIStrings.helloTimeInMsWorld, {
+        timeInMs: 55,
+        sirNotAppearingInThisString: 66,
+      }))
+        // eslint-disable-next-line max-len
+        .toThrow(`Provided value "sirNotAppearingInThisString" does not match any placeholder in ICU message "Hello {timeInMs, number, seconds} World"`);
+    });
+
+    it('formats correctly with NaN and Infinity numeric values', () => {
+      const helloInfinityStr = str_(UIStrings.helloBytesWorld, {in: Infinity});
+      expect(helloInfinityStr).toBeDisplayString('Hello ∞ World');
+
+      const helloNaNStr = str_(UIStrings.helloBytesWorld, {in: NaN});
+      // TODO(COMPAT): workaround can be removed after Node 13 is retired.
+      // expect(helloNaNStr).toBeDisplayString('Hello NaN World');
+
+      // Node 13/V8 7.9 and 8.0 have a bug where `({a: NaN}).a.toLocaleString() === "-NaN"`. It
+      // works correctly in Node 12 and 14, so work around it since NaN isn't essential for
+      // user-facing strings and it will eventually correct itself.
+      const formattedNaNStr = format.getFormatted(helloNaNStr, 'en-US');
+      expect(formattedNaNStr === 'Hello NaN World' || formattedNaNStr === 'Hello -NaN World')
+        .toBe(true);
+    });
+  });
+});

package/shared/test/localization/locales-test.js

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright 2018 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+const locales = require('../../localization/locales.js');
+const assert = require('assert').strict;
+
+/* eslint-env jest */
+
+describe('locales', () => {
+  it('has only canonical (or expected-deprecated) language tags', () => {
+    // Map of deprecated codes to their canonical version. Depending on the ICU
+    // version used to run Lighthouse/this test, these *may* come back as their
+    // substitute, not themselves.
+    const deprecatedCodes = {
+      in: 'id',
+      iw: 'he',
+      mo: 'ro',
+      tl: 'fil',
+    };
+
+    for (const locale of Object.keys(locales)) {
+      const canonicalLocale = Intl.getCanonicalLocales(locale)[0];
+      const substitute = deprecatedCodes[locale];
+      assert.ok(locale === canonicalLocale || substitute === canonicalLocale,
+        `locale code '${locale}' not canonical ('${canonicalLocale}' found instead)`);
+    }
+
+    // Deprecation subsitutes should be removed from the test if no longer used.
+    for (const locale of Object.keys(deprecatedCodes)) {
+      assert.ok(locales[locale], `${locale} substitute should be removed from test`);
+    }
+  });
+
+  it('has a base language prefix fallback for all supported languages', () => {
+    for (const locale of Object.keys(locales)) {
+      const basePrefix = locale.split('-')[0];
+      // The internet sez there is no canonical Chinese, so we exclude that one.
+      if (basePrefix !== 'zh') {
+        assert.ok(locales[basePrefix], `${locale} is missing a base fallback`);
+      }
+    }
+  });
+});

package/shared/test/localization/swap-locale-test.js

@@ -0,0 +1,140 @@
+/**
+ * @license Copyright 2019 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+const swapLocale = require('../../localization/swap-locale.js');
+const {isNode12SmallIcu} = require('../../../lighthouse-core/test/test-utils.js');
+
+const lhr = require('../../../lighthouse-core/test/results/sample_v2.json');
+
+/* eslint-env jest */
+describe('swap-locale', () => {
+  // COMPAT: Node 12 only has 'en' by default. Skip these tests since they're all about swapping locales.
+  if (isNode12SmallIcu()) {
+    // Jest requires at least one test per suite.
+    it('throws if locale is not supported', () => {
+      // Even though 'pt' is requested, 'en' is all that's available.
+      expect(() => swapLocale(lhr, 'pt')).toThrow('Unsupported locale \'pt\'');
+    });
+
+    return;
+  }
+
+  it('does not mutate the original lhr', () => {
+    /** @type {LH.Result} */
+    const lhrClone = JSON.parse(JSON.stringify(lhr));
+
+    const lhrPt = swapLocale(lhr, 'pt').lhr;
+    expect(lhrPt).not.toStrictEqual(lhr);
+    expect(lhr).toStrictEqual(lhrClone);
+  });
+
+  it('can change golden LHR english strings into german', () => {
+    /** @type {LH.Result} */
+    const lhrEn = JSON.parse(JSON.stringify(lhr));
+    const lhrDe = swapLocale(lhrEn, 'de').lhr;
+
+    // Basic replacement
+    expect(lhrEn.audits.plugins.title).toEqual('Document avoids plugins');
+    expect(lhrDe.audits.plugins.title).toEqual('Dokument verwendet keine Plug-ins');
+
+    // With ICU string argument values
+    expect(lhrEn.audits['dom-size'].displayValue).toMatchInlineSnapshot(`"153 elements"`);
+    /* eslint-disable no-irregular-whitespace */
+    expect(lhrDe.audits['dom-size'].displayValue).toMatchInlineSnapshot(`"153 Elemente"`);
+
+    // Renderer formatted strings
+    expect(lhrEn.i18n.rendererFormattedStrings.labDataTitle).toEqual('Lab Data');
+    expect(lhrDe.i18n.rendererFormattedStrings.labDataTitle).toEqual('Labdaten');
+
+    // Formatted numbers in placeholders.
+    expect(lhrEn.audits['mainthread-work-breakdown'].displayValue).
+toMatchInlineSnapshot(`"2.2 s"`);
+    expect(lhrDe.audits['mainthread-work-breakdown'].displayValue).
+toMatchInlineSnapshot(`"2,2 s"`);
+    /* eslint-enable no-irregular-whitespace */
+  });
+
+  it('can roundtrip back to english correctly', () => {
+    /** @type {LH.Result} */
+    const lhrEn = JSON.parse(JSON.stringify(lhr));
+
+    // via Spanish
+    const lhrEnEsRT = swapLocale(swapLocale(lhrEn, 'es').lhr, 'en-US').lhr;
+    expect(lhrEnEsRT).toEqual(lhrEn);
+
+    // via Arabic
+    const lhrEnArRT = swapLocale(swapLocale(lhrEn, 'ar').lhr, 'en-US').lhr;
+    expect(lhrEnArRT).toEqual(lhrEn);
+  });
+
+  it('leaves alone messages where there is no translation available', () => {
+    const miniLHR = {
+      audits: {
+        redirects: {
+          id: 'redirects',
+          title: 'Avoid multiple page redirects',
+          doesntExist: 'A string that does not have localized versions',
+        },
+        fakeaudit: {
+          id: 'fakeaudit',
+          title: 'An audit without translations',
+        },
+      },
+      configSettings: {
+        locale: 'en-US',
+      },
+      i18n: {
+        icuMessagePaths: {
+          'lighthouse-core/audits/redirects.js | title': ['audits.redirects.title'],
+          // File that exists, but `doesntExist` message within it does not.
+          'lighthouse-core/audits/redirects.js | doesntExist': ['audits.redirects.doesntExist'],
+          // File and message which do not exist.
+          'lighthouse-core/audits/fakeaudit.js | title': ['audits.fakeaudit.title'],
+        },
+      },
+    };
+    const {missingIcuMessageIds} = swapLocale(miniLHR, 'es');
+
+    // Updated strings are not found, so these remain in the original language
+    expect(missingIcuMessageIds).toMatchInlineSnapshot(`
+Array [
+  "lighthouse-core/audits/redirects.js | doesntExist",
+  "lighthouse-core/audits/fakeaudit.js | title",
+]
+`);
+  });
+
+  it('does not change properties that are not strings', () => {
+    // Unlikely, but possible e.g. if an audit details changed shape over LH versions.
+    const miniLhr = {
+      audits: {
+        redirects: {
+          id: 'redirects',
+          title: 'Avoid multiple page redirects',
+        },
+      },
+      configSettings: {
+        locale: 'en-US',
+      },
+      i18n: {
+        icuMessagePaths: {
+          // Points to audit object, not string.
+          'lighthouse-core/audits/redirects.js | title': ['audits.redirects'],
+          // Path does not point to anything in LHR.
+          'lighthouse-core/audits/redirects.js | description': ['gatherers..X'],
+        },
+      },
+    };
+    const testLocale = 'ru';
+    const {lhr} = swapLocale(miniLhr, testLocale);
+
+    // LHR remains unchanged except for locale and injected `rendererFormattedStrings`.
+    miniLhr.configSettings.locale = testLocale;
+    miniLhr.i18n.rendererFormattedStrings = expect.any(Object);
+    expect(lhr).toEqual(miniLhr);
+  });
+});

package/shared/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "../../.tmp/tsbuildinfo/shared/",
+
+    // Limit defs to base JS.
+    "lib": ["es2020"],
+    // Only include `@types/node` from node_modules/.
+    "types": ["node"],
+    // "listFiles": true,
+  },
+  "references": [
+    {"path": "../types/lhr/"},
+  ],
+  "include": [
+    "**/*.js",
+    "types/**/*.d.ts",
+  ],
+  "exclude": [
+    "test/**/*.js",
+  ],
+}

package/shared/types/shared.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {IcuMessage as IcuMessage_} from '../../types/lhr/i18n';
+import LHResult from '../../types/lhr/lhr';
+import FlowResult_ from '../../types/lhr/flow';
+
+import {Locale as Locale_} from '../../types/lhr/settings';
+ 
+declare global {
+  // Expose global types in LH namespace.
+  module LH {
+    export import Result = LHResult;
+    export import FlowResult = FlowResult_;
+    export type IcuMessage = IcuMessage_;
+    export type IcuMessagePaths = LHResult.IcuMessagePaths;
+    export type Locale = Locale_;
+  }
+}
+
+export {};