adapt-authoring-lang 1.1.0 → 1.2.0

package/bin/check.js

@@ -74,7 +74,7 @@ async function getUsedStrings (translatedStrings) {
       usedStrings[key].add(f.replace(root, '').split('/')[1]) // only add module name for errors
     })
   }))
-  const sourceFiles = await glob('adapt-authoring-*/**/*.@(js|hbs)', { cwd: root, absolute: true, ignore: '**/node_modules/**' })
+  const sourceFiles = await glob('adapt-authoring-*/**/*.@(js|hbs)', { cwd: root, absolute: true, ignore: ['**/node_modules/**', '**/*.spec.js', '**/tests/**'] })
 
   await Promise.all(sourceFiles.map(async f => {
     const contents = (await fs.readFile(f)).toString()

package/index.js

@@ -3,3 +3,4 @@
  * @namespace lang
  */
 export { default } from './lib/LangModule.js'
+export { storeStrings, translate, translateError } from './lib/utils.js'

package/lib/LangModule.js

@@ -2,6 +2,7 @@ import { AbstractModule } from 'adapt-authoring-core'
 import fs from 'fs/promises'
 import { glob } from 'glob'
 import path from 'path'
+import { storeStrings, translate, translateError } from './utils.js'
 
 /**
  * Module to handle localisation of language strings
@@ -51,18 +52,18 @@ class LangModule extends AbstractModule {
     await Promise.all(files.map(async f => {
       try {
         const contents = JSON.parse((await fs.readFile(f)).toString())
-        Object.entries(contents).forEach(([k, v]) => this.storeStrings(`${path.basename(f).replace('.json', '')}.${k}`, v))
+        Object.entries(contents).forEach(([k, v]) => storeStrings(this.phrases, `${path.basename(f).replace('.json', '')}.${k}`, v))
       } catch (e) {
         this.log('error', e.message, f)
       }
     }))
   }
 
+  /**
+   * @deprecated Use storeStrings() from 'adapt-authoring-lang' instead
+   */
   storeStrings (key, value) {
-    const i = key.indexOf('.')
-    const lang = key.slice(0, i)
-    if (!this.phrases[lang]) this.phrases[lang] = {}
-    this.phrases[lang][key.slice(i + 1)] = value
+    storeStrings(this.phrases, key, value)
   }
 
   /**
@@ -146,34 +147,7 @@ class LangModule extends AbstractModule {
    * @return {String}
    */
   translate (lang, key, data) {
-    if (typeof lang !== 'string') {
-      lang = this.getConfig('defaultLang')
-    }
-    if (key.constructor.name.endsWith('Error')) {
-      return this.translateError(lang, key)
-    }
-    const s = this.phrases[lang]?.[key]
-    if (!s) {
-      this.log('warn', `missing key '${lang}.${key}'`)
-      return key
-    }
-    if (!data) {
-      return s
-    }
-    return Object.entries(data).reduce((s, [k, v]) => {
-      // map any errors specified in data
-      v = Array.isArray(v) ? v.map(v2 => this.translateError(lang, v2)) : this.translateError(lang, v)
-      s = s.replaceAll(`\${${k}}`, v)
-      // handle special-case array replacements
-      if (Array.isArray(v)) {
-        const matches = [...s.matchAll(new RegExp(String.raw`\$map{${k}:(.+)}`, 'g'))]
-        matches.forEach(([replace, data]) => {
-          const [attrs, delim] = data.split(':')
-          s = s.replace(replace, v.map(val => attrs.split(',').map(a => Object.prototype.hasOwnProperty.call(val, a) ? val[a] : a)).join(delim))
-        })
-      }
-      return s
-    }, s)
+    return translate(this.phrases, this.getConfig('defaultLang'), msg => this.log('warn', msg), lang, key, data)
   }
 
   /**
@@ -183,7 +157,7 @@ class LangModule extends AbstractModule {
    * @returns The translated error (if passed error is not an instance of AdaptError, the original value will be returned)
    */
   translateError (lang, error) {
-    return error?.constructor.name.endsWith('Error') ? this.translate(lang, `error.${error.code}`, error.data ?? error) : error
+    return translateError(this.phrases, this.getConfig('defaultLang'), msg => this.log('warn', msg), lang, error)
   }
 }
 

package/lib/utils/storeStrings.js

@@ -0,0 +1,13 @@
+/**
+ * Parses a dotted language key and stores the value in the phrases dictionary
+ * @param {Object} phrases The phrases dictionary to store into
+ * @param {String} key Key in the format 'lang.namespace.key'
+ * @param {String} value The string value to store
+ * @memberof lang
+ */
+export function storeStrings (phrases, key, value) {
+  const i = key.indexOf('.')
+  const lang = key.slice(0, i)
+  if (!phrases[lang]) phrases[lang] = {}
+  phrases[lang][key.slice(i + 1)] = value
+}

package/lib/utils/translate.js

@@ -0,0 +1,43 @@
+import { translateError } from './translateError.js'
+
+/**
+ * Returns translated language string
+ * @param {Object} phrases The phrases dictionary
+ * @param {String} defaultLang Default language to use when lang is not a string
+ * @param {Function} logWarn Logging function for missing keys (receives message string)
+ * @param {String} lang The target language (if undefined, the default language will be used)
+ * @param {String|AdaptError} key The unique string key (if an AdaptError is passed, the error data will be used for the data param)
+ * @param {Object} data Dynamic data to be inserted into translated string
+ * @return {String}
+ * @memberof lang
+ */
+export function translate (phrases, defaultLang, logWarn, lang, key, data) {
+  if (typeof lang !== 'string') {
+    lang = defaultLang
+  }
+  if (key.constructor.name.endsWith('Error')) {
+    return translateError(phrases, defaultLang, logWarn, lang, key)
+  }
+  const s = phrases[lang]?.[key]
+  if (!s) {
+    logWarn(`missing key '${lang}.${key}'`)
+    return key
+  }
+  if (!data) {
+    return s
+  }
+  return Object.entries(data).reduce((s, [k, v]) => {
+    // map any errors specified in data
+    v = Array.isArray(v) ? v.map(v2 => translateError(phrases, defaultLang, logWarn, lang, v2)) : translateError(phrases, defaultLang, logWarn, lang, v)
+    s = s.replaceAll(`\${${k}}`, v)
+    // handle special-case array replacements
+    if (Array.isArray(v)) {
+      const matches = [...s.matchAll(new RegExp(String.raw`\$map{${k}:(.+)}`, 'g'))]
+      matches.forEach(([replace, data]) => {
+        const [attrs, delim] = data.split(':')
+        s = s.replace(replace, v.map(val => attrs.split(',').map(a => Object.prototype.hasOwnProperty.call(val, a) ? val[a] : a)).join(delim))
+      })
+    }
+    return s
+  }, s)
+}

package/lib/utils/translateError.js

@@ -0,0 +1,17 @@
+import { translate } from './translate.js'
+
+/**
+ * Translates an AdaptError
+ * @param {Object} phrases The phrases dictionary
+ * @param {String} defaultLang Default language to use when lang is not a string
+ * @param {Function} logWarn Logging function for missing keys (receives message string)
+ * @param {String} lang The target language
+ * @param {AdaptError} error Error to translate
+ * @returns The translated error (if passed error is not an instance of AdaptError, the original value will be returned)
+ * @memberof lang
+ */
+export function translateError (phrases, defaultLang, logWarn, lang, error) {
+  return error?.constructor.name.endsWith('Error')
+    ? translate(phrases, defaultLang, logWarn, lang, `error.${error.code}`, error.data ?? error)
+    : error
+}

package/lib/utils.js

@@ -0,0 +1,3 @@
+export { storeStrings } from './utils/storeStrings.js'
+export { translate } from './utils/translate.js'
+export { translateError } from './utils/translateError.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-lang",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Localisation for the Adapt authoring tool",
   "homepage": "https://github.com/taylortom/adapt-authoring-lang",
   "license": "GPL-3.0",
@@ -14,7 +14,7 @@
   },
   "repository": "github:adapt-security/adapt-authoring-lang",
   "dependencies": {
-    "adapt-authoring-core": "^1.7.0",
+    "adapt-authoring-core": "^2.0.0",
     "glob": "^13.0.0"
   },
   "peerDependencies": {

package/tests/utils-storeStrings.spec.js

@@ -0,0 +1,49 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { storeStrings } from '../lib/utils/storeStrings.js'
+
+describe('storeStrings()', () => {
+  let phrases
+
+  beforeEach(() => {
+    phrases = {}
+  })
+
+  it('should store string with language prefix', () => {
+    storeStrings(phrases, 'en.app.test', 'Test Value')
+    assert.equal(phrases.en['app.test'], 'Test Value')
+  })
+
+  it('should create language key if not exists', () => {
+    storeStrings(phrases, 'fr.app.hello', 'Bonjour')
+    assert.ok(phrases.fr)
+    assert.equal(phrases.fr['app.hello'], 'Bonjour')
+  })
+
+  it('should store multiple strings for same language', () => {
+    storeStrings(phrases, 'en.app.test1', 'Value 1')
+    storeStrings(phrases, 'en.app.test2', 'Value 2')
+    assert.equal(phrases.en['app.test1'], 'Value 1')
+    assert.equal(phrases.en['app.test2'], 'Value 2')
+  })
+
+  it('should handle nested keys with dots', () => {
+    storeStrings(phrases, 'en.app.nested.key', 'Nested Value')
+    assert.equal(phrases.en['app.nested.key'], 'Nested Value')
+  })
+
+  it('should overwrite existing key', () => {
+    storeStrings(phrases, 'en.app.test', 'Original')
+    storeStrings(phrases, 'en.app.test', 'Updated')
+    assert.equal(phrases.en['app.test'], 'Updated')
+  })
+
+  it('should store strings for multiple languages', () => {
+    storeStrings(phrases, 'en.app.hello', 'Hello')
+    storeStrings(phrases, 'fr.app.hello', 'Bonjour')
+    storeStrings(phrases, 'de.app.hello', 'Hallo')
+    assert.equal(phrases.en['app.hello'], 'Hello')
+    assert.equal(phrases.fr['app.hello'], 'Bonjour')
+    assert.equal(phrases.de['app.hello'], 'Hallo')
+  })
+})

package/tests/utils-translate.spec.js

@@ -0,0 +1,114 @@
+/* eslint-disable no-template-curly-in-string */
+import { describe, it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { translate } from '../lib/utils/translate.js'
+
+describe('translate()', () => {
+  let phrases
+  const defaultLang = 'en'
+  let logWarn
+
+  beforeEach(() => {
+    logWarn = mock.fn()
+    phrases = {
+      en: {
+        'app.simple': 'Simple text',
+        'app.withdata': 'Hello ${name}',
+        'app.multiple': 'User ${user} has ${count} items',
+        'app.array': 'Items: ${items}',
+        'app.arraymap': 'Names: $map{users:name:, }',
+        'error.TEST_ERROR': 'Test error message'
+      },
+      fr: {
+        'app.simple': 'Texte simple',
+        'app.withdata': 'Bonjour ${name}'
+      }
+    }
+  })
+
+  it('should return simple translated string', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.simple'), 'Simple text')
+  })
+
+  it('should return string in specified language', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'fr', 'app.simple'), 'Texte simple')
+  })
+
+  it('should return key if translation not found', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.missing'), 'app.missing')
+  })
+
+  it('should call logWarn when key is missing', () => {
+    translate(phrases, defaultLang, logWarn, 'en', 'app.missing')
+    assert.equal(logWarn.mock.callCount(), 1)
+    assert.ok(logWarn.mock.calls[0].arguments[0].includes('app.missing'))
+  })
+
+  it('should use default language when lang is not a string', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, null, 'app.simple'), 'Simple text')
+    assert.equal(translate(phrases, defaultLang, logWarn, undefined, 'app.simple'), 'Simple text')
+    assert.equal(translate(phrases, defaultLang, logWarn, 42, 'app.simple'), 'Simple text')
+  })
+
+  it('should replace single placeholder with data', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.withdata', { name: 'John' }), 'Hello John')
+  })
+
+  it('should replace multiple placeholders', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.multiple', { user: 'Alice', count: 5 }), 'User Alice has 5 items')
+  })
+
+  it('should leave unreplaced placeholders when data is missing', () => {
+    const result = translate(phrases, defaultLang, logWarn, 'en', 'app.withdata', {})
+    assert.equal(result, 'Hello ${name}')
+  })
+
+  it('should return string without substitution when no data provided', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.simple'), 'Simple text')
+  })
+
+  it('should handle $map syntax with arrays of objects', () => {
+    const users = [
+      { name: 'Alice', age: 30 },
+      { name: 'Bob', age: 25 }
+    ]
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.arraymap', { users }), 'Names: Alice, Bob')
+  })
+
+  it('should translate error objects', () => {
+    const mockError = {
+      constructor: { name: 'AdaptError' },
+      code: 'TEST_ERROR',
+      data: {}
+    }
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', mockError), 'Test error message')
+  })
+
+  it('should translate error values in data', () => {
+    phrases.en['app.status'] = 'Status: ${err}'
+    phrases.en['error.INNER'] = 'inner error'
+    const innerError = {
+      constructor: { name: 'AdaptError' },
+      code: 'INNER',
+      data: {}
+    }
+    assert.equal(translate(phrases, defaultLang, logWarn, 'en', 'app.status', { err: innerError }), 'Status: inner error')
+  })
+
+  it('should translate error values inside arrays in data', () => {
+    phrases.en['app.errors'] = 'Errors: ${errs}'
+    phrases.en['error.E1'] = 'err one'
+    phrases.en['error.E2'] = 'err two'
+    const errs = [
+      { constructor: { name: 'AdaptError' }, code: 'E1', data: {} },
+      { constructor: { name: 'AdaptError' }, code: 'E2', data: {} }
+    ]
+    const result = translate(phrases, defaultLang, logWarn, 'en', 'app.errors', { errs })
+    assert.ok(result.includes('err one'))
+    assert.ok(result.includes('err two'))
+  })
+
+  it('should return key when language does not exist', () => {
+    assert.equal(translate(phrases, defaultLang, logWarn, 'de', 'app.simple'), 'app.simple')
+  })
+})

package/tests/utils-translateError.spec.js

@@ -0,0 +1,63 @@
+/* eslint-disable no-template-curly-in-string */
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { translateError } from '../lib/utils/translateError.js'
+
+describe('translateError()', () => {
+  const phrases = {
+    en: {
+      'error.TEST_CODE': 'Error: ${message}',
+      'error.SIMPLE': 'Simple error'
+    }
+  }
+  const defaultLang = 'en'
+  const logWarn = mock.fn()
+
+  it('should translate error with code', () => {
+    const error = {
+      constructor: { name: 'AdaptError' },
+      code: 'SIMPLE',
+      data: {}
+    }
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', error), 'Simple error')
+  })
+
+  it('should translate error with data', () => {
+    const error = {
+      constructor: { name: 'TestError' },
+      code: 'TEST_CODE',
+      data: { message: 'Something went wrong' }
+    }
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', error), 'Error: Something went wrong')
+  })
+
+  it('should return non-error values unchanged', () => {
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', 'just a string'), 'just a string')
+  })
+
+  it('should return null unchanged', () => {
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', null), null)
+  })
+
+  it('should return undefined unchanged', () => {
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', undefined), undefined)
+  })
+
+  it('should return number values unchanged', () => {
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', 42), 42)
+  })
+
+  it('should use error object itself as data when data is missing', () => {
+    phrases.en['error.NO_DATA'] = 'Code: ${code}'
+    const error = {
+      constructor: { name: 'AdaptError' },
+      code: 'NO_DATA'
+    }
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', error), 'Code: NO_DATA')
+  })
+
+  it('should handle objects without constructor gracefully', () => {
+    const obj = {}
+    assert.equal(translateError(phrases, defaultLang, logWarn, 'en', obj), obj)
+  })
+})