Merge pull request #6 from samchon/feat/texts

samchon · web-flow · commit 6c76ae726aa6 · 2024-10-16T14:10:52.000+09:00
Enhance `JsonTranslator.detect()` function.
diff --git a/README.md b/README.md
@@ -62,4 +62,136 @@ Also, below is the list of example result files of such translation.
 English (source) | Korean | Japanese | Arabic
 --------|--------|----------|--------
 [bbs.article.json](https://github.com/samchon/json-translator/blob/master/assets/input/bbs.article.json) | [bbs.ko.json](https://github.com/samchon/json-translator/blob/master/assets/output/bbs.article.ko.json) | [bbs.ja.json](https://github.com/samchon/json-translator/blob/master/assets/output/bbs.article.ja.json) | [bbs.ar.json](https://github.com/samchon/json-translator/blob/master/assets/output/bbs.article.ar.json)
-[shopping.swagger.json](https://github.com/samchon/json-translator/blob/master/assets/input/shopping.swagger.json) | [shopping.ko.json](https://github.com/samchon/json-translator/blob/master/assets/output/shopping.swagger.ko.json) | [shopping.ja.json](https://github.com/samchon/json-translator/blob/master/assets/output/shopping.swagger.ja.json) | [shopping.ar.json](https://github.com/samchon/json-translator/blob/master/assets/output/shopping.swagger.ar.json)
+[shopping.swagger.json](https://github.com/samchon/json-translator/blob/master/assets/input/shopping.swagger.json) | [shopping.ko.json](https://github.com/samchon/json-translator/blob/master/assets/output/shopping.swagger.ko.json) | [shopping.ja.json](https://github.com/samchon/json-translator/blob/master/assets/output/shopping.swagger.ja.json) | [shopping.ar.json](https://github.com/samchon/json-translator/blob/master/assets/output/shopping.swagger.ar.json)
+
+
+
+
+## API
+```typescript
+export class JsonTranslator {
+  /**
+   * Translate JSON data.
+   *
+   * `JsonTranslate.translate()` translates JSON input data into another language.
+   *
+   * If you want to filter some specific values to translate, fill the
+   * {@link JsonTranslator.IProps.filter} function.
+   *
+   * Also, if you do not fill the {@link JsonTranslator.IProps.source} value,
+   * the source language would be detected through the {@link JsonTranslator.detect}
+   * method with the longest text. Otherwise you assign the `null` value to the
+   * {@link JsonTranslator.IProps.source}, the translation would be executed without
+   * the source language.
+   *
+   * @template T The type of the JSON input data.
+   * @param props Properties for the translation.
+   * @returns The translated JSON data.
+   */
+  public translate<T>(props: JsonTranslator.IProps<T>): Promise<T>;
+
+  /**
+   * Detect the language of JSON data.
+   *
+   * Pick the longest text from the JSON input data and detect the language
+   * through the Google Translate API, with the similar properties like the
+   * {@link JsonTranslator.translate} method.
+   *
+   * Therefore, if you want to filter some specific values to participate in
+   * the language detection, fill the {@link JsonTranslator.IProps.filter}
+   * function.
+   *
+   * @param input Properties for language detection.
+   * @returns The detected language or `undefined` if the language is unknown.
+   */
+  public detect<T>(
+    props: Omit<JsonTranslator.IProps<T>, "source" | "target">,
+  ): Promise<string | undefined>;
+}
+export namespace JsonTranslator {
+  /**
+   * Properties for the translation.
+   */
+  export interface IProps<T> {
+    /**
+     * The JSON input data to translate.
+     */
+    input: T;
+
+    /**
+     * Source language code.
+     *
+     * If not specified (`undefined`), the source language would be detected
+     * through the {@link JsonTranslator.detect} method with the longest text.
+     *
+     * Otherwise `null` value assigned, the source language would be skipped,
+     * so that the translation would be executed without the source language.
+     * Therefore, if your JSON value contains multiple languages, you should
+     * assign the `null` value to prevent the source language specification.
+     */
+    source?: string | null | undefined;
+
+    /**
+     * Target language code.
+     */
+    target: string;
+
+    /**
+     * Filter function specifying which data to translate.
+     *
+     * @param explore Information about the data to explore.
+     * @returns `true` if the data should be translated; otherwise, `false`.
+     */
+    filter?: ((explore: IExplore) => boolean) | null | undefined;
+
+    /**
+     * Reserved dictionary of pre-translated values.
+     *
+     * The dictionary is a key-value pair object containing the pre-translated
+     * values. The key means the original value, and the value means the
+     * pre-translated value.
+     *
+     * If this dictionary has been configured and a JSON input value matches to
+     * the dictionary's key, the dictionary's value would be used instead of
+     * calling the Google Translate API.
+     */
+    dictionary?: Record<string, string> | null | undefined;
+  }
+
+  /**
+   * Exploration information used in the {@link IProps.filter} function.
+   */
+  export interface IExplore {
+    /**
+     * The parent object instance.
+     */
+    object: object | null;
+
+    /**
+     * The property key containing the {@link value}
+     */
+    key: string | null;
+
+    /**
+     * Index number if the {@link value} is an array element.
+     */
+    index: number | null;
+
+    /**
+     * Accessor path to the {@link value}.
+     *
+     * It starts from the `["$input"]` array value, and each element
+     * would be the property key or the index number.
+     *
+     * For example, if there's an access expression `$input.a[0].b`,
+     * the accessor would be `["$input", "a", "0", "b"]`.
+     */
+    accessor: string[];
+
+    /**
+     * The string value to translate.
+     */
+    value: string;
+  }
+}
+```
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@samchon/json-translator",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "JSON Translator via Google Translation API with optimization strategies",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
diff --git a/src/JsonTranslator.ts b/src/JsonTranslator.ts
@@ -47,7 +47,7 @@ export class JsonTranslator {
     const from: string | undefined =
       props.source === null
         ? undefined
-        : (props.source ?? (await this.detect(collection.raw)));
+        : (props.source ?? (await this._Detect_language(collection.raw)));
 
     let queue: Array<IPiece> = [];
     let bytes: number = 0;
@@ -94,19 +94,35 @@ export class JsonTranslator {
   }
 
   /**
-   * Detect the language of the texts.
+   * Detect the language of JSON data.
    *
-   * @param texts Texts to detect the language.
+   * Pick the longest text from the JSON input data and detect the language
+   * through the Google Translate API, with the similar properties like the
+   * {@link JsonTranslator.translate} method.
+   *
+   * Therefore, if you want to filter some specific values to participate in
+   * the language detection, fill the {@link JsonTranslator.IProps.filter}
+   * function.
+   *
+   * @param input Properties for language detection.
    * @returns The detected language or `undefined` if the language is unknown.
    */
-  public async detect(texts: string[]): Promise<string | undefined> {
-    if (texts.length === 0) return undefined;
-    const [response] = await this.service_.detect(
-      texts
-        .slice()
-        .sort((a, b) => b.length - a.length)
-        .at(0)!,
-    );
+  public async detect<T>(
+    props: Omit<JsonTranslator.IProps<T>, "source" | "target">,
+  ): Promise<string | undefined> {
+    const texts: string[] = JsonTranslateExecutor.getTexts(props);
+    return this._Detect_language(texts);
+  }
+
+  /**
+   * @internal
+   */
+  private async _Detect_language(texts: string[]): Promise<string | undefined> {
+    let longest: string | undefined = undefined;
+    for (const str of texts)
+      if (str.length > (longest?.length ?? 0)) longest = str;
+    if (longest === undefined) return undefined;
+    const [response] = await this.service_.detect(longest);
     const res: string | undefined = response.language ?? undefined;
     return res === "und" ? undefined : res;
   }
diff --git a/src/internal/JsonTranslateExecutor.ts b/src/internal/JsonTranslateExecutor.ts
@@ -4,6 +4,9 @@ import { JsonTranslator } from "../JsonTranslator";
  * @internal
  */
 export namespace JsonTranslateExecutor {
+  /* -----------------------------------------------------------
+    PREPARE COLLECTION
+  ----------------------------------------------------------- */
   export interface ICollection {
     output: any;
     raw: string[];
@@ -47,28 +50,32 @@ export namespace JsonTranslateExecutor {
     value: any;
     explore: Omit<JsonTranslator.IExplore, "value">;
   }): void => {
-    if (typeof next.value === "string" && next.value.trim().length !== 0) {
-      if (
+    if (typeof next.value === "string") {
+      if (next.value.trim().length === 0) return;
+      else if (
         next.filter &&
         !next.filter({
           ...next.explore,
           value: next.value,
         })
       )
         return;
-      else if (next.dictionary && next.dictionary[next.value])
+      else if (
+        next.dictionary &&
+        typeof next.dictionary[next.value] === "string"
+      ) {
         next.set(next.dictionary[next.value]);
-      else {
-        const found: Setter<string> | undefined = next.setters.get(next.value);
-        if (found !== undefined) {
-          next.setters.set(next.value, (str) => {
-            next.set(str);
-            found(str);
-          });
-        } else {
-          next.raw.push(next.value);
-          next.setters.set(next.value, next.set);
-        }
+        return;
+      }
+      const found: Setter<string> | undefined = next.setters.get(next.value);
+      if (found !== undefined) {
+        next.setters.set(next.value, (str) => {
+          next.set(str);
+          found(str);
+        });
+      } else {
+        next.raw.push(next.value);
+        next.setters.set(next.value, next.set);
       }
     } else if (Array.isArray(next.value))
       next.value.forEach((elem, i) =>
@@ -99,4 +106,78 @@ export namespace JsonTranslateExecutor {
         }),
       );
   };
+
+  /* -----------------------------------------------------------
+    LIST UP TEXTS
+  ----------------------------------------------------------- */
+  export const getTexts = (
+    props: Omit<JsonTranslator.IProps<any>, "source" | "target">,
+  ): string[] => {
+    const output: Set<string> = new Set();
+    const visited: WeakSet<object> = new WeakSet();
+    visitTexts({
+      filter: props.filter,
+      dictionary: props.dictionary ?? null,
+      output,
+      visited,
+      value: props.input,
+      explore: {
+        object: null,
+        key: null,
+        index: null,
+        accessor: ["$input"],
+      },
+    });
+    return Array.from(output);
+  };
+
+  const visitTexts = (next: {
+    filter: JsonTranslator.IProps<any>["filter"];
+    dictionary: Record<string, string> | null;
+    output: Set<string>;
+    visited: WeakSet<object>;
+    value: any;
+    explore: Omit<JsonTranslator.IExplore, "value">;
+  }): void => {
+    if (typeof next.value === "string") {
+      if (next.value.length === 0) return;
+      else if (
+        next.filter &&
+        !next.filter({
+          ...next.explore,
+          value: next.value,
+        })
+      )
+        return;
+      else if (
+        next.dictionary &&
+        typeof next.dictionary[next.value] === "string"
+      )
+        return;
+      else next.output.add(next.value);
+    } else if (Array.isArray(next.value))
+      next.value.forEach((elem, i) =>
+        visitTexts({
+          ...next,
+          value: elem,
+          explore: {
+            ...next.explore,
+            index: i,
+          },
+        }),
+      );
+    else if (typeof next.value === "object" && next.value !== null)
+      Object.entries(next.value).forEach(([key, value]) =>
+        visitTexts({
+          ...next,
+          explore: {
+            ...next.explore,
+            object: next.value,
+            key,
+            index: null,
+          },
+          value,
+        }),
+      );
+  };
 }
diff --git a/test/features/test_texts.ts b/test/features/test_texts.ts
@@ -0,0 +1,48 @@
+import { TestValidator } from "@nestia/e2e";
+import { JsonTranslateExecutor } from "@samchon/json-translator/lib/internal/JsonTranslateExecutor";
+
+export const test_texts = (): void => {
+  const input = {
+    x: "x",
+    y: "y",
+    z: "z",
+    nested: {
+      alpha: "alpha",
+      beta: "beta",
+      reserved: "reserved",
+    },
+    exceptional: "exceptional",
+    array: ["one", "two", "three"],
+    elements: [
+      {
+        first: "first",
+        second: "second",
+      },
+      {
+        third: "third",
+        fourth: "fourth",
+      },
+    ],
+  };
+  const texts: string[] = JsonTranslateExecutor.getTexts({
+    input,
+    filter: (explore) => explore.key !== "exceptional",
+    dictionary: {
+      reserved: "reserved",
+    },
+  });
+  TestValidator.equals("texts")(texts)([
+    "x",
+    "y",
+    "z",
+    "alpha",
+    "beta",
+    "one",
+    "two",
+    "three",
+    "first",
+    "second",
+    "third",
+    "fourth",
+  ]);
+};
diff --git a/tsconfig.json b/tsconfig.json
@@ -55,7 +55,7 @@
     "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
     // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
     // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
-    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+    "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
     // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
     // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
     "outDir": "./lib",                                   /* Specify an output folder for all emitted files. */

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@samchon/json-translator",`
`3`		`- "version": "1.2.0",`
	`3`	`+ "version": "2.0.0",`
`4`	`4`	`"description": "JSON Translator via Google Translation API with optimization strategies",`
`5`	`5`	`"main": "lib/index.js",`
`6`	`6`	`"types": "lib/index.d.ts",`