@tolgee/core 4.7.0 → 4.7.2

package/src/Tolgee.ts

@@ -0,0 +1,335 @@
+import { TolgeeConfig } from './TolgeeConfig';
+import {
+  InstantProps,
+  InstantPropsTags,
+  TolgeeModule,
+  TranslateProps,
+  TranslatePropsTags,
+  TranslationTags,
+  TranslationParams,
+  TranslationParamsTags,
+} from './types';
+
+import { EventEmitterImpl } from './services/EventEmitter';
+import { DependencyService } from './services/DependencyService';
+
+export class Tolgee {
+  private dependencyService: DependencyService;
+
+  private constructor() {
+    this.dependencyService = new DependencyService();
+  }
+
+  get properties() {
+    return this.dependencyService.properties;
+  }
+
+  public get lang() {
+    return this.properties.currentLanguage;
+  }
+
+  /**
+   * This sets a new language.
+   *
+   * Using this setter can behave buggy when you change languages
+   * too fast, since it changes the language property before
+   * translations are actually loaded.
+   * @deprecated use asynchronous changeLanguage method.
+   */
+  public set lang(newLanguage) {
+    this.properties.currentLanguage = newLanguage;
+
+    this.dependencyService.translationService
+      .loadTranslations(newLanguage)
+      .then(() => {
+        this.emitLangChangeEvent(newLanguage);
+      });
+  }
+
+  public get defaultLanguage() {
+    return this.properties.config.defaultLanguage;
+  }
+
+  public get onLangChange() {
+    return this.dependencyService.eventService.LANGUAGE_CHANGED;
+  }
+
+  public get onTranslationChange() {
+    return this.dependencyService.eventService.TRANSLATION_CHANGED;
+  }
+
+  /**
+   * Is emitted when language is loaded for the first time
+   */
+  public get onLangLoaded() {
+    return this.dependencyService.eventService.LANGUAGE_LOADED;
+  }
+
+  /**
+   * True if loading is needed to wait for Tolgee init.
+   * When translation data are provided statically (using import
+   * as staticData config property) then there is no need for translation
+   * fetching so initial loading is not needed at all.
+   */
+  get initialLoading(): boolean {
+    const currentLang = this.properties.currentLanguage;
+    const fallbackLang = this.properties.config.fallbackLanguage;
+    const fallbackPreloading = this.properties.config.preloadFallback;
+    const isStaticDataProvided = (data?: any) => {
+      return data !== undefined && typeof data !== 'function';
+    };
+
+    return (
+      !isStaticDataProvided(this.properties.config.staticData?.[currentLang]) ||
+      (!!fallbackPreloading &&
+        !isStaticDataProvided(
+          this.properties.config.staticData?.[fallbackLang]
+        ))
+    );
+  }
+
+  private get coreService() {
+    return this.dependencyService.coreService;
+  }
+
+  static use(module: TolgeeModule) {
+    return new Tolgee().use(module);
+  }
+
+  static init(config: TolgeeConfig) {
+    return new Tolgee().init(config);
+  }
+
+  /**
+   * Sets the new language.
+   *
+   * Emits the onLangChange and onLangChangeAndLoad events after
+   * the translations are loaded.
+   *
+   * @return Promise<void> Resolves when translations are loaded
+   */
+  public async changeLanguage(newLanguage: string): Promise<void> {
+    await this.dependencyService.translationService.loadTranslations(
+      newLanguage
+    );
+    this.properties.currentLanguage = newLanguage;
+    this.emitLangChangeEvent(newLanguage);
+  }
+
+  use(module: TolgeeModule) {
+    this.dependencyService.moduleService.addModule(module);
+    return this;
+  }
+
+  init(config: TolgeeConfig) {
+    this.dependencyService.init(config);
+    const { apiKey, apiUrl } = this.dependencyService.properties.config;
+    this.dependencyService.properties.mode =
+      apiKey && apiUrl ? 'development' : 'production';
+
+    return this;
+  }
+
+  public async run(): Promise<void> {
+    this.dependencyService.run();
+    if (this.properties.mode === 'development') {
+      try {
+        await this.coreService.loadApiKeyDetails();
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.error("Couldn't connect to Tolgee");
+        // eslint-disable-next-line no-console
+        console.error(e);
+        this.properties.mode = 'production';
+      }
+    }
+
+    await this.dependencyService.translationService.loadTranslations();
+    await this.dependencyService.pluginManager.run();
+
+    if (this.properties.config.preloadFallback) {
+      await this.dependencyService.translationService.loadTranslations(
+        this.properties.config.fallbackLanguage
+      );
+    }
+
+    await this.refresh();
+
+    if (this.properties.config.watch) {
+      this.dependencyService.observer.observe();
+    }
+  }
+
+  public async refresh() {
+    return this.dependencyService.wrapper.handleSubtree(
+      this.properties.config.targetElement
+    );
+  }
+
+  async translate(props: TranslateProps): Promise<string>;
+  async translate<T>(props: TranslatePropsTags<T>): Promise<TranslationTags<T>>;
+
+  async translate(
+    key: string,
+    params?: TranslationParams,
+    noWrap?: boolean,
+    defaultValue?: string
+  ): Promise<string>;
+  async translate<T>(
+    key: string,
+    params?: TranslationParamsTags<T>,
+    noWrap?: boolean,
+    defaultValue?: string
+  ): Promise<TranslationTags<T>>;
+
+  async translate(
+    keyOrProps: string | TranslatePropsTags<any>,
+    params: TranslationParamsTags<any> = {},
+    noWrap = false,
+    defaultValue: string | undefined = undefined
+  ): Promise<TranslationTags<any>> {
+    const key = typeof keyOrProps === 'string' ? keyOrProps : keyOrProps.key;
+    let orEmpty = undefined;
+    if (typeof keyOrProps === 'object') {
+      const props = keyOrProps as TranslateProps;
+      // if values are not provided in props object, get them from function
+      // params defaults
+      params = props.params !== undefined ? props.params : params;
+      noWrap = props.noWrap !== undefined ? props.noWrap : noWrap;
+      defaultValue =
+        props.defaultValue !== undefined ? props.defaultValue : defaultValue;
+      orEmpty = props.orEmpty;
+    }
+
+    const translation = await this.dependencyService.textService.translate(
+      key,
+      params,
+      undefined,
+      orEmpty,
+      defaultValue
+    );
+
+    if (this.properties.mode === 'development' && !noWrap) {
+      await this.coreService.loadApiKeyDetails();
+      return this.dependencyService.wrapper.wrap(
+        key,
+        params,
+        defaultValue,
+        translation
+      );
+    }
+
+    return translation;
+  }
+
+  wrap(
+    key: string,
+    params?: TranslationParams,
+    defaultValue?: string | undefined,
+    translation?: string
+  ): string;
+  wrap<T>(
+    key: string,
+    params?: TranslationTags<T>,
+    defaultValue?: string | undefined,
+    translation?: TranslationTags<T>
+  ): TranslationTags<T>;
+
+  wrap(
+    key: string,
+    params?: any,
+    defaultValue?: string | undefined,
+    translation?: TranslationTags<any>
+  ): TranslationTags<any> {
+    if (this.properties.mode === 'development') {
+      return this.dependencyService.wrapper.wrap(
+        key,
+        params,
+        defaultValue,
+        translation
+      );
+    } else {
+      return translation || defaultValue;
+    }
+  }
+
+  instant(
+    key: string,
+    params?: TranslationParams,
+    noWrap?: boolean,
+    orEmpty?: boolean,
+    defaultValue?: string
+  ): string;
+  instant<T>(
+    key: string,
+    params?: TranslationParamsTags<T>,
+    noWrap?: boolean,
+    orEmpty?: boolean,
+    defaultValue?: string
+  ): TranslationTags<T>;
+
+  instant(props: InstantProps): string;
+  instant<T>(props: InstantPropsTags<T>): TranslationTags<T>;
+
+  instant(
+    keyOrProps: string | InstantPropsTags<any>,
+    params: TranslationParams = {},
+    noWrap = false,
+    orEmpty?: boolean,
+    defaultValue?: string
+  ) {
+    const key = typeof keyOrProps === 'string' ? keyOrProps : keyOrProps.key;
+    if (typeof keyOrProps === 'object') {
+      const props = keyOrProps as InstantProps;
+      // if values are not provided in props object, get them from function
+      // params defaults
+      params = props.params !== undefined ? props.params : params;
+      noWrap = props.noWrap !== undefined ? props.noWrap : noWrap;
+      defaultValue =
+        props.defaultValue !== undefined ? props.defaultValue : defaultValue;
+      orEmpty = props.orEmpty !== undefined ? props.orEmpty : orEmpty;
+    }
+
+    const translation = this.dependencyService.textService.instant(
+      key,
+      params,
+      undefined,
+      orEmpty,
+      defaultValue
+    );
+
+    if (this.properties.mode === 'development' && !noWrap) {
+      return this.dependencyService.wrapper.wrap(
+        key,
+        params,
+        defaultValue,
+        translation
+      );
+    }
+    return translation;
+  }
+
+  /**
+   * Get currently cached translations for all languages
+   */
+  public getCachedTranslations() {
+    return this.dependencyService.translationService.getCachedTranslations();
+  }
+
+  /**
+   * Loads translations for given language or returns them from cache
+   * @returns Loaded translations
+   */
+  public loadTranslations(lang: string) {
+    return this.dependencyService.translationService.loadTranslations(lang);
+  }
+
+  public stop = () => {
+    this.dependencyService.stop();
+  };
+
+  private emitLangChangeEvent(value: string) {
+    const langChangedEmitter = this.onLangChange as EventEmitterImpl<any>;
+    langChangedEmitter.emit(value);
+  }
+}

package/src/TolgeeConfig.test.ts

@@ -0,0 +1,21 @@
+jest.dontMock('./TolgeeConfig');
+
+import { TolgeeConfig } from './TolgeeConfig';
+
+describe('TolgeeConfig', () => {
+  test('will be created with default targetElement', () => {
+    const tolgeeConfig = new TolgeeConfig();
+    expect(tolgeeConfig.targetElement).toEqual(document.body);
+  });
+
+  test('will be created with provided targetElement', () => {
+    const div = document.createElement('div');
+    const tolgeeConfig = new TolgeeConfig({ targetElement: div });
+    expect(tolgeeConfig.targetElement).toEqual(div);
+  });
+
+  test('will be created with default when empty object', () => {
+    const tolgeeConfig = new TolgeeConfig({});
+    expect(tolgeeConfig.targetElement).toEqual(document.body);
+  });
+});

package/src/TolgeeConfig.ts

@@ -0,0 +1,134 @@
+import { TreeTranslationsData } from './types';
+import { NodeHelper } from './helpers/NodeHelper';
+import { ModifierKey } from './Constants/ModifierKey';
+import { Mode } from 'fs';
+
+const API_KEY_LOCAL_STORAGE = '__tolgee_apiKey';
+const API_URL_LOCAL_STORAGE = '__tolgee_apiUrl';
+
+const DEFAULT_TARGET_ELEMENT_SUPPLIER = () => {
+  if (typeof document !== 'undefined') {
+    return document.body;
+  }
+};
+
+type UiConstructor = new (...args) => any;
+
+interface UiLibInterface {
+  UI: UiConstructor;
+}
+
+type UiType =
+  | UiConstructor
+  | UiLibInterface
+  | Promise<UiConstructor>
+  | Promise<UiLibInterface>;
+
+export class TolgeeConfig {
+  /**
+   * @deprecated This option won't have any effect,
+   * because mode is now automatically detected when apiKey + apiUrl are set
+   */
+  mode?: Mode;
+  apiUrl?: string;
+  apiKey?: string;
+  inputPrefix?: string = '%-%tolgee:';
+  inputSuffix?: string = '%-%';
+  /**
+   * Overrides all language settings
+   */
+  forceLanguage?: string;
+  /**
+   * Used when auto detection is not available or is turned off
+   */
+  defaultLanguage?: string = 'en';
+  /**
+   * 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?: string;
+  /**
+   * Store user language in localStorage (default: true)
+   */
+  enableLanguageStore?: boolean = true;
+  /**
+   * Use auto language detection by browser locale (default: true)
+   */
+  enableLanguageDetection?: boolean = true;
+  filesUrlPrefix?: string = 'i18n/';
+  watch?: boolean;
+  ui?: UiType;
+  targetElement?: Element;
+  tagAttributes?: { [key: string]: string[] } = {
+    textarea: ['placeholder'],
+    input: ['value', 'placeholder'],
+    img: ['alt'],
+    '*': ['aria-label', 'title'],
+  };
+  highlightKeys?: ModifierKey[] = [ModifierKey.Alt];
+  passToParent?:
+    | (keyof HTMLElementTagNameMap)[]
+    | ((node: Element) => boolean) = ['option', 'optgroup'];
+  restrictedElements?: string[] = ['script', 'style'];
+  highlightColor?: string = 'rgb(255, 0, 0)';
+  highlightWidth?: number = 5;
+  /** localization data to use in production mode */
+  staticData?: {
+    [key: string]: TreeTranslationsData | (() => Promise<TreeTranslationsData>);
+  };
+  wrapperMode?: 'text' | 'invisible' = 'text';
+
+  /**
+   * When true, fallback language will be preloaded on Tolgee.run
+   */
+  preloadFallback?: boolean = false;
+  private _targetElement?: Element;
+
+  constructor(config?: TolgeeConfig) {
+    //workaround for: https://stackoverflow.com/questions/48725916/typescript-optional-property-with-a-getter
+    Object.defineProperty(this, 'targetElement', {
+      set(targetElement: Element) {
+        if (this.targetElement !== undefined) {
+          throw new Error('Target element is already defined!');
+        }
+        if (targetElement === undefined) {
+          this._targetElement = DEFAULT_TARGET_ELEMENT_SUPPLIER();
+        }
+        if (NodeHelper.isElementTargetElement(targetElement)) {
+          // eslint-disable-next-line no-console
+          console.error('Target element: ', this._targetElement);
+          throw new Error(
+            'An tolgee instance is inited with provided target element'
+          );
+        }
+        this._targetElement = targetElement;
+        NodeHelper.markElementAsTargetElement(this._targetElement);
+      },
+      get() {
+        return this._targetElement;
+      },
+    });
+
+    Object.assign(this, config || {});
+    if (typeof sessionStorage !== 'undefined') {
+      this.apiUrl =
+        sessionStorage.getItem(API_URL_LOCAL_STORAGE) || this.apiUrl;
+      this.apiKey =
+        sessionStorage.getItem(API_KEY_LOCAL_STORAGE) || this.apiKey;
+    }
+    if (this._targetElement === undefined) {
+      this._targetElement = DEFAULT_TARGET_ELEMENT_SUPPLIER();
+    }
+    this.fallbackLanguage = this.fallbackLanguage || this.defaultLanguage;
+    if (this.watch === undefined) {
+      this.watch = Boolean(this.apiKey && this.apiUrl);
+    }
+    if (this.availableLanguages === undefined && this.staticData) {
+      this.availableLanguages = Object.keys(this.staticData);
+    }
+  }
+}

package/src/__integration/FormatterIcu.test.ts

@@ -0,0 +1,80 @@
+jest.autoMockOff();
+
+import '@testing-library/jest-dom/extend-expect';
+import { IcuFormatter, Tolgee } from '../index';
+import mockTranslations from './mockTranslations';
+import fetchMock from 'jest-fetch-mock';
+import { testConfig } from './testConfig';
+
+const API_URL = 'http://localhost';
+const API_KEY = 'dummyApiKey';
+
+const fetch = fetchMock.mockResponse(async (req) => {
+  if (req.url.includes('/v2/api-keys/current')) {
+    return JSON.stringify(testConfig);
+  } else if (req.url.includes('/v2/projects/translations/en')) {
+    return JSON.stringify(mockTranslations);
+  }
+  throw new Error('Invalid request');
+});
+
+describe('Tolgee with icu formatter', () => {
+  let tolgee: Tolgee;
+  beforeEach(async () => {
+    fetch.enableMocks();
+    tolgee = Tolgee.use(IcuFormatter).init({
+      targetElement: document.body,
+      apiKey: API_KEY,
+      apiUrl: API_URL,
+      inputPrefix: '{{',
+      inputSuffix: '}}',
+      watch: false,
+    });
+    document.body.innerHTML = '';
+    await tolgee.run();
+  });
+
+  afterEach(() => {
+    tolgee.stop();
+  });
+
+  it('Formats variable', async () => {
+    const translation = await tolgee.translate(
+      'peter_dogs',
+      { dogsCount: '10' },
+      true
+    );
+    expect(translation).toEqual('Peter has 10 dogs.');
+
+    const instantTranslation = tolgee.instant(
+      'peter_dogs',
+      { dogsCount: '10' },
+      true
+    );
+    expect(instantTranslation).toEqual('Peter has 10 dogs.');
+  });
+
+  it('Wont format key', async () => {
+    const translation = await tolgee.translate(
+      'weird {key}',
+      { key: '10' },
+      true
+    );
+    expect(translation).toEqual('weird {key}');
+
+    const instantTranslation = tolgee.instant(
+      'weird {key}',
+      { key: '10' },
+      true
+    );
+    expect(instantTranslation).toEqual('weird {key}');
+  });
+
+  it('Returns key if missing', async () => {
+    const translation = await tolgee.translate('nonexistant', undefined, true);
+    expect(translation).toEqual('nonexistant');
+
+    const instantTranslation = tolgee.instant('nonexistant', undefined, true);
+    expect(instantTranslation).toEqual('nonexistant');
+  });
+});

package/src/__integration/FormatterMissing.ts

@@ -0,0 +1,54 @@
+jest.autoMockOff();
+
+import '@testing-library/jest-dom/extend-expect';
+import { Tolgee } from '..';
+import mockTranslations from './mockTranslations';
+import fetchMock from 'jest-fetch-mock';
+import { testConfig } from './testConfig';
+
+const API_URL = 'http://localhost';
+const API_KEY = 'dummyApiKey';
+
+const fetch = fetchMock.mockResponse(async (req) => {
+  if (req.url.includes('/v2/api-keys/current')) {
+    return JSON.stringify(testConfig);
+  } else if (req.url.includes('/v2/projects/translations/en')) {
+    return JSON.stringify(mockTranslations);
+  }
+  throw new Error('Invalid request');
+});
+
+describe('Tolgee without formatter', () => {
+  let tolgee: Tolgee;
+  beforeEach(async () => {
+    fetch.enableMocks();
+    tolgee = Tolgee.init({
+      targetElement: document.body,
+      apiKey: API_KEY,
+      apiUrl: API_URL,
+      watch: false,
+    });
+    document.body.innerHTML = '';
+    await tolgee.run();
+  });
+
+  afterEach(() => {
+    tolgee.stop();
+  });
+
+  it('Returns plain translation', async () => {
+    const translation = await tolgee.translate('peter_dogs', undefined, true);
+    expect(translation).toEqual('Peter has {dogsCount} dogs.');
+
+    const instantTranslation = tolgee.instant('peter_dogs', undefined, true);
+    expect(instantTranslation).toEqual('Peter has {dogsCount} dogs.');
+  });
+
+  it('Returns key if missing', async () => {
+    const translation = await tolgee.translate('nonexistant', undefined, true);
+    expect(translation).toEqual('nonexistant');
+
+    const instantTranslation = tolgee.instant('nonexistant', undefined, true);
+    expect(instantTranslation).toEqual('nonexistant');
+  });
+});