multiapi-language-translator

Multi-API language translation library. Supported APIs: LibreTranslate™, DeepL™.

Requirements:

• access to a server hosting one of the supported language translation service APIs
  • LibreTranslate
    • API key
    • API URL
  • DeepL
    • API key

Supported Languages

• the list of supported input and output languages depends upon the chosen API
  • LibreTranslate
    • there is no guarantee for consistency, either between server instances or over time
    • to obtain a real-time list of supported languages from a specific server instance, directly query its <API URL>/languages API endpoint
  • DeepL

Installation

npm install @warren-bank/multiapi-language-translator

Library API (common usage)

• set_api(api_service, api_key, api_url)

  • input parameters:
    • api_service
      • type: string
      • name of the chosen language translation service
      • value is restricted to the enum: ["libre", "deepl"]
    • api_key
      • type: string | null
      • unique to the chosen language translation service
      • required by service: "deepl"
    • api_url
      • type: string | null
      • unique to the chosen language translation service
  • return value:
    • undefined

• translate(input_language_code, output_language_code, input_strings_array, optimize_duplicates)

  • input parameters:
    • input_language_code
      • type: string
      • value is restricted to the list of supported languages
    • output_language_code
      • type: string
      • value is restricted to the list of supported languages
    • input_strings_array
      • type: array of strings
      • each string will be translated from input_language_code to output_language_code
      • the order of strings is preserved in the resolved return value
    • optimize_duplicates
      • type: boolean
      • default: false
      • when true:
        • duplicate strings are removed from the request to the translation service
        • translations for duplicate input strings are positionally inserted into the response from the translation service
          • the resolved value is identical to that of a non-optimized request
          • the benefit is that the translation service performs less work
  • return value:
    • Promise that resolves to an array of translated strings in the same order as the input array
  • prerequisites:
    • set_api()
  • notes:
    • init() is called internally

Library API (advanced usage)

• init()

  • input parameters:
    • none
  • return value:
    • Promise that resolves when library is ready to use
  • prerequisites:
    • set_api()

• get_input_languages()

  • input parameters:
    • none
  • return value:
    • array of strings that identifies all valid input language codes
  • prerequisites:
    • set_api() and init()

• get_output_languages(input_language_code)

  • input parameters:
    • input_language_code
      • type: string
      • value is restricted to the list of supported languages
  • return value:
    • array of strings that identifies all valid output language codes for the specified input language code
  • prerequisites:
    • set_api() and init()

• is_valid_input_language(input_language_code)

  • input parameters:
    • input_language_code
      • type: string
  • return value:
    • type: boolean
    • value indicates whether the specified input language code is in the list of supported languages
  • prerequisites:
    • set_api() and init()

• is_valid_output_language(input_language_code, output_language_code)

  • input parameters:
    • input_language_code
      • type: string
      • value is restricted to the list of supported languages
    • output_language_code
      • type: string
  • return value:
    • type: boolean
    • value indicates whether the specified output language code is in the list of supported languages for the specified input language code
  • prerequisites:
    • set_api() and init()

Library API (very advanced usage)

• class: DuplicatesStore
  • constructor: DuplicatesStore(input_strings_array)
    • input parameters:
      • input_strings_array
        • type: array of strings
        • array may contain duplicate values
  • dehydrate_input_strings_array()
    • input parameters:
      • none
    • return value:
      • type: array of strings
      • array does not contain any duplicates
  • rehydrate_translated_strings_array(translated_strings_array)
    • input parameters:
      • translated_strings_array
        • type: array of strings
        • array does not contain any duplicates
    • return value:
      • type: array of strings
      • array may contain duplicate values

Library Examples

const {set_api, translate} = require('@warren-bank/multiapi-language-translator')

const deepl_example = async () => {
  const api_service          = 'deepl'
  const api_key              = 'MY_DEEPL_TRANSLATE_API_KEY'
  const api_url              = null
  const input_language_code  = 'en'
  const output_language_code = 'de'
  const input_strings_array  = ['Hello world', 'Welcome to the jungle', 'Hello world', 'Welcome to the jungle']
  const optimize_duplicates  = true

  set_api(api_service, api_key, api_url)

  const translated_strings_array = await translate(input_language_code, output_language_code, input_strings_array, optimize_duplicates)

  console.log(
    `"${api_service}" translation from "${input_language_code}" to "${output_language_code}"`,
    '=',
    JSON.stringify(translated_strings_array, null, 2)
  )
}

Legal:

• copyright: Warren Bank
• license: GPL-2.0