feat: added format specific methods to @replexica/sdk (#264)

Author: maxprilutskiy

.changeset/fair-roses-give.md

@@ -0,0 +1,8 @@
+---
+"@replexica/compiler": minor
+"@replexica/cli": minor
+"@replexica/sdk": minor
+"replexica": minor
+---
+
+added format specific methods to `@replexica/sdk`

packages/cli/src/cli/i18n.ts

@@ -218,13 +218,12 @@ export default new Command()
                 referencePayload[i18nConfig.locale.extraSource] = extraSourcePayload;
               }
 
-              processedPayload = await replexicaEngine.localize(
+              processedPayload = await replexicaEngine.localizeObject(
                 finalPayload,
                 {
                   sourceLocale: i18nConfig.locale.source,
                   targetLocale: targetLocale,
                 },
-                referencePayload,
                 (progress) => {
                   localeOra.text = `(${progress}%) AI localization in progress...`;
                 }

packages/compiler/src/unplg/workers/locale-server.ts

@@ -45,7 +45,7 @@ function createCachedRemoteLocalizer() {
       // create a new cache subobject from the translated changed dictionary
       const dictionaryCacheUpdate = _.mapValues(translatedChangedDictionary, hashValue);
       // merge the dictionary cache update with the existing dictionary cache
-      const newDictionaryCache = { ...dictionaryCache, ...dictionaryCacheUpdate };
+      const newDictionaryCache: Record<string, any> = { ...dictionaryCache, ...dictionaryCacheUpdate };
       // store the new dictionary cache
       cache.set(cacheKey, newDictionaryCache);
       // return the final dictionary
@@ -65,7 +65,7 @@ function createRemoteLocalizer() {
         return dictionary;
       }
 
-      const data = await rplx.localize(dictionary, {
+      const data = await rplx.localizeObject(dictionary, {
         sourceLocale,
         targetLocale,
       });

packages/sdk/README.md

@@ -48,7 +48,7 @@ const replexica = new ReplexicaEngine({
 });
 
 // Localize a JSON payload
-const localizedContent = await replexica.localize(
+const localizedContent = await replexica.localizeObject(
   { myKey: 'Hello, world!' },
   { sourceLocale: 'en', targetLocale: 'es' },
   (progress) => console.log(`Localization progress: ${progress}%`) // Optional progress callback

packages/sdk/src/index.ts

@@ -56,7 +56,7 @@ export class ReplexicaEngine {
    * @param progressCallback - Optional callback function to report progress
    * @returns Localized content
    */
-  async localize(
+  async _localizeRaw(
     payload: Z.infer<typeof payloadSchema>,
     params: Z.infer<typeof localizationParamsSchema>,
     reference?: Z.infer<typeof referenceSchema>,
@@ -178,4 +178,56 @@ export class ReplexicaEngine {
       return 0;
     }
   }
+
+  /**
+   * Localize a typical JavaScript object
+   * @param obj - The object to be localized
+   * @param params - Localization parameters
+   * @param progressCallback - Optional callback function to report progress
+   * @returns Localized object
+   */
+  async localizeObject(
+    obj: Record<string, any>,
+    params: Z.infer<typeof localizationParamsSchema>,
+    progressCallback?: (progress: number) => void
+  ): Promise<Record<string, any>> {
+    return this._localizeRaw(obj, params, undefined, progressCallback);
+  }
+
+  /**
+   * Localize a text document
+   * @param textDocument - The text to be localized
+   * @param params - Localization parameters
+   * @param progressCallback - Optional callback function to report progress
+   * @returns Localized text
+   */
+  async localizeDocument(
+    textDocument: string,
+    params: Z.infer<typeof localizationParamsSchema>,
+    progressCallback?: (progress: number) => void
+  ): Promise<string> {
+    const localized = await this._localizeRaw({ text: textDocument }, params, undefined, progressCallback);
+    return localized.text || '';
+  }
+
+  /**
+   * Localize a chat sequence
+   * @param chat - The chat sequence to be localized
+   * @param params - Localization parameters
+   * @param progressCallback - Optional callback function to report progress
+   * @returns Localized chat sequence
+   */
+  async localizeChat(
+    chat: Array<{ name: string; text: string }>,
+    params: Z.infer<typeof localizationParamsSchema>,
+    progressCallback?: (progress: number) => void
+  ): Promise<Array<{ name: string; text: string }>> {
+
+    const localized = await this._localizeRaw({ chat }, params, undefined, progressCallback);
+
+    return Object.entries(localized).map(([key, value]) => ({
+      name: chat[parseInt(key.split('_')[1])].name,
+      text: value,
+    }));
+  }
 }