@tolgee/core 4.9.2 → 5.0.0-rc.0b3e627.0

package/src/Controller/Plugins/Plugins.ts

@@ -0,0 +1,305 @@
+import { isPromise, missingOptionError, valueOrPromise } from '../../helpers';
+import {
+  BackendDevInterface,
+  BackendGetRecord,
+  BackendInterface,
+  FormatterInterface,
+  ObserverInterface,
+  TranslatePropsInternal,
+  TranslationOnClick,
+  UiInterface,
+  UiLibInterface,
+  UiType,
+  FinalFormatterInterface,
+  HighlightInterface,
+  UiConstructor,
+  UiKeyOption,
+  LanguageDetectorInterface,
+  LanguageStorageInterface,
+  Options,
+  ChangeTranslationInterface,
+  WrapperWrapProps,
+  Unwrapped,
+} from '../../types';
+import { getFallbackArray } from '../State/helpers';
+
+export const PluginService = (
+  getLanguage: () => string | undefined,
+  getInitialOptions: () => Options,
+  getAvailableLanguages: () => string[] | undefined,
+  getTranslationNs: (props: TranslatePropsInternal) => string[] | string,
+  getTranslation: (props: TranslatePropsInternal) => string | undefined,
+  changeTranslation: ChangeTranslationInterface
+) => {
+  const plugins = {
+    ui: undefined as UiConstructor | undefined,
+  };
+
+  const instances = {
+    formatters: [] as FormatterInterface[],
+    finalFormatter: undefined as FinalFormatterInterface | undefined,
+    observer: undefined as ReturnType<ObserverInterface> | undefined,
+    devBackend: undefined as BackendDevInterface | undefined,
+    backends: [] as BackendInterface[],
+    ui: undefined as UiInterface | undefined,
+    languageDetector: undefined as LanguageDetectorInterface | undefined,
+    languageStorage: undefined as LanguageStorageInterface | undefined,
+  };
+
+  const onClick: TranslationOnClick = async (event, { keysAndDefaults }) => {
+    const withNs: UiKeyOption[] = keysAndDefaults.map(
+      ({ key, ns, defaultValue }) => ({
+        key,
+        defaultValue,
+        ns: getFallbackArray(getTranslationNs({ key, ns, defaultValue })),
+        translation: getTranslation({
+          key,
+          ns,
+        }),
+      })
+    );
+    instances.ui?.handleElementClick(event, withNs);
+  };
+
+  const run = () => {
+    instances.ui =
+      plugins.ui &&
+      new plugins.ui({
+        apiKey: getInitialOptions().apiKey!,
+        apiUrl: getInitialOptions().apiUrl!,
+        highlight,
+        changeTranslation,
+      });
+    instances.observer?.run({ mouseHighlight: Boolean(instances.ui) });
+    checkCorrectConfiguration();
+  };
+
+  const checkCorrectConfiguration = () => {
+    if (instances.languageDetector) {
+      const availableLanguages = getAvailableLanguages();
+      if (!availableLanguages) {
+        throw new Error(missingOptionError('availableLanguages'));
+      }
+    }
+  };
+
+  const stop = () => {
+    instances.ui = undefined;
+    instances.observer?.stop();
+  };
+
+  const highlight: HighlightInterface = (key, ns) => {
+    return instances.observer?.highlight?.(key, ns) || { unhighlight() {} };
+  };
+
+  const translate = (props: TranslatePropsInternal) => {
+    const translation = getTranslation(props);
+    return formatTranslation({ ...props, translation, formatEnabled: true });
+  };
+
+  const setObserver = (observer: ObserverInterface | undefined) => {
+    instances.observer = observer?.({ translate, onClick });
+  };
+
+  const getObserver = () => {
+    return instances.observer;
+  };
+
+  const addFormatter = (formatter: FormatterInterface | undefined) => {
+    if (formatter) {
+      instances.formatters.push(formatter);
+    }
+  };
+
+  const setFinalFormatter = (
+    formatter: FinalFormatterInterface | undefined
+  ) => {
+    instances.finalFormatter = formatter;
+  };
+
+  const setUi = (ui: UiType | undefined) => {
+    plugins.ui = (ui as UiLibInterface)?.UI || ui;
+  };
+
+  const getUi = () => {
+    return plugins.ui;
+  };
+
+  const setLanguageStorage = (
+    storage: LanguageStorageInterface | undefined
+  ) => {
+    instances.languageStorage = storage;
+  };
+
+  const setStoredLanguage = (language: string) => {
+    instances.languageStorage?.setLanguage(language);
+  };
+
+  const setLanguageDetector = (
+    detector: LanguageDetectorInterface | undefined
+  ) => {
+    instances.languageDetector = detector;
+  };
+
+  const detectLanguage = () => {
+    if (!instances.languageDetector) {
+      return undefined;
+    }
+
+    const availableLanguages = getAvailableLanguages()!;
+
+    return instances.languageDetector.getLanguage({
+      availableLanguages,
+    });
+  };
+
+  const getInitialLanguage = () => {
+    const availableLanguages = getAvailableLanguages();
+    const languageOrPromise = instances.languageStorage?.getLanguage();
+
+    return valueOrPromise(languageOrPromise, (language) => {
+      if (
+        (!availableLanguages || availableLanguages.includes(language!)) &&
+        language
+      ) {
+        return language;
+      }
+      return detectLanguage();
+    });
+  };
+
+  const addBackend = (backend: BackendInterface | undefined) => {
+    if (backend) {
+      instances.backends.push(backend);
+    }
+  };
+
+  const setDevBackend = (backend: BackendDevInterface | undefined) => {
+    instances.devBackend = backend;
+  };
+
+  const getDevBackend = () => {
+    return instances.devBackend;
+  };
+
+  const getBackendDevRecord: BackendGetRecord = ({ language, namespace }) => {
+    return instances.devBackend?.getRecord({
+      apiKey: getInitialOptions().apiKey,
+      apiUrl: getInitialOptions().apiUrl,
+      language,
+      namespace,
+    });
+  };
+
+  const getBackendRecord: BackendGetRecord = ({ language, namespace }) => {
+    for (const backend of instances.backends) {
+      const data = backend.getRecord({ language, namespace });
+      if (isPromise(data)) {
+        return data?.catch((e) => {
+          // eslint-disable-next-line no-console
+          console.error(e);
+          return {};
+        });
+      }
+      if (data !== undefined) {
+        return data;
+      }
+    }
+    return undefined;
+  };
+
+  const formatTranslation = ({
+    key,
+    translation,
+    defaultValue,
+    noWrap,
+    params,
+    orEmpty,
+    ns,
+    formatEnabled,
+  }: TranslatePropsInternal & { formatEnabled?: boolean }) => {
+    const formattableTranslation = translation || defaultValue;
+    let result = formattableTranslation || (orEmpty ? '' : key);
+    if (instances.observer && !noWrap) {
+      result = instances.observer.wrap({
+        key,
+        translation: result,
+        defaultValue,
+        params,
+        ns,
+      });
+    }
+
+    const language = getLanguage();
+    const isFormatEnabled =
+      formatEnabled || !instances.observer?.outputNotFormattable;
+    if (formattableTranslation && language && isFormatEnabled) {
+      for (const formatter of instances.formatters) {
+        result = formatter.format({
+          translation: result,
+          language,
+          params,
+        });
+      }
+    }
+
+    if (
+      instances.finalFormatter &&
+      formattableTranslation &&
+      language &&
+      isFormatEnabled
+    ) {
+      result = instances.finalFormatter.format({
+        translation: result,
+        language,
+        params,
+      });
+    }
+    return result;
+  };
+
+  const wrap = (params: WrapperWrapProps) => {
+    if (instances.observer) {
+      return instances.observer?.wrap(params);
+    }
+    return params.translation;
+  };
+
+  const unwrap = (text: string): Unwrapped => {
+    if (instances.observer) {
+      return instances.observer?.unwrap(text);
+    }
+    return { text, keys: [] };
+  };
+
+  const retranslate = () => {
+    instances.observer?.retranslate();
+  };
+
+  return Object.freeze({
+    setFinalFormatter,
+    addFormatter,
+    formatTranslation,
+    setObserver,
+    getObserver,
+    setUi,
+    getUi,
+    addBackend,
+    setDevBackend,
+    getDevBackend,
+    getBackendRecord,
+    getBackendDevRecord,
+    setLanguageDetector,
+    setLanguageStorage,
+    getInitialLanguage,
+    setStoredLanguage,
+    run,
+    stop,
+    retranslate,
+    highlight,
+    wrap,
+    unwrap,
+  });
+};
+
+export type PluginServiceType = ReturnType<typeof PluginService>;

package/src/Controller/State/State.ts

@@ -0,0 +1,165 @@
+import {
+  CacheDescriptor,
+  CacheDescriptorInternal,
+  EventEmitterType,
+  FallbackNSTranslation,
+} from '../../types';
+import { decodeCacheKey } from '../Cache/helpers';
+import { getFallbackArray, getFallbackFromStruct, unique } from './helpers';
+import { initState, Options } from './initState';
+
+export const State = (
+  onLanguageChange: EventEmitterType<string>,
+  onPendingLanguageChange: EventEmitterType<string>,
+  onRunningChange: EventEmitterType<boolean>
+) => {
+  let state = initState();
+
+  function init(options?: Partial<Options>) {
+    state = initState(options, state);
+  }
+
+  function isRunning() {
+    return state.isRunning;
+  }
+
+  function setRunning(value: boolean) {
+    if (state.isRunning !== value) {
+      state.isRunning = value;
+      onRunningChange.emit(value);
+    }
+  }
+
+  function isInitialLoading() {
+    return state.isInitialLoading;
+  }
+
+  function setInitialLoading(value: boolean) {
+    state.isInitialLoading = value;
+  }
+
+  function getLanguage() {
+    return state.language || state.initialOptions.language;
+  }
+
+  function getLanguageOrFail() {
+    const language = state.language || state.initialOptions.language;
+    if (!language) {
+      throw new Error(`No language set`);
+    }
+    return language;
+  }
+
+  function setLanguage(language: string) {
+    if (state.language !== language) {
+      state.language = language;
+      onLanguageChange.emit(language);
+    }
+  }
+
+  function getPendingLanguage() {
+    return state.pendingLanguage || getLanguage();
+  }
+
+  function setPendingLanguage(language: string) {
+    if (state.pendingLanguage !== language) {
+      state.pendingLanguage = language;
+      onPendingLanguageChange.emit(language);
+    }
+  }
+
+  function getInitialOptions() {
+    return state.initialOptions;
+  }
+
+  function addActiveNs(ns: FallbackNSTranslation) {
+    const namespaces = getFallbackArray(ns);
+    namespaces.forEach((namespace) => {
+      const value = state.activeNamespaces.get(namespace);
+      if (value !== undefined) {
+        state.activeNamespaces.set(namespace, value + 1);
+      } else {
+        state.activeNamespaces.set(namespace, 1);
+      }
+    });
+  }
+
+  function removeActiveNs(ns: FallbackNSTranslation) {
+    const namespaces = getFallbackArray(ns);
+    namespaces.forEach((namespace) => {
+      const value = state.activeNamespaces.get(namespace);
+      if (value !== undefined && value > 1) {
+        state.activeNamespaces.set(namespace, value - 1);
+      } else {
+        state.activeNamespaces.delete(namespace);
+      }
+    });
+  }
+
+  function getRequiredNamespaces() {
+    return unique([
+      ...(state.initialOptions.ns || [state.initialOptions.defaultNs]),
+      ...state.activeNamespaces.keys(),
+    ]);
+  }
+
+  function getFallbackLangs(lang?: string) {
+    const language = lang || getLanguage();
+    if (!language) {
+      return [];
+    }
+    return unique([
+      language,
+      ...getFallbackFromStruct(language, state.initialOptions.fallbackLanguage),
+    ]);
+  }
+
+  function getFallbackNamespaces() {
+    const defaultNs = state.initialOptions.defaultNs;
+    const fallbackNs = state.initialOptions.fallbackNs;
+    const fallbackNamespaces = typeof defaultNs === 'string' ? [defaultNs] : [];
+    return unique([...fallbackNamespaces, ...getFallbackArray(fallbackNs)]);
+  }
+
+  function getAvailableLanguages() {
+    if (state.initialOptions.availableLanguages) {
+      return state.initialOptions.availableLanguages;
+    } else if (state.initialOptions.staticData) {
+      const languagesFromStaticData = Object.keys(
+        state.initialOptions.staticData
+      ).map((key) => decodeCacheKey(key).language);
+      return Array.from(new Set(languagesFromStaticData));
+    }
+  }
+
+  function withDefaultNs(descriptor: CacheDescriptor): CacheDescriptorInternal {
+    return {
+      namespace:
+        descriptor.namespace === undefined
+          ? getInitialOptions().defaultNs
+          : descriptor.namespace,
+      language: descriptor.language,
+    };
+  }
+
+  return Object.freeze({
+    init,
+    isRunning,
+    setRunning,
+    isInitialLoading,
+    setInitialLoading,
+    getLanguage,
+    getLanguageOrFail,
+    setLanguage,
+    getPendingLanguage,
+    setPendingLanguage,
+    getInitialOptions,
+    addActiveNs,
+    removeActiveNs,
+    getRequiredNamespaces,
+    getFallbackLangs,
+    getFallbackNamespaces,
+    getAvailableLanguages,
+    withDefaultNs,
+  });
+};

package/src/Controller/State/helpers.ts

@@ -0,0 +1,41 @@
+import {
+  FallbackGeneral,
+  FallbackLanguage,
+  FallbackLanguageObject,
+  FallbackLanguageOption,
+} from '../../types';
+
+export function isObject(item: any) {
+  return typeof item === 'object' && !Array.isArray(item) && item !== null;
+}
+
+export function getFallback(value: FallbackGeneral): string[] | undefined {
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return undefined;
+}
+
+export function getFallbackArray(value: FallbackGeneral): string[] {
+  return getFallback(value) || [];
+}
+
+export function getFallbackFromStruct(
+  language: string,
+  fallbackLanguage: FallbackLanguageOption
+) {
+  if (isObject(fallbackLanguage)) {
+    return getFallbackArray(
+      (fallbackLanguage as FallbackLanguageObject)?.[language]
+    );
+  } else {
+    return getFallbackArray(fallbackLanguage as FallbackLanguage);
+  }
+}
+
+export function unique<T>(arr: T[]) {
+  return Array.from(new Set(arr));
+}

package/src/Controller/State/initState.ts

@@ -0,0 +1,90 @@
+import {
+  FallbackLanguageOption,
+  FallbackNS,
+  TreeTranslationsData,
+} from '../../types';
+
+export type Options = {
+  /**
+   * Initial language
+   */
+  language?: string;
+  apiUrl?: string;
+  apiKey?: string;
+  projectId?: number;
+  /**
+   * Used when auto detection is not available or is turned off
+   */
+  defaultLanguage?: string;
+  /**
+   * Languages which can be used for language detection
+   * and also limits which values can be stored
+   */
+  availableLanguages?: string[];
+  /**
+   * Language which is used when no translation is available for current one
+   */
+  fallbackLanguage?: FallbackLanguageOption;
+  /**
+   * Store user language in localStorage (default: true)
+   */
+  enableLanguageStore?: boolean;
+  /**
+   * Namespaces which should be always fetched
+   */
+  ns?: string[];
+  /**
+   * Namespaces to be used to find translation when no explicit namespace set.
+   */
+  fallbackNs?: FallbackNS;
+  /**
+   * Default namespace when no namespace defined (default: '')
+   */
+  defaultNs: string;
+  /**
+   * Prefix used for fetching languages (default: 'i18n/')
+   */
+  filesUrlPrefix: string;
+  staticData?: {
+    [key: string]: TreeTranslationsData | (() => Promise<TreeTranslationsData>);
+  };
+};
+
+export type State = {
+  initialOptions: Options;
+  activeNamespaces: Map<string, number>;
+  language: string | undefined;
+  pendingLanguage: string | undefined;
+  isInitialLoading: boolean;
+  isRunning: boolean;
+};
+
+const defaultValues: Options = {
+  enableLanguageStore: true,
+  defaultNs: '',
+  filesUrlPrefix: 'i18n/',
+};
+
+export const initState = (
+  options?: Partial<Options>,
+  previousState?: State
+): State => {
+  const initialOptions = {
+    ...defaultValues,
+    ...previousState?.initialOptions,
+    ...options,
+  };
+  // remove extra '/' from url end
+  const apiUrl = initialOptions.apiUrl;
+  initialOptions.apiUrl = apiUrl ? apiUrl.replace(/\/+$/, '') : apiUrl;
+
+  return {
+    initialOptions,
+    activeNamespaces:
+      previousState?.activeNamespaces || new Map<string, number>(),
+    language: previousState?.language,
+    pendingLanguage: previousState?.language,
+    isInitialLoading: false,
+    isRunning: false,
+  };
+};

package/src/Controller/ValueObserver.ts

@@ -0,0 +1,23 @@
+export const ValueObserver = <T = any>(
+  initialValue: T,
+  valueGetter: () => T,
+  handler: (value: T) => void
+) => {
+  let previousValue: T = initialValue;
+  function init(value: T) {
+    previousValue = value;
+  }
+  function notify() {
+    const value = valueGetter();
+    if (previousValue !== value) {
+      handler(value);
+    }
+    previousValue = value;
+  }
+  return Object.freeze({
+    init,
+    notify,
+  });
+};
+
+export type ValueObserverInstance<T> = ReturnType<typeof ValueObserver<T>>;

package/src/Events/EventEmitter.ts

@@ -0,0 +1,27 @@
+import { Listener, ListenerHandler } from '../types';
+
+export const EventEmitter = <T>() => {
+  let handlers: ListenerHandler<T>[] = [];
+
+  const listen = (handler: ListenerHandler<T>): Listener => {
+    const handlerWrapper: ListenerHandler<T> = (e) => {
+      handler(e);
+    };
+
+    handlers.push(handlerWrapper);
+
+    return {
+      unsubscribe: () => {
+        handlers = handlers.filter((i) => handlerWrapper !== i);
+      },
+    };
+  };
+
+  const emit = (data: T) => {
+    handlers.forEach((handler) => handler({ value: data }));
+  };
+
+  return Object.freeze({ listen, emit });
+};
+
+export type EventEmitterType<T> = ReturnType<typeof EventEmitter<T>>;