generaltranslation 2.0.65 → 2.0.67

package/dist/codes/determineLanguage.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/codes/determineLanguage.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = _determineLanguage;
+var codes_1 = require("./codes");
+/**
+ * Given a list of language and a list of approved language, sorted in preference order
+ * Determines which language of the given languages is the best match in the approvedLanguages, prioritizing exact matches and falling back to dialects of the same language
+* @internal
+*/
+function _determineLanguage(languages, approvedLanguages) {
+    if (typeof languages === 'string')
+        languages = [languages];
+    if (!approvedLanguages)
+        return languages[0];
+    var _loop_1 = function (language) {
+        var exactMatch = approvedLanguages.find(function (approvedLanguage) { return approvedLanguage === language; });
+        if (exactMatch)
+            return { value: exactMatch };
+        var sameLanguage = approvedLanguages.find(function (approvedLanguage) { return (0, codes_1._isSameLanguage)(approvedLanguage, language); });
+        if (sameLanguage)
+            return { value: sameLanguage };
+    };
+    for (var _i = 0, languages_1 = languages; _i < languages_1.length; _i++) {
+        var language = languages_1[_i];
+        var state_1 = _loop_1(language);
+        if (typeof state_1 === "object")
+            return state_1.value;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -32,14 +32,14 @@ declare class GT {
      * If `metadata.save` is provided, the translation is cached for use in a public project.
      *
      * @param {Content} content - The string or array of strings/variables to be translated.
-     * @param {string} targetLanguage - The target language code (e.g., 'en', 'fr') for the translation.
+     * @param {string} language - The target language code (e.g., 'en', 'fr') for the translation.
      * @param {{ context?: string, save?: boolean, [key: string]: any }} [metadata] - Additional metadata for the translation request.
      * @param {string} [metadata.context] - Contextual information to assist with the translation.
      * @param {boolean} [metadata.save] - Whether to cache the translation for use in a public project.
      *
      * @returns {Promise<ContentTranslationResult>} A promise that resolves to the translated content, or an error if the translation fails.
      */
-    translate(content: Content, targetLanguage: string, metadata?: {
+    translate(content: Content, language: string, metadata?: {
         context?: string;
         save?: boolean;
         [key: string]: any;
@@ -52,12 +52,12 @@ declare class GT {
     *
     * @param {Object} params - The parameters for the translation.
     * @param {ReactChildrenAsObject} params.children - The React children content to be translated.
-    * @param {string} params.targetLanguage - The target language for the translation.
+    * @param {string} params.language - The target language for the translation.
     * @param {Object} params.metadata - Additional metadata for the translation process.
     *
     * @returns {Promise<ReactTranslationResult>} - A promise that resolves to the translated content.
     */
-    translateReact(children: ReactChildrenAsObject, targetLanguage: string, metadata?: {
+    translateReact(children: ReactChildrenAsObject, language: string, metadata?: {
         context?: string;
         save?: boolean;
         [key: string]: any;
@@ -70,7 +70,7 @@ declare class GT {
     translateBundle(requests: Request[]): Promise<Array<ReactTranslationResult | ContentTranslationResult>>;
     /**
     * Pushes updates to a remotely cached translation dictionary.
-    * @param {Update[]} updates - Array of updates with optional targetLanguage.
+    * @param {Update[]} updates - Array of updates.
     * @param {string[]} [languages] - Array of languages to be updated.
     * @param {string} [projectID=this.projectID] - The ID of the project. Defaults to the instance's projectID.
     * @param {boolean} [replace=false] - Whether to replace the existing dictionary. Defaults to false.
@@ -200,3 +200,22 @@ export declare function splitStringToContent(string: string): Content;
 export declare function renderContentToString<V extends Record<string, any>>(content: Content, languages?: string | string[], variables?: V, variableOptions?: {
     [key in keyof V]?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions;
 }): string;
+/**
+ * Determines the best matching language from the approved languages list based on a provided
+ * list of preferred languages. The function prioritizes exact matches, but will also consider
+ * dialects of the same language if an exact match is not available.
+ *
+ * It also respects the order of preference in both the provided languages list and the
+ * approved languages list. A dialect match of a higher-preference language is considered better
+ * than an exact match of a lower-preference language.
+ *
+ * For example, if the `languages` list is ['en', 'fr'], and the `approvedLanguages` list is
+ * ['fr', 'en-GB'], it will prefer 'en-GB' over 'fr', even though 'fr' has an exact
+ * dialect match, because 'en' appears earlier in the `languages` list.
+ *
+ * @param {string | string[]} languages - A single language or an array of languages sorted in preference order.
+ * @param {string[]} approvedLanguages - An array of approved languages, also sorted by preference.
+ *
+ * @returns {string | undefined} - The best matching language from the approvedLanguages list, or undefined if no match is found.
+ */
+export declare function determineLanguage(languages: string | string[], approvedLanguages: string[]): string | undefined;

package/dist/index.js

@@ -62,6 +62,7 @@ exports.formatDateTime = formatDateTime;
 exports.formatCurrency = formatCurrency;
 exports.splitStringToContent = splitStringToContent;
 exports.renderContentToString = renderContentToString;
+exports.determineLanguage = determineLanguage;
 // ----- IMPORTS ----- //
 var codes_1 = require("./codes/codes");
 var getLanguageDirection_1 = __importDefault(require("./codes/getLanguageDirection"));
@@ -71,6 +72,7 @@ var _translateReact_1 = __importDefault(require("./translation/react/_translateR
 var _updateProjectDictionary_1 = __importDefault(require("./translation/dictionaries/_updateProjectDictionary"));
 var _format_1 = require("./formatting/_format");
 var _string_content_1 = require("./formatting/_string_content");
+var determineLanguage_1 = __importDefault(require("./codes/determineLanguage"));
 // ----- CORE CLASS ----- // 
 var getDefaultFromEnv = function (VARIABLE) {
     if (typeof process !== 'undefined' && process.env) {
@@ -103,18 +105,18 @@ var GT = /** @class */ (function () {
      * If `metadata.save` is provided, the translation is cached for use in a public project.
      *
      * @param {Content} content - The string or array of strings/variables to be translated.
-     * @param {string} targetLanguage - The target language code (e.g., 'en', 'fr') for the translation.
+     * @param {string} language - The target language code (e.g., 'en', 'fr') for the translation.
      * @param {{ context?: string, save?: boolean, [key: string]: any }} [metadata] - Additional metadata for the translation request.
      * @param {string} [metadata.context] - Contextual information to assist with the translation.
      * @param {boolean} [metadata.save] - Whether to cache the translation for use in a public project.
      *
      * @returns {Promise<ContentTranslationResult>} A promise that resolves to the translated content, or an error if the translation fails.
      */
-    GT.prototype.translate = function (content, targetLanguage, metadata) {
+    GT.prototype.translate = function (content, language, metadata) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0: return [4 /*yield*/, (0, _translate_1.default)(this, content, targetLanguage, __assign({ projectID: this.projectID, defaultLanguage: this.defaultLanguage }, metadata))];
+                    case 0: return [4 /*yield*/, (0, _translate_1.default)(this, content, language, __assign({ projectID: this.projectID, defaultLanguage: this.defaultLanguage }, metadata))];
                     case 1: return [2 /*return*/, _a.sent()];
                 }
             });
@@ -125,16 +127,16 @@ var GT = /** @class */ (function () {
     *
     * @param {Object} params - The parameters for the translation.
     * @param {ReactChildrenAsObject} params.children - The React children content to be translated.
-    * @param {string} params.targetLanguage - The target language for the translation.
+    * @param {string} params.language - The target language for the translation.
     * @param {Object} params.metadata - Additional metadata for the translation process.
     *
     * @returns {Promise<ReactTranslationResult>} - A promise that resolves to the translated content.
     */
-    GT.prototype.translateReact = function (children, targetLanguage, metadata) {
+    GT.prototype.translateReact = function (children, language, metadata) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0: return [4 /*yield*/, (0, _translateReact_1.default)(this, children, targetLanguage, __assign({ projectID: this.projectID, defaultLanguage: this.defaultLanguage }, metadata))];
+                    case 0: return [4 /*yield*/, (0, _translateReact_1.default)(this, children, language, __assign({ projectID: this.projectID, defaultLanguage: this.defaultLanguage }, metadata))];
                     case 1: return [2 /*return*/, _a.sent()];
                 }
             });
@@ -154,7 +156,7 @@ var GT = /** @class */ (function () {
     };
     /**
     * Pushes updates to a remotely cached translation dictionary.
-    * @param {Update[]} updates - Array of updates with optional targetLanguage.
+    * @param {Update[]} updates - Array of updates.
     * @param {string[]} [languages] - Array of languages to be updated.
     * @param {string} [projectID=this.projectID] - The ID of the project. Defaults to the instance's projectID.
     * @param {boolean} [replace=false] - Whether to replace the existing dictionary. Defaults to false.
@@ -278,3 +280,24 @@ function splitStringToContent(string) {
 function renderContentToString(content, languages, variables, variableOptions) {
     return (0, _string_content_1._renderContentToString)(content, languages, variables, variableOptions);
 }
+/**
+ * Determines the best matching language from the approved languages list based on a provided
+ * list of preferred languages. The function prioritizes exact matches, but will also consider
+ * dialects of the same language if an exact match is not available.
+ *
+ * It also respects the order of preference in both the provided languages list and the
+ * approved languages list. A dialect match of a higher-preference language is considered better
+ * than an exact match of a lower-preference language.
+ *
+ * For example, if the `languages` list is ['en', 'fr'], and the `approvedLanguages` list is
+ * ['fr', 'en-GB'], it will prefer 'en-GB' over 'fr', even though 'fr' has an exact
+ * dialect match, because 'en' appears earlier in the `languages` list.
+ *
+ * @param {string | string[]} languages - A single language or an array of languages sorted in preference order.
+ * @param {string[]} approvedLanguages - An array of approved languages, also sorted by preference.
+ *
+ * @returns {string | undefined} - The best matching language from the approvedLanguages list, or undefined if no match is found.
+ */
+function determineLanguage(languages, approvedLanguages) {
+    return (0, determineLanguage_1.default)(languages, approvedLanguages);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generaltranslation",
-  "version": "2.0.65",
+  "version": "2.0.67",
   "description": "A language toolkit for AI developers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",