✨ Allow deployment config to provide translation overrides

A generic way for deployments to tweak any i18nized text in the app, specified as "translation_overrides": {"<lang>": { ...same shape as en.json... }}

Via i18next addResourceBundle, these get tacked onto the translations from en.json, es.json, etc. when the config is loaded, which is before the UI gets a change to load any strings that would be modified.
The exception is, of course, the strings that appear before the user enters their opcode (as the app doesn't know what deployment it's using yet!)

We can likely use this to replace intro.translated_text entirely, since it accomplishes the same thing in a more generic way.

We might also consider using it to replace label-options "translations"; i.e. instead of asking deployers to provide the translations there for all the modes they list, we provide the translations for our default set of modes, and they would only have to provide the ones they added (or wanted to name something else), and those translations would live in the same place as any other translations/ in-app text they are providing.

Author: JGreenlee

src/__tests__/configTranslations.test.ts

@@ -0,0 +1,37 @@
+import i18next, { applyConfigTranslations } from '../js/i18nextInit';
+import { DeploymentConfigWithOverrides } from '../js/types/appConfigTypes';
+
+const configWithOverrides = {
+  translation_overrides: {
+    en: { library: { 'available-vehicles': { title: 'Available Bikes' } } },
+  },
+} as unknown as DeploymentConfigWithOverrides;
+
+describe('applyConfigTranslations', () => {
+  afterEach(() => applyConfigTranslations(null));
+
+  it('overrides a built-in string with the one from the config', () => {
+    applyConfigTranslations(configWithOverrides);
+    expect(i18next.t('library.available-vehicles.title')).toBe('Available Bikes');
+  });
+
+  it('leaves keys that the config does not mention alone', () => {
+    applyConfigTranslations(configWithOverrides);
+    expect(i18next.t('library.available-vehicles.subtitle')).toBe('Find a station near you');
+    expect(i18next.t('library.available-vehicles.scan')).toBe('Scan');
+  });
+
+  it('only overrides the languages given in the config', () => {
+    applyConfigTranslations({
+      translation_overrides: { en: { loading: 'Just a sec...' } },
+    } as unknown as DeploymentConfigWithOverrides);
+    expect(i18next.getResource('en', 'translation', 'loading')).toBe('Just a sec...');
+    expect(i18next.getResource('es', 'translation', 'loading')).toBe('Cargando...');
+  });
+
+  it('restores the built-in strings once a config without overrides is applied', () => {
+    applyConfigTranslations(configWithOverrides);
+    applyConfigTranslations({} as DeploymentConfigWithOverrides);
+    expect(i18next.t('library.available-vehicles.title')).toBe('Available Vehicles');
+  });
+});

src/js/config/dynamicConfig.ts

@@ -11,6 +11,7 @@ import {
 } from './opcode';
 import { Alerts } from '../components/AlertArea';
 import { setPendingOpcode } from '../onboarding/onboardingHelper';
+import { applyConfigTranslations } from '../i18nextInit';
 
 export const CONFIG_PHONE_UI = 'config/app_ui_config';
 export const CONFIG_PHONE_UI_KVSTORE = 'CONFIG_PHONE_UI';
@@ -168,6 +169,7 @@ export function loadNewConfig(newToken: string, existingVersion?: number): Promi
         .then(([result, kvStoreResult]) => {
           logDebug(`UI_CONFIG: Stored dynamic config in KVStore successfully, 
             result = ${JSON.stringify(kvStoreResult)}`);
+          applyConfigTranslations(downloadedConfig);
           _promisedConfig = Promise.resolve(downloadedConfig);
           configChanged = true;
           return true;
@@ -231,8 +233,13 @@ export function getConfig(): Promise<DeploymentConfig | null> {
       },
     );
   });
-  _promisedConfig = promise;
-  return promise;
+  // apply translation overrides before anyone awaiting the config can render with the defaults
+  const configPromise = promise.then((config: DeploymentConfig | null) => {
+    applyConfigTranslations(config);
+    return config;
+  });
+  _promisedConfig = configPromise;
+  return configPromise;
 }
 
 export async function refreshConfig(opcode: string, existingVersion?: number) {

src/js/i18nextInit.ts

@@ -4,6 +4,7 @@
 
 import i18next from 'i18next';
 import { initReactI18next } from 'react-i18next';
+import { DeploymentConfigWithOverrides, TranslationTree } from './types/appConfigTypes';
 
 /* How should we handle missing translations?
 
@@ -38,11 +39,51 @@ function mergeInTranslations(lang, fallbackLang) {
 
 import enJson from '../i18n/en.json';
 import esJson from '../../locales/es/i18n/es.json';
+/* the built-in translations, before any deployment config overrides are applied */
+const baseTranslations: { [lang: string]: TranslationTree } = {
+  en: enJson as TranslationTree,
+  es: mergeInTranslations(esJson, enJson) as TranslationTree,
+};
 const langs = {
-  en: { translation: enJson },
-  es: { translation: mergeInTranslations(esJson, enJson) },
+  en: { translation: baseTranslations.en },
+  es: { translation: baseTranslations.es },
 };
 
+/* warns about override keys that don't exist in the built-in translations, which are
+  almost always typos since they would silently have no effect */
+function warnOnUnknownKeys(overrides: TranslationTree, base: TranslationTree, path = '') {
+  Object.entries(overrides).forEach(([key, value]) => {
+    const keyPath = path ? `${path}.${key}` : key;
+    if (base[key] === undefined) {
+      logWarn(`Deployment config overrides unknown translation key '${keyPath}'`);
+    } else if (typeof value === 'object' && typeof base[key] === 'object') {
+      warnOnUnknownKeys(value, base[key] as TranslationTree, keyPath);
+    }
+  });
+}
+
+/**
+ * @description Applies the `translation_overrides` from a deployment config on top of the
+ *  built-in translations. Only the languages given in the config are overridden; every other
+ *  language, and every key not mentioned, keeps its built-in value.
+ */
+export function applyConfigTranslations(config?: DeploymentConfigWithOverrides | null) {
+  const overrides = config?.translation_overrides;
+  Object.keys(baseTranslations).forEach((lang) => {
+    /* a deep addResourceBundle mutates the bundle in place, so drop the existing bundle and start
+      from a copy of the built-in translations; otherwise overrides from a previously loaded
+      deployment config would stick around */
+    const base = JSON.parse(JSON.stringify(baseTranslations[lang]));
+    i18next.removeResourceBundle(lang, 'translation');
+    i18next.addResourceBundle(lang, 'translation', base, false, true);
+    if (overrides?.[lang]) {
+      // always validate against English, which is the complete set of keys
+      warnOnUnknownKeys(overrides[lang], baseTranslations.en);
+      i18next.addResourceBundle(lang, 'translation', overrides[lang], true, true);
+    }
+  });
+}
+
 const locales = navigator?.languages?.length ? navigator.languages : [navigator.language];
 let detectedLang;
 for (const locale of locales) {

src/js/types/appConfigTypes.ts

@@ -0,0 +1,11 @@
+import { DeploymentConfig } from 'op-deployment-configs';
+
+export type TranslationTree = { [key: string]: string | TranslationTree };
+
+/** Per-language translation overrides supplied by a deployment config, keyed by language code */
+export type TranslationOverrides = { [lang: string]: TranslationTree };
+
+// `DeploymentConfig` is a type alias in op-deployment-configs, so it can't be augmented in place
+export type DeploymentConfigWithOverrides = DeploymentConfig & {
+  translation_overrides?: TranslationOverrides;
+};