generaltranslation 1.2.15 → 1.3.1

package/codes/codes.js

@@ -1,15 +1,43 @@
 // ----- IMPORTS ----- //
 
+// Import modules for mapping ISO 639 codes to language names and vice versa
 const CodeToLanguage = require('./639-1/CodeToLanguage.js');
 const LanguageToCode = require('./639-1/LanguageToCode.js');
 
-// only for languages which have no two-letter code
+// Import modules for mapping ISO 639-3 codes (for languages without two-letter codes)
 const CodeToLanguageTriletter = require('./639-3/CodeToLanguageTriletter.js');
 const LanguageToCodeTriletter = require('./639-3/LanguageToCodeTriletter.js');
 
-// ----- LANGUAGE CODES ----- //
+// Import module for mapping ISO 15924 script codes to script names
+const ScriptToCode = require('./15924/ScriptToCode.js');
+const CodeToScript = require('./15924/CodeToScript.js');
 
-// Returns the name of a language from an ISO 639 code or an array of codes
+// Import module for mapping ISO 3166 region codes to region names
+const RegionToCode = require('./3166/RegionToCode.js');
+const CodeToRegion = require('./3166/CodeToRegion.js');
+
+// Import predefined common regions
+const Predefined = require('./predefined/Predefined.js')
+
+// ----- FORMATTING HELPER FUNCTIONS ----- //
+
+/**
+ * Capitalizes the first letter of a code and converts the rest to lowercase.
+ * @param {string} code - The code to capitalize.
+ * @returns {string} The capitalized code.
+ */
+const _capitalize = (code) => {
+    if (code.length === 0) return code;
+    return code.charAt(0).toUpperCase() + code.slice(1).toLowerCase();
+}
+
+// ----- MAPPING FUNCTIONS ----- //
+
+/**
+ * Returns the name of a language from an ISO 639 code.
+ * @param {string} code - The ISO 639 code.
+ * @returns {string} The language name.
+ */
 const _mapCodeToLanguage = code => {
     code = code?.toLowerCase();
     if (code?.length === 2) {
@@ -17,27 +45,248 @@ const _mapCodeToLanguage = code => {
     } 
     if (code?.length === 3) {
         return CodeToLanguageTriletter[code];
-    } else {
-        return CodeToLanguage[code?.slice(0, 2)] || '';
     }
+    return '';
 }
 
-const _getLanguageName = codes => {
-    return Array.isArray(codes) ? codes.map(_mapCodeToLanguage) : _mapCodeToLanguage(codes);
+/**
+ * Returns an ISO 639 code from a language name.
+ * Preferentially returns two-letter codes.
+ * @param {string} language - The language name.
+ * @returns {string} The ISO 639 code.
+ */
+const _mapLanguageToCode = language => {
+    language = language?.toLowerCase();
+    return LanguageToCode[language] || LanguageToCodeTriletter[language] || '';
 }
 
-// Returns an ISO 639 code from a language name or an array of language names
-// Preferentially returns two-letter codes
-const _mapLanguageToCode = language => {
-    const lowerCaseLanguage = language?.toLowerCase();
-    return LanguageToCode[lowerCaseLanguage] || LanguageToCodeTriletter[lowerCaseLanguage] || '';
+/**
+ * Returns the name of a script from an ISO 15924 code.
+ * @param {string} code - The ISO 15924 code.
+ * @returns {string} The script name.
+ */
+const _mapCodeToScript = code => {
+    code = _capitalize(code);
+    return CodeToScript[code] || '';
+}
+
+/**
+ * Returns an ISO 15924 code from a script name.
+ * @param {string} script - The script name.
+ * @returns {string} The ISO 15924 code.
+ */
+const _mapScriptToCode = script => {
+    script = script?.toLowerCase();
+    return ScriptToCode[script] || '';
+}
+/**
+ * Returns the name of a region from an ISO 3166 code.
+ * @param {string} code - The ISO 3166 code.
+ * @returns {string} The region name.
+ */
+const _mapCodeToRegion = code => {
+    code = code?.toUpperCase();
+    return CodeToRegion[code] || '';
+}
+
+/**
+ * Returns an ISO 3166 code from a region name.
+ * @param {string} region - The region name.
+ * @returns {string} The ISO 3166 code.
+ */
+const _mapRegionToCode = region => {
+    region = region?.toLowerCase();
+    return RegionToCode[region] || '';
+}
+
+// ----- LANGUAGE OBJECTS FROM CODES ----- //
+
+/**
+ * Returns a language object from an array of codes or a single code.
+ * @param {string|string[]} codes - The code or array of codes.
+ * @returns {Object|Object[]} The language object(s).
+ */
+const _getLanguageObject = codes => {
+    return Array.isArray(codes) ? codes.map(_handleGetLanguageObject) : _handleGetLanguageObject(codes);
+}
+
+/**
+ * Helper function to create a language object from a code.
+ * @param {string} code - The language code.
+ * @returns {Object|null} The language object.
+ */
+const _handleGetLanguageObject = code => {
+    if (!code) return null;
+    let languageObject = {
+        language: '',
+        script: '',
+        region: ''
+    };
+    const subtags = code.split('-');
+    // Look for language
+    const languageCode = subtags[0];
+    languageObject.language = _mapCodeToLanguage(languageCode);
+    // Look for script and region
+    if (subtags.length === 3) { // language-script-region
+        languageObject.script = _mapCodeToScript(subtags[1]);
+        languageObject.region = _mapCodeToRegion(subtags[2]);
+    }
+    else if (subtags.length === 2) { // either language-script or language-region
+        if (_isScriptCode(subtags[1])) {
+            languageObject.script = _mapCodeToScript(subtags[1]);
+        } else {
+            languageObject.region = _mapCodeToRegion(subtags[1]);
+        }
+    }
+    return languageObject.language ? languageObject : null;
+}
+
+/**
+ * Helper function to determine if a code is a script code.
+ * @param {string} code - The code to check.
+ * @returns {boolean} True if the code is a script code, false otherwise.
+ */
+const _isScriptCode = (code) => { // if not assume region
+    if (code.length !== 4) return false;
+    return true;
+}
+
+// ----- LANGUAGE NAMES FROM CODES ----- //
+
+/**
+ * Returns the language name(s) from an array of codes or a single code.
+ * @param {string|string[]} codes - The code or array of codes.
+ * @returns {string|string[]} The language name(s).
+ */
+const _getLanguageName = (codes) => {
+    return Array.isArray(codes) ? codes.map(_handleGetLanguageName) : _handleGetLanguageName(codes);
 }
 
+/**
+ * Helper function to get the language name from a code.
+ * @param {string} code - The language code.
+ * @returns {string} The language name.
+ */
+const _handleGetLanguageName = code => {
+    if (!code) return '';
+    if (Predefined[code]) return Predefined[code];
+    const languageObject = _getLanguageObject(code);
+    if (!languageObject) return '';
+    let result = languageObject.language;
+    if (languageObject.script) {
+        result += `, ${languageObject.script}`
+    }
+    if (languageObject.region) {
+        result += `, ${languageObject.region}`
+    }
+    return result;
+}
+
+// ----- LANGUAGE CODES FROM NAMES ----- //
+
+/**
+ * Returns the language code(s) from an array of language names or a single name.
+ * @param {string|string[]} languages - The language name or array of language names.
+ * @returns {string|string[]} The language code(s).
+ */
 const _getLanguageCode = languages => {
-    return Array.isArray(languages) ? languages.map(_mapLanguageToCode) : _mapLanguageToCode(languages);
+    return Array.isArray(languages) ? languages.map(_handleGetLanguageCode) : _handleGetLanguageCode(languages);
+}
+
+/**
+ * Helper function to get the language code from a language name.
+ * @param {string|Object} language - The language name or object.
+ * @returns {string} The language code.
+ */
+const _handleGetLanguageCode = language => {
+    if (typeof language === 'string') return _handleGetLanguageCodeFromString(language);
+    return _handleGetLanguageCodeFromObject(language);
 }
 
+/**
+ * Helper function to get the language code from a language name string.
+ * @param {string} language - The language name.
+ * @returns {string} The language code.
+ */
+const _handleGetLanguageCodeFromString = language => {
+    const subtagStrings = language.split(',').map(string => string.trim());
+    let code = _mapLanguageToCode(subtagStrings[0]);
+    if (code) {
+        if (subtagStrings.length === 3) {
+            code += `-${_mapScriptToCode(subtagStrings[1])}`
+            code += `-${_mapRegionToCode(subtagStrings[2])}`
+        }
+        else if (subtagStrings.length === 2) {
+            let tag = _mapScriptToCode(subtagStrings[1]);
+            if (!tag) tag = _mapRegionToCode(subtagStrings[1]);
+            if (tag) code += `-${tag}`;
+        }
+    }
+    if (!code) {
+        for (const key in Predefined) {
+            if (Predefined[key] === language) {
+                return key;
+            }
+        }
+    }
+    return code;
+}
+
+/**
+ * Helper function to get the language code from a language object.
+ * @param {Object} languageObject - The language object.
+ * @returns {string} The language code.
+ */
+const _handleGetLanguageCodeFromObject = languageObject => {
+    if (!languageObject?.language) return '';
+    let code = languageObject.language.toLowerCase();
+    if (languageObject.script) {
+        code += `-${_capitalize(languageObject.script)}`
+    }
+    if (languageObject.region) {
+        code += `-${languageObject.region.toUpperCase()}`
+    }
+    return code;
+}
+
+// ----- COMPARISON FUNCTION ----- //
+
+/**
+ * Determines if all provided language codes represent the same language.
+ * Can take either an array of codes or a plain set of parameters.
+ * @param {...(string|string[])} codes - The language codes, either as separate arguments or as an array.
+ * @returns {boolean} True if all codes represent the same language, false otherwise.
+ */
+const _isSameLanguage = (...codes) => {
+    // Flatten the array in case the codes are provided as an array
+    if (codes.length === 1 && Array.isArray(codes[0])) {
+        codes = codes[0];
+    }
+
+    if (codes.length < 2) return false;
+
+    let language = null;
+    for (let i = 0; i < codes.length; i++) {
+        if (typeof codes[i] !== 'string') return false;
+
+        const languageCode = codes[i].split('-')[0];
+        const currentLanguage = _mapCodeToLanguage(languageCode);
+
+        if (language === null) {
+            language = currentLanguage;
+        } else if (language !== currentLanguage) {
+            return false;
+        }
+    }
+    return true;
+}
+
+// ----- EXPORTS ----- //
+
+// Export functions for external use
 module.exports = {
+    _getLanguageObject,
     _getLanguageName,
-    _getLanguageCode
+    _getLanguageCode,
+    _isSameLanguage
 };

package/codes/predefined/Predefined.js

@@ -0,0 +1,29 @@
+const Predefined = {
+    "en-US": "English",
+    "en-GB": "British English",
+    "en-CA": "Canadian English",
+    "en-AU": "Australian English",
+    "es-ES": "Spanish",
+    "es-MX": "Mexican Spanish",
+    "es-AR": "Argentinian Spanish",
+    "es-CO": "Colombian Spanish",
+    "fr-FR": "French",
+    "fr-CA": "Canadian French",
+    "fr-BE": "Belgian French",
+    "fr-CH": "Swiss French",
+    "zh-CN": "Mandarin Chinese",
+    "zh-TW": "Traditional Chinese",
+    "zh-HK": "Hong Kong Chinese",
+    "pt-PT": "Portuguese",
+    "pt-BR": "Brazilian Portuguese",
+    "de-DE": "German",
+    "de-AT": "Austrian German",
+    "de-CH": "Swiss German",
+    "ar-SA": "Saudi Arabic",
+    "ar-EG": "Egyptian Arabic",
+    "ar-AE": "Emirati Arabic",
+    "ar-MA": "Moroccan Arabic",
+    "nl-BE": "Belgian Dutch",
+    "it-CH": "Swiss Italian"
+};
+module.exports = Predefined;

package/index.js

@@ -3,14 +3,13 @@
 
 // ----- IMPORTS ----- //
 
-const { _getLanguageCode, _getLanguageName } = require('./codes/codes.js');
-const { _translate, _translateMany } = require('./translate/translate.js');
-const _translateHTML = require('./translate/html.js');
+const { _getLanguageObject, _getLanguageCode, _getLanguageName, _isSameLanguage } = require('./codes/codes.js');
+const _translateReactChildren = require('./translation/react/translateReactChildren.js');
 
 // TO DO
+// - Translation API
 // - Times/dates?
 // - Currency conversion?
-// - Regions (e.g. en-GB)
 
 // ----- CORE CLASS ----- // 
 
@@ -29,7 +28,7 @@ class GT {
         apiKey = '', 
         defaultLanguage = 'en',
         projectID = '',
-        baseURL = 'https://translate.gtx.dev'
+        baseURL = 'https://prod.gtx.dev'
     } = {}) {
         this.apiKey = apiKey || getDefaultFromEnv('GT_API_KEY');
         this.projectID = projectID || getDefaultFromEnv('GT_PROJECT_ID');
@@ -37,31 +36,19 @@ class GT {
         this.baseURL = baseURL;
     }
 
-    // Site I18N
-    async translateHTML({ page, userLanguage, defaultLanguage, content, ...metadata }) {
-        return await _translateHTML({
-            page: page,
-            userLanguage: userLanguage,
-            defaultLanguage: defaultLanguage,
-            content: content,
-            config: this,
-            ...metadata
-        });
-    }
-
-    // String translation
-    async translate(content, language, ...options) {
-        return await _translate({
-            content: content, language: language, config: this, ...options,
-        });
-    }
-
-    // String translation, of an array of strings
-    // requestArray looks like { content: '', language: '' }
-    async translateMany(contentArray, language, ...options) {
-        return await _translateMany({
-            contentArray, language, config: this, ...options
-        });
+    /**
+    * Asynchronously translates the given React content to the specified target language.
+    *
+    * 
+    * @param {Object} params - The parameters for the translation.
+    * @param {Object|Array} params.content - The React children content to be translated.
+    * @param {string} params.targetLanguage - The target language for translation.
+    * @param {...any} metadata - Additional metadata that might be needed for the translation process.
+    * 
+    * @returns {Promise<Object|Array>} - A promise that resolves to the translated React children content.
+    */
+    async translateReactChildren({ content, targetLanguage, ...metadata }) {
+        return await _translateReactChildren(content, targetLanguage, metadata, this)
     }
 
 }
@@ -72,5 +59,7 @@ class GT {
 module.exports = GT;
 
 // Export the functions 
+module.exports.getLanguageObject = _getLanguageObject;
 module.exports.getLanguageCode = _getLanguageCode;
-module.exports.getLanguageName = _getLanguageName;
+module.exports.getLanguageName = _getLanguageName;
+module.exports.isSameLanguage= _isSameLanguage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generaltranslation",
-  "version": "1.2.15",
+  "version": "1.3.1",
   "description": "A language toolkit for AI developers",
   "main": "index.js",
   "scripts": {

package/translation/react/translateReactChildren.js

@@ -0,0 +1,25 @@
+async function _translateReactChildren(content, targetLanguage, this, ...metadata) {
+    try {
+        const response = await fetch(`${this.baseURL}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'gtx-api-key': this.apiKey,
+            },
+            body: JSON.stringify({
+                content: content,
+                targetLanguage: targetLanguage,
+                metadata: { ...metadata }
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`${response.status}: ${await response.text()}`)
+        }
+        return await response.json();
+    } catch (error) {
+        console.error(error)
+        return null;
+    }
+}
+
+module.exports = _translateReactChildren;

package/translate/html.js

@@ -1,50 +0,0 @@
-const _translateHTML = async ({
-    page,
-    userLanguage,
-    defaultLanguage,
-    content,
-    config,
-    ...metadata
-}) => {
-
-    const apiKey = config?.apiKey;
-    if (!apiKey) {
-        throw new Error('Missing API Key!')
-    };
-
-    const projectID = config?.projectID;
-    if (!projectID) {
-        throw new Error('Missing Project ID!')
-    };
-
-    try {
-        const response = await fetch('https://html.gtx.dev', {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'gtx-api-key': apiKey,
-            },
-            body: JSON.stringify({
-                projectID: projectID,
-                page: page,
-                userLanguage: userLanguage,
-                defaultLanguage: defaultLanguage,
-                content: content,
-                metadata: { ...metadata }
-            })
-        });
-        if (!response.ok) {
-            const result = await response.text();
-            throw new Error(`${result || response.status}`);
-        } else {
-            const result = await response.json();
-            return result;
-        }
-    } catch (error) {
-        console.error(error);
-        return {};
-    }
-    
-}
-
-module.exports = _translateHTML;

package/translate/translate.js

@@ -1,191 +0,0 @@
-// ----- TRANSLATION ----- //
-
-// Decides whether an item object should be translated
-const _shouldTranslate = item => typeof item?.translate === 'boolean' ? item.translate : true;
-
-// Pre-processes content to send to the API
-// Separates out text that shouldn't be translated.
-const _processContent = ({ content }) => {
-    const processed = [];
-    const untranslated = [];
-    if (Array.isArray(content)) {
-        for (const item of content) {
-            if (typeof item === 'string') {
-                processed.push({
-                    text: item
-                });
-            } else if (_shouldTranslate(item)) {
-                processed.push(item);
-            } else {
-                processed.push({text: '', translate: false});
-                untranslated.push(item);
-            }
-        }
-    } else {
-        if (typeof content === 'string') {
-            processed.push({
-                text: content
-            });
-        } else if (_shouldTranslate(content)) {
-            processed.push(content);
-        } else {
-            processed.push({text: '', translate: false});
-            untranslated.push(content);
-        }
-    } 
-    return {
-        processed: processed,
-        untranslated: untranslated.length > 0 ? untranslated : null
-    }
-}
-
-// Build content string from array or single item
-const _constructContent = ({ content, untranslated = null}) => {
-    if (Array.isArray(content)) {
-        let final = '';
-        for (const item of content) {
-            if (typeof item === 'string') final += item;
-            else if (_shouldTranslate(item)) final += item?.text || '';
-            else {
-                if (untranslated?.length > 0) {
-                    final += untranslated?.shift().text || '';
-                } else {
-                    final += item?.text || '';
-                }
-            }
-        }
-        return final;
-    } else if (typeof content === 'string') {
-        return content;
-    } else {
-        return content?.text || '';
-    }
-}
-
-// Get a translation via General Translation API
-// Returns string
-const _translate = async ({
-    content, language, config, ...options
-}) => {
-    
-    const apiKey = config?.apiKey;
-    if (!apiKey) {
-        throw new Error('Missing API Key!')
-    };
-
-    const defaultLanguage = config?.defaultLanguage;
-    if (language === defaultLanguage) {
-        return _constructContent({ content: content });
-    };
-
-    const { processed, untranslated } = _processContent({ content });
-    
-    try {
-        const response = await fetch(`${config?.baseURL}`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'gtx-api-key': apiKey,
-            },
-            body: JSON.stringify({
-                content: processed,
-                targetLanguage: language,
-                defaultLanguage: defaultLanguage,
-                options: { ...options }
-            })
-        })
-        if (!response.ok) {
-            const result = await response.text();
-            throw new Error(`${result || response.status}`);
-        } else {
-            const result = await response.json();
-            return _constructContent({content: result, untranslated: untranslated });
-        }
-    } catch (error) {
-        console.error(error)
-        return _constructContent({ content: content })
-    }
-
-}
-
-const constructAll = (contentArray) => {
-    const returnArray = [];
-    for (const item of contentArray) {
-        returnArray.push(_constructContent({ content: item }))
-    }
-    return returnArray;
-}
-
-// Get a translation of multiple strings via General Translation API
-// Returns array of strings
-const _translateMany = async ({
-    contentArray, language, config, ...options
-}) => {
-
-    const apiKey = config?.apiKey;
-    if (!apiKey) {
-        throw new Error('Missing API Key!')
-    };
-
-    const defaultLanguage = config?.defaultLanguage;
-    if (language === defaultLanguage) {
-        return constructAll(contentArray);
-    };
-
-    /*
-        // [{content, language,...options}], config 
-        ->
-        [{
-            content: processed,
-            targetLanguage: language,
-            defaultLanguage: defaultLanguage,
-            options: { ...options }
-        }]
-    */
-
-    const processedArray = [];
-    const untranslatedArray = [];
-
-    for (const item of contentArray) {
-        const { processed, untranslated } = _processContent({ content: item });
-        processedArray.push(processed);
-        untranslatedArray.push(untranslated);
-    }
-
-    try {
-        const response = await fetch(`${config?.baseURL}/many`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'gtx-api-key': apiKey,
-            },
-            body: JSON.stringify({
-                contentArray: processedArray,
-                targetLanguage: language,
-                defaultLanguage: defaultLanguage,
-                options: { ...options }
-            })
-        })
-        if (!response.ok) {
-            
-            const result = await response.text();
-            throw new Error(`${result || response.status}`);
-        } else {
-            const result = await response.json();
-            if (!Array.isArray(result)) {
-                throw new Error(`${result || response.status}`);
-            }
-            const returnArray = [];
-            for (const [index, item] of result.entries()) {
-                returnArray.push(_constructContent({content: item, untranslated: untranslatedArray[index] }));
-            }
-            return returnArray;
-        }
-    } catch (error) {
-        console.error(error)
-        return constructAll(contentArray);
-    }
-
-}
-
-module.exports = { _translate, _translateMany };