@rimori/client 1.4.5 → 1.4.8

package/src/fromRimori/EventBus.ts

@@ -3,9 +3,9 @@ export type EventPayload = Record<string, any>;
 
 /**
  * Interface representing a message sent through the EventBus
- *
+ * 
  * Debug capabilities:
- * - System-wide debugging: Send an event to "global.system.requestDebug"
+ * - System-wide debugging: Send an event to "global.system.requestDebug" 
  *   Example: `EventBus.emit("yourPluginId", "global.system.requestDebug");`
  */
 export interface EventBusMessage<T = EventPayload> {
@@ -40,7 +40,7 @@ export class EventBusHandler {
   private responseResolvers: Map<number, (value: EventBusMessage<unknown>) => void> = new Map();
   private static instance: EventBusHandler | null = null;
   private debugEnabled: boolean = false;
-  private evName: string = '';
+  private evName: string = "";
 
   private constructor() {
     //private constructor
@@ -50,14 +50,12 @@ export class EventBusHandler {
     if (!EventBusHandler.instance) {
       EventBusHandler.instance = new EventBusHandler();
 
-      EventBusHandler.instance.on('global.system.requestDebug', () => {
+      EventBusHandler.instance.on("global.system.requestDebug", () => {
         EventBusHandler.instance!.debugEnabled = true;
-        console.log(
-          `[${EventBusHandler.instance!.evName}] Debug mode enabled. Make sure debugging messages are enabled in the browser console.`,
-        );
+        console.log(`[${EventBusHandler.instance!.evName}] Debug mode enabled. Make sure debugging messages are enabled in the browser console.`);
       });
     }
-    if (name && EventBusHandler.instance.evName === '') {
+    if (name && EventBusHandler.instance.evName === "") {
       EventBusHandler.instance.evName = name;
     }
     return EventBusHandler.instance;
@@ -82,9 +80,9 @@ export class EventBusHandler {
    * @param topic - The topic of the event.
    * @param data - The data of the event.
    * @param eventId - The event id of the event.
-   *
+   * 
    * The topic format is: **pluginId.area.action**
-   *
+   * 
    * Example topics:
    * - pl1234.card.requestHard
    * - pl1234.card.requestNew
@@ -98,13 +96,7 @@ export class EventBusHandler {
     this.emitInternal(sender, topic, data || {}, eventId);
   }
 
-  private emitInternal(
-    sender: string,
-    topic: string,
-    data: EventPayload,
-    eventId?: number,
-    skipResponseTrigger = false,
-  ): void {
+  private emitInternal(sender: string, topic: string, data: EventPayload, eventId?: number, skipResponseTrigger = false): void {
     if (!this.validateTopic(topic)) {
       this.logAndThrowError(false, `Invalid topic: ` + topic);
       return;
@@ -113,7 +105,7 @@ export class EventBusHandler {
     const event = this.createEvent(sender, topic, data, eventId);
 
     const handlers = this.getMatchingHandlers(event.topic);
-    handlers.forEach((handler) => {
+    handlers.forEach(handler => {
       if (handler.ignoreSender && handler.ignoreSender.includes(sender)) {
         // console.log("ignore event as its in the ignoreSender list", { event, ignoreList: handler.ignoreSender });
         return;
@@ -140,12 +132,8 @@ export class EventBusHandler {
    * @param ignoreSender - The senders to ignore.
    * @returns An EventListener object containing an off() method to unsubscribe the listeners.
    */
-  public on<T = EventPayload>(
-    topics: string | string[],
-    handler: EventHandler<T>,
-    ignoreSender: string[] = [],
-  ): EventListener {
-    const ids = this.toArray(topics).map((topic) => {
+  public on<T = EventPayload>(topics: string | string[], handler: EventHandler<T>, ignoreSender: string[] = []): EventListener {
+    const ids = this.toArray(topics).map(topic => {
       this.logIfDebug(`Subscribing to ` + topic, { ignoreSender });
       if (!this.validateTopic(topic)) {
         this.logAndThrowError(true, `Invalid topic: ` + topic);
@@ -166,7 +154,7 @@ export class EventBusHandler {
     });
 
     return {
-      off: () => this.off(ids),
+      off: () => this.off(ids)
     };
   }
 
@@ -177,41 +165,33 @@ export class EventBusHandler {
    * @param handler - The handler to be called when the event is received. The handler returns the data to be emitted. Can be a static object or a function.
    * @returns An EventListener object containing an off() method to unsubscribe the listeners.
    */
-  public respond(
-    sender: string,
-    topic: string | string[],
-    handler: EventPayload | ((data: EventBusMessage) => EventPayload | Promise<EventPayload>),
-  ): EventListener {
+  public respond(sender: string, topic: string | string[], handler: EventPayload | ((data: EventBusMessage) => EventPayload | Promise<EventPayload>)): EventListener {
     const topics = Array.isArray(topic) ? topic : [topic];
-    const listeners = topics.map((topic) => {
+    const listeners = topics.map(topic => {
       const blackListedEventIds: number[] = [];
       //To allow event communication inside the same plugin the sender needs to be ignored but the events still need to be checked for the same event just reaching the subscriber to prevent infinite loops
-      const finalIgnoreSender = !topic.startsWith('self.') ? [sender] : [];
-
-      const listener = this.on(
-        topic,
-        async (data: EventBusMessage) => {
-          if (blackListedEventIds.includes(data.eventId)) {
-            // console.log("BLACKLISTED EVENT ID", data.eventId);
-            return;
-          }
-          blackListedEventIds.push(data.eventId);
-          if (blackListedEventIds.length > 20) {
-            blackListedEventIds.shift();
-          }
-          const response = typeof handler === 'function' ? await handler(data) : handler;
-          this.emit(sender, topic, response, data.eventId);
-        },
-        finalIgnoreSender,
-      );
-
-      this.logIfDebug(`Added respond listener ` + sender + ' to topic ' + topic, { listener, sender });
+      const finalIgnoreSender = !topic.startsWith("self.") ? [sender] : [];
+
+      const listener = this.on(topic, async (data: EventBusMessage) => {
+        if (blackListedEventIds.includes(data.eventId)) {
+          // console.log("BLACKLISTED EVENT ID", data.eventId);
+          return;
+        }
+        blackListedEventIds.push(data.eventId);
+        if (blackListedEventIds.length > 20) {
+          blackListedEventIds.shift();
+        }
+        const response = typeof handler === "function" ? await handler(data) : handler;
+        this.emit(sender, topic, response, data.eventId);
+      }, finalIgnoreSender);
+
+      this.logIfDebug(`Added respond listener ` + sender + " to topic " + topic, { listener, sender });
       return {
-        off: () => listener.off(),
+        off: () => listener.off()
       };
     });
     return {
-      off: () => listeners.forEach((listener) => listener.off()),
+      off: () => listeners.forEach(listener => listener.off())
     };
   }
 
@@ -241,12 +221,12 @@ export class EventBusHandler {
    * @param listenerIds - The ids of the listeners to unsubscribe from.
    */
   private off(listenerIds: string | string[]): void {
-    this.toArray(listenerIds).forEach((fullId) => {
+    this.toArray(listenerIds).forEach(fullId => {
       const { topic, id } = JSON.parse(atob(fullId));
 
       const listeners = this.listeners.get(topic) || new Set();
 
-      listeners.forEach((listener) => {
+      listeners.forEach(listener => {
         if (listener.id === Number(id)) {
           listeners.delete(listener);
           this.logIfDebug(`Removed listener ` + fullId, { topic, listenerId: id });
@@ -266,11 +246,7 @@ export class EventBusHandler {
    * @param data - The data of the event.
    * @returns A promise that resolves to the event.
    */
-  public async request<T = EventPayload>(
-    sender: string,
-    topic: string,
-    data?: EventPayload,
-  ): Promise<EventBusMessage<T>> {
+  public async request<T = EventPayload>(sender: string, topic: string, data?: EventPayload): Promise<EventBusMessage<T>> {
     if (!this.validateTopic(topic)) {
       this.logAndThrowError(true, `Invalid topic: ` + topic);
     }
@@ -279,10 +255,8 @@ export class EventBusHandler {
 
     this.logIfDebug(`Requesting data from ` + topic, { event });
 
-    return new Promise<EventBusMessage<T>>((resolve) => {
-      this.responseResolvers.set(event.eventId, (value: EventBusMessage<unknown>) =>
-        resolve(value as EventBusMessage<T>),
-      );
+    return new Promise<EventBusMessage<T>>(resolve => {
+      this.responseResolvers.set(event.eventId, (value: EventBusMessage<unknown>) => resolve(value as EventBusMessage<T>));
       this.emitInternal(sender, topic, data || {}, event.eventId, true);
     });
   }
@@ -297,7 +271,7 @@ export class EventBusHandler {
 
     // Find wildcard matches
     const wildcard = [...this.listeners.entries()]
-      .filter(([key]) => key.endsWith('*') && topic.startsWith(key.slice(0, -1)))
+      .filter(([key]) => key.endsWith("*") && topic.startsWith(key.slice(0, -1)))
       .flatMap(([_, handlers]) => [...handlers]);
     return new Set([...exact, ...wildcard]);
   }
@@ -309,35 +283,32 @@ export class EventBusHandler {
    */
   private validateTopic(topic: string): boolean {
     // Split event type into parts
-    const parts = topic.split('.');
+    const parts = topic.split(".");
     const [plugin, area, action] = parts;
 
     if (parts.length !== 3) {
-      if (parts.length === 1 && plugin === '*') {
+      if (parts.length === 1 && plugin === "*") {
         return true;
       }
-      if (parts.length === 2 && plugin !== '*' && area === '*') {
+      if (parts.length === 2 && plugin !== "*" && area === "*") {
         return true;
       }
       this.logAndThrowError(false, `Event type must have 3 parts separated by dots. Received: ` + topic);
       return false;
     }
 
-    if (action === '*') {
+    if (action === "*") {
       return true;
     }
 
     // Validate action part
-    const validActions = ['request', 'create', 'update', 'delete', 'trigger'];
+    const validActions = ["request", "create", "update", "delete", "trigger"];
 
-    if (validActions.some((a) => action.startsWith(a))) {
+    if (validActions.some(a => action.startsWith(a))) {
       return true;
     }
 
-    this.logAndThrowError(
-      false,
-      `Invalid event topic name. The action: ` + action + '. Must be or start with one of: ' + validActions.join(', '),
-    );
+    this.logAndThrowError(false, `Invalid event topic name. The action: ` + action + ". Must be or start with one of: " + validActions.join(", "));
     return false;
   }
 
@@ -356,4 +327,4 @@ export class EventBusHandler {
   }
 }
 
-export const EventBus = EventBusHandler.getInstance();
+export const EventBus = EventBusHandler.getInstance();

package/src/fromRimori/PluginTypes.ts

@@ -4,10 +4,10 @@ export type Plugin<T extends {} = {}> = Omit<RimoriPluginConfig<T>, 'context_men
   endpoint: string;
   assetEndpoint: string;
   context_menu_actions: MenuEntry[];
-  release_channel: 'alpha' | 'beta' | 'stable';
-};
+  release_channel: "alpha" | "beta" | "stable";
+}
 
-export type ActivePlugin = Plugin<{ active?: boolean }>;
+export type ActivePlugin = Plugin<{ active?: boolean }>
 
 // browsable page of a plugin
 export interface PluginPage {
@@ -17,22 +17,13 @@ export interface PluginPage {
   // Whether the page should be shown in the navbar
   show: boolean;
   description: string;
-  root:
-    | 'vocabulary'
-    | 'grammar'
-    | 'reading'
-    | 'listening'
-    | 'watching'
-    | 'writing'
-    | 'speaking'
-    | 'other'
-    | 'community';
+  root: "vocabulary" | "grammar" | "reading" | "listening" | "watching" | "writing" | "speaking" | "other" | "community";
   // The actions that can be triggered in the plugin
   // The key is the action key. The other entries are additional properties needed when triggering the action
   action?: {
     key: string;
     parameters: ObjectTool;
-  };
+  }
 }
 
 // a sidebar page of a plugin
@@ -74,7 +65,7 @@ export interface ContextMenuAction {
   // id of the plugin that the action belongs to
   plugin_id: string;
   // key of the action. Used to know which action to trigger when clicking on the context menu
-  action_key: string;
+  action_key: string
 }
 
 /**
@@ -95,7 +86,7 @@ export interface RimoriPluginConfig<T extends {} = {}> {
     logo: string;
     /** Optional website URL for the plugin's homepage or link to plugins owner for contributions */
     website?: string;
-  };
+  }
   /**
    * Configuration for different types of pages.
    */
@@ -110,11 +101,11 @@ export interface RimoriPluginConfig<T extends {} = {}> {
     settings?: string;
     /** Optional array of event topics the plugin pages can listen to for cross-plugin communication */
     topics?: string[];
-  };
+  }
   /**
    * Context menu actions that the plugin registers to appear in right-click menus throughout the application.
    */
-  context_menu_actions: Omit<MenuEntry, 'plugin_id'>[];
+  context_menu_actions: Omit<MenuEntry, "plugin_id">[];
   /**
    * Documentation paths for different types of plugin documentation.
    */
@@ -125,7 +116,7 @@ export interface RimoriPluginConfig<T extends {} = {}> {
     user_path: string;
     /** Path to developer documentation for plugin development */
     developer_path: string;
-  };
+  }
   /**
    * Configuration for the plugin's web worker if it uses background processing or exposes actions to other plugins.
    */
@@ -145,7 +136,7 @@ export interface Tool {
   parameters: {
     name: string;
     description: string;
-    type: 'string' | 'number' | 'boolean';
+    type: "string" | "number" | "boolean";
   }[];
   execute?: (args: Record<string, any>) => Promise<unknown> | unknown | void;
 }
@@ -154,7 +145,7 @@ export interface Tool {
  * The tool definition structure is used for LLM function calling and plugin action parameters.
  * It defines the schema for tools that can be used by Language Learning Models (LLMs)
  * and plugin actions.
- *
+ * 
  * @example
  * ```typescript
  * const flashcardTool: Tool = {
@@ -164,13 +155,13 @@ export interface Tool {
  *     description: 'Number of flashcards to practice'
  *   },
  *   deck: {
- *     type: 'string',
+ *     type: 'string', 
  *     enum: ['latest', 'random', 'oldest', 'mix', 'best_known'],
  *     description: 'Type of deck to practice'
  *   }
  * };
  * ```
- *
+ * 
  */
 export type ObjectTool = {
   [key: string]: ToolParameter;
@@ -197,15 +188,15 @@ interface ToolParameter {
  * Supports primitive types, nested objects for complex data structures,
  * and arrays of objects for collections. The tuple notation [{}] indicates
  * arrays of objects with a specific structure.
- *
+ * 
  * @example Primitive: 'string' | 'number' | 'boolean'
  * @example Nested object: { name: { type: 'string' }, age: { type: 'number' } }
  * @example Array of objects: [{ id: { type: 'string' }, value: { type: 'number' } }]
  */
 type ToolParameterType =
   | PrimitiveType
-  | { [key: string]: ToolParameter } // for nested objects
-  | [{ [key: string]: ToolParameter }]; // for arrays of objects (notice the tuple type)
+  | { [key: string]: ToolParameter }  // for nested objects
+  | [{ [key: string]: ToolParameter }];  // for arrays of objects (notice the tuple type)
 
 /**
  * Primitive data types supported by the LLM tool system.

package/src/hooks/I18nHooks.ts

@@ -0,0 +1,33 @@
+import { TOptions } from 'i18next';
+import { useEffect, useState } from 'react';
+import { Translator } from '../plugin/TranslationController';
+import { useRimori } from '../providers/PluginProvider';
+
+type TranslatorFn = (key: string, options?: TOptions) => string;
+
+/**
+ * Custom useTranslation hook that provides a translation function and indicates readiness
+ * @returns An object containing the translation function (`t`) and a boolean (`ready`) indicating if the translator is initialized.
+ */
+export function useTranslation(): { t: TranslatorFn; ready: boolean } {
+  const { plugin } = useRimori();
+  const [translatorInstance, setTranslatorInstance] = useState<Translator | null>(null);
+
+  useEffect(() => {
+    void plugin.getTranslator().then(setTranslatorInstance);
+  }, [plugin]);
+
+  const safeT = (key: string, options?: TOptions): string => {
+    // return zero-width space if translator is not initialized to keep text space occupied
+    if (!translatorInstance) return '\u200B'; // zero-width space
+
+    const result = translatorInstance.t(key, options);
+    if (!result) {
+      console.error(`Translation key not found: ${key}`);
+      return '\u200B'; // zero-width space
+    }
+    return result;
+  };
+
+  return { t: safeT, ready: translatorInstance !== null };
+}

package/src/index.ts

@@ -6,7 +6,7 @@ export * from './providers/PluginProvider';
 export * from './cli/types/DatabaseTypes';
 export * from './utils/difficultyConverter';
 export * from './utils/PluginUtils';
-export * from './utils/Language';
 export * from './fromRimori/PluginTypes';
 export { FirstMessages } from './components/ai/utils';
 export { AudioController } from './plugin/AudioController';
+export { useTranslation } from './hooks/I18nHooks';

package/src/plugin/RimoriClient.ts

@@ -16,6 +16,7 @@ import { EventBus, EventBusMessage, EventHandler, EventPayload } from '../fromRi
 import { ActivePlugin, MainPanelAction, Plugin, Tool } from '../fromRimori/PluginTypes';
 import { AccomplishmentHandler, AccomplishmentPayload } from './AccomplishmentHandler';
 import { PluginController, RimoriInfo } from './PluginController';
+import { Translator } from './TranslationController';
 
 interface Db {
   from: {
@@ -73,6 +74,7 @@ interface PluginInterface {
     sidePanelPlugin?: ActivePlugin;
   };
   getUserInfo: () => UserInfo;
+  getTranslator: () => Promise<Translator>;
 }
 
 export class RimoriClient {
@@ -84,6 +86,7 @@ export class RimoriClient {
   private exerciseController: ExerciseController;
   private accomplishmentHandler: AccomplishmentHandler;
   private rimoriInfo: RimoriInfo;
+  private translator: Translator;
   public plugin: PluginInterface;
   public db: Db;
 
@@ -95,6 +98,7 @@ export class RimoriClient {
     this.sharedContentController = new SharedContentController(this.superbase, this);
     this.exerciseController = new ExerciseController(supabase, pluginController);
     this.accomplishmentHandler = new AccomplishmentHandler(info.pluginId);
+    this.translator = new Translator(info.profile.mother_tongue.code);
 
     this.from = this.from.bind(this);
     this.getTableName = this.getTableName.bind(this);
@@ -108,7 +112,7 @@ export class RimoriClient {
     };
     this.plugin = {
       pluginId: info.pluginId,
-      setSettings: async (settings: any) => {
+      setSettings: async (settings: any): Promise<void> => {
         await this.settingsController.setSettings(settings);
       },
       getSettings: async <T extends object>(defaultSettings: T): Promise<T> => {
@@ -124,6 +128,10 @@ export class RimoriClient {
           sidePanelPlugin: this.rimoriInfo.sidePanelPlugin,
         };
       },
+      getTranslator: async (): Promise<Translator> => {
+        await this.translator.initialize();
+        return this.translator;
+      },
     };
   }
 

package/src/plugin/TranslationController.ts

@@ -0,0 +1,105 @@
+import { createInstance, ThirdPartyModule, TOptions, i18n as i18nType } from 'i18next';
+
+/**
+ * Translator class for handling internationalization
+ */
+export class Translator {
+  private currentLanguage: string;
+  private isInitialized: boolean;
+  private i18n: i18nType | undefined;
+
+  constructor(initialLanguage: string) {
+    this.isInitialized = false;
+    this.currentLanguage = initialLanguage;
+  }
+
+  /**
+   * Initialize translator with user's language
+   * @param userLanguage - Language code from user info
+   */
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    const translations = await this.fetchTranslations(this.currentLanguage);
+
+    const instance = createInstance({
+      lng: this.currentLanguage,
+      resources: {
+        [this.currentLanguage]: {
+          translation: translations,
+        },
+      },
+      debug: window.location.hostname === 'localhost',
+    });
+
+    await instance.init();
+    this.i18n = instance;
+    this.isInitialized = true;
+  }
+
+  private getTranslationUrl(language: string): string {
+    // For localhost development, use local- prefix for non-English languages
+    const isLocalhost = window.location.hostname === 'localhost';
+    const isEnglish = language === 'en';
+    const filename = isLocalhost && !isEnglish ? `local-${language}` : language;
+
+    return `${window.location.origin}/locales/${filename}.json`;
+  }
+
+  public usePlugin(plugin: ThirdPartyModule): void {
+    if (!this.i18n) {
+      throw new Error('Translator is not initialized');
+    }
+    this.i18n.use(plugin);
+  }
+  /**
+   * Fetch translations manually from the current domain
+   * @param language - Language code to fetch
+   * @returns Promise with translation data
+   */
+  private async fetchTranslations(language: string): Promise<Record<string, string>> {
+    try {
+      const response = await fetch(this.getTranslationUrl(language));
+      if (!response.ok) {
+        throw new Error(`Failed to fetch translations for ${language}`);
+      }
+      return (await response.json()) as Record<string, string>;
+    } catch (error) {
+      console.warn(`Failed to fetch translations for ${language}:`, error);
+      if (language === 'en') return {};
+
+      // Fallback to English
+      return this.fetchTranslations('en').catch((error) => {
+        console.error('Failed to fetch fallback translations:', error);
+        return {};
+      });
+    }
+  }
+
+  /**
+   * Get translation for a key
+   * @param key - Translation key
+   * @param options - Translation options
+   * @returns Translated string
+   */
+  t(key: string, options?: TOptions): string {
+    if (!this.i18n) {
+      throw new Error('Translator is not initialized');
+    }
+    return this.i18n.t(key, options) as string;
+  }
+
+  /**
+   * Get current language
+   */
+  getCurrentLanguage(): string {
+    return this.currentLanguage;
+  }
+
+  /**
+   * Check if translator is initialized
+   */
+  isReady(): boolean {
+    return this.isInitialized;
+  }
+}

package/src/utils/Language.ts

@@ -1,72 +0,0 @@
-export const languageKeys = {
-  sq: 'albanian',
-  ar: 'arabic',
-  hy: 'armenian',
-  az: 'azerbaijani',
-  bn: 'bengali',
-  bs: 'bosnian',
-  bg: 'bulgarian',
-  ca: 'catalan',
-  zh: 'chinese',
-  hr: 'croatian',
-  cs: 'czech',
-  da: 'danish',
-  nl: 'dutch',
-  en: 'english',
-  et: 'estonian',
-  fi: 'finnish',
-  fr: 'french',
-  gl: 'galician',
-  de: 'german',
-  el: 'greek',
-  he: 'hebrew',
-  hi: 'hindi',
-  hu: 'hungarian',
-  is: 'icelandic',
-  id: 'indonesian',
-  it: 'italian',
-  ja: 'japanese',
-  kn: 'kannada',
-  kk: 'kazakh',
-  ko: 'korean',
-  lv: 'latvian',
-  lt: 'lithuanian',
-  mk: 'macedonian',
-  ms: 'malay',
-  mr: 'marathi',
-  mi: 'maori',
-  ne: 'nepali',
-  no: 'norwegian',
-  fa: 'persian',
-  pl: 'polish',
-  pt: 'portuguese',
-  ro: 'romanian',
-  ru: 'russian',
-  sr: 'serbian',
-  sk: 'slovak',
-  sl: 'slovenian',
-  es: 'spanish',
-  sw: 'swahili',
-  sv: 'swedish',
-  tl: 'filipino',
-  ta: 'tamil',
-  th: 'thai',
-  tr: 'turkish',
-  uk: 'ukrainian',
-  ur: 'urdu',
-  vi: 'vietnamese',
-  cy: 'welsh',
-} as const;
-
-export type Language = keyof typeof languageKeys;
-
-/**
- * Get the language name from the language code
- * @param languageCode The code of the language
- * @param capitalize Whether to capitalize the first letter of the language name
- * @returns The language name
- */
-export function getLanguageName(languageCode: Language, capitalize: boolean = false): string {
-  const lang = languageKeys[languageCode];
-  return capitalize ? lang.charAt(0).toUpperCase() + lang.slice(1) : lang;
-}