Methods and Properties

An instance of the HTApi class provides several methods for you to interact with the library. Using these, you have full control over translations, settings, and interactions with internal components, allowing you to create your own use cases and flow control.

To get a better understanding of the available methods in a class, consider the following example interface:

interface IHTApi {
	stop(): void;
	active(): void;
	desactive(): void;
	setConfig(config: IConfig): void;
	translate(sentence: string): Promise<void>;
	changeAnimationSpeed(speed: CoreSpeed): void;
	registerToggleStateSubscriber(subscriber: (isOpen: boolean) => void): void;
	notifyPromptLink(promptLinkNotification: IPromptLinkNotification | null): void;

	isLoaded: boolean;
}

Properties

isLoaded

• type: boolean
• default: false

A property that indicates whether the library has been loaded.

ATTENTION

This property does not refer to the deactivation state of the library; it is meant to indicate that all necessary data for initializing the library has been loaded correctly.

Methods

active()

• returns: void

A method that starts the library and allows interaction with the API. Without calling this method, no other method will have any effect. We recommend using this method with the custom element ht-button.

desactive()

• returns: void

A method that stops the library and disables interaction with the API. This method is useful when you want to disable the library and allow the user to continue using your application without the translator. This method is also called when the user clicks the disable button in the widget.

setConfig(config: IConfig)

• returns: void
• param: IConfig:

  interface IConfig {
  	avatar: "HUGO" | "MAYA";
  	language: "ptBR" | "enUS" | "enES";
  	parentElement: HTMLElement;
  	signLanguage: "ptBR-bzs" | "en-ase";
  	token: string;
  	theme: {
  		translatorButtonBackground: string;
  		translatorButtonForeground: string;
  		translatorButtonBorder: string;
  		widgetBackground: string;
  		widgetForeground: string;
  		widgetBorder: string;
  		widgetPosition: "left" | "right";
  	};
  	enableComponents?: {
  		promptLink: boolean;
  		widget: boolean;
  	};
  }

A method that sets the library's configurations. This method is useful for changing settings after instantiating HTApi and modifying the properties passed to the constructor.

Recommended use cases:

• change theme based on user interaction;
• change language based on user interaction;
• adjust components as needed.

translate(sentence: string)

• returns: Promise<void>
• param: string

A method that starts translating a text sentence.

stop()

A method that stops any ongoing translation. This method is also called when the user clicks the stop button in the translation window.

changeAnimationSpeed(speed: CoreSpeed)

• returns: void
• param: CoreSpeed

type CoreSpeed = "slow" | "normal" | "fast";

A method that changes the animation speed. This method is triggered when the user clicks the change speed button in the translation window.

registerToggleStateSubscriber(subscriber: (isOpen: boolean) => void)

• returns: void
• param: (isOpen: boolean) => void

A method that provides a subscriber to notify when the translation window is open or closed. You need to pass a callback function as a parameter, and whenever there is a state change, the provided callback will be called with the current state value.

notifyPromptLink(promptLinkNotification: IPromptLinkNotification | null)

• returns: void
• param: IPromptLinkNotification | null

interface IPromptLinkNotification {
	allocatedElement: HTMLElement;
	isAnActionElement: boolean;
	elementToObserveScroll?: HTMLElement;
	handleCallAllocatedElementOnClick?: () => void;
	handleTranslate?: () => void;
	onClose?: () => void;
}

A method to interact with the PromptLink. Since the PromptLink is an agnostic component, no functionality is implemented within it, so the developer must create use cases for it. We provide this method to allow you to control the PromptLink component.

Whenever you want to change the state of the PromptLink, pay attention to the properties you need to pass in IPromptLinkNotification:

• allocatedElement: the element where the PromptLink should be anchored;
• isAnActionElement: indicates whether the provided element is an action element (a button, link, etc.);
• elementToObserveScroll: When the user scrolls on the screen, the PromptLink disappears. However, you need to indicate which element should be observed. If this behavior is unnecessary, simply omit this parameter;
• handleCallAllocatedElementOnClick: the function that the PromptLink should call when the user clicks the action button within the PromptLink;
• handleTranslate: the function that the PromptLink should call when the user clicks the translate button within the PromptLink;
• onClose: a function that is automatically executed when the PromptLink is closed and is useful for cleaning up state if necessary.

In addition to the above properties, if you want to completely clear the current state of the PromptLink, simply pass null as a parameter, which will reset and hide the PromptLink.