Providing i18n translations for (custom) audits

[fbatschi]

Inject Translations for custom audits

There is currently no information in the docs on how to add I18N translations for locales for a custom audit.

I have a custom audit like the one below and want to provide a translation for a given locale (let's say 'fr'). How to proceed? How to inject or reference a json file with my custom translations for several locales?

'use strict';
const Audit = require('lighthouse').Audit;
const i18n = require('lighthouse/lighthouse-core/lib/i18n/i18n.js');

const UIStrings = {
  title: 'A crazy audit',
  failureTitle: 'Audit failed massively',
  description: 'This is a test. This is not real. ',
};

const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);

class MyCustomAudit extends Audit {
  static get meta() {
    return {
      id: 'my-custom-audit',
      title: str_(UIStrings.title),
      failureTitle: str_(UIStrings.failureTitle),
      description: str_(UIStrings.description),
    };
  }

  static audit(artifacts) {
    [...]
  }
}

module.exports = MyCustomAudit;

There also sees to be no way to provide another JSON files as extension to the existing locale files in lighthouse-core to overwrite an existing translation or to provide a missing translation during runtime without touching core files.

[patrickhulce]

Thanks for filing @fbatschi! You're the first person I'm aware of to have requested this :)

The i18n flow is hard-coded to the set of JSON files in core right now, you are correct. It seems like we would need to add some functionality to config for the location of supplemental i18n locale files.

@exterkamp any additional thoughts here?

[fbatschi]

I could of course handle translations inside of the custom audit and provide different translation texts depending on the used locale and set the meta information of the audit accordingly, but that would be repetitive and not very generic if you have many custom audits.

And also, as there are some core audits, which have not been translated yet and one might even want to replace or slightly change the texts of the core audits without touching the core I think a way to include additional locale files or a locale directory would be great.

These added locale translations should override existing values, so when another json file is given, it should be merged into the existing locale JSON and override a value when the key already exists in the core locale file.

[exterkamp]

@patrickhulce my additional thought is, yes! This is a gap in our custom audit, and plugin, story. And I think that @brendankenny might have some more context on the integration side in the future. My only feedback is that, yes this is happening!

I'm not sure about the idea that we would directly support JSON overriding of the core audit texts. Why would you want to do that? Other than that there are some untranslated audits (soon to be fixed #9105 #9092). I'd say if you have a problem with the core translations, then just edit that .json file directly (also you should open an issue against it 😉), but we wouldn't support overriding it in core from an external JSON pulled in at runtime I don't think.

[fbatschi]

The reason for us to override core translations is that some of the translations are too technical for our audience of the reports, so we want to change them completely (during runtime), in other cases we simply wanted to add a sentence or two.

For the time being we have built the functionality with a handful of new lines of code to i18n.js as well as including the y18n package and preserve the changes with patch-package to enable both requested features for us.

If translations for custom audits become a core feature though, this would be appreciated.

[aquariuslt]

how about provides a function in i18n.js like below

/**
 * register/override custom locale messages
 * @param {LH.Locale || string }locale
 * @param {Record<string, {message: string}>} localeMessages
 */
function registerLocale(locale, localeMessages) {
  // update/merge LOCALES, so that lookupLocales(locale) can return override localeMessages
}

[xjjxjj]

Will support it ? I also have the same hope.The reason for us to override core translations like follow

1. there are some core audits have not been translated yet
2. I want to change some translate to easier to understand for those who use my report

If translations can be custom become a core feature, this would be appreciated.

[paulirish]

Update: We introduced a i18n.registerLocaleData() method in #9638 We didn't intend for it to be used outside of the Lighthouse internals, but it certainly could be.

We still don't offer a first-class i18n story for custom audits.