adapt-authoring-lang 0.0.1

package/.eslintignore

@@ -0,0 +1 @@
+node_modules

package/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "env": {
+      "browser": false,
+      "node": true,
+      "commonjs": false,
+      "es2020": true
+  },
+  "extends": [
+      "standard"
+  ],
+  "parserOptions": {
+      "ecmaVersion": 2020
+  }
+}

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Please describe the issue
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: Tell us what should have happened
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Steps to reproduce
+      description: Tell us how to reproduce the issue
+    validations:
+      required: true
+  - type: input
+    id: aat-version
+    attributes:
+      label: Authoring tool version
+      description: What version of the Adapt authoring tool are you running?
+    validations:
+      required: true
+  - type: input
+    id: fw-version
+    attributes:
+      label: Framework version
+      description: What version of the Adapt framework are you running?
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: sh

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Request a new feature
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature in the Adapt authoring tool! The Adapt team will consider all new feature requests, but unfortunately cannot commit to every one.
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: Please describe your feature request
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Can you work on this feature?
+      description: If you are able to commit your own time to work on this feature, it will greatly increase the liklihood of it being implemented by the core dev team. Otherwise, it will be triaged and prioritised alongside the core team's current priorities.
+      options:
+        - label: I can contribute

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+[//]: # (Please title your PR according to eslint commit conventions)
+[//]: # (See https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention for details)
+
+[//]: # (Add a link to the original issue)
+
+[//]: # (Delete as appropriate)
+### Fix
+* A sentence describing each fix
+
+### Update
+* A sentence describing each udpate
+
+### New
+* A sentence describing each new feature
+
+### Breaking
+* A sentence describing each breaking change
+
+[//]: # (List appropriate steps for testing if needed)
+### Testing
+1. Steps for testing
+
+[//]: # (Mention any other dependencies)
+
+

package/.github/workflows/labelled_prs.yml

@@ -0,0 +1,16 @@
+name: Add labelled PRs to project
+
+on:
+  pull_request:
+    types: [ labeled ]
+
+jobs:
+  add-to-project:
+    if: ${{ github.event.label.name == 'dependencies' }}
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/.github/workflows/new.yml

@@ -0,0 +1,19 @@
+name: Add to main project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -0,0 +1,6 @@
+{
+  "essentialType": "lang",
+  "documentation": {
+    "enable": true
+  }
+}

package/bin/check.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Checks for unused and missing language strings
+*/
+import fs from 'fs/promises'
+import { glob } from 'glob'
+import path from 'path'
+
+const root = `${process.cwd().replaceAll(path.sep, '/')}/node_modules`
+
+async function check () {
+  console.log('Checking for unused language strings')
+
+  const translatedStrings = await getTranslatedStrings()
+  const usedStrings = await getUsedStrings(translatedStrings)
+
+  logUnusedStrings(translatedStrings)
+  logMissingStrings(translatedStrings, usedStrings)
+}
+
+async function getTranslatedStrings () {
+  const langPacks = await glob(`${root}/adapt-authoring-langpack-*/lang`)
+  const keyMap = {}
+  await Promise.all((langPacks).map(async l => {
+    await Promise.all((await fs.readdir(l)).map(async f => {
+      const keys = JSON.parse(await fs.readFile(`${l}/${f}`))
+      const id = f.split('.')[1]
+      Object.keys(keys)
+        .map(k => `${id}.${k}`)
+        .forEach(k => {
+          keyMap[k] = false
+        })
+    }))
+  }))
+  return keyMap
+}
+
+async function getUsedStrings (translatedStrings) {
+  const translatedKeys = Object.keys(translatedStrings)
+  const usedStrings = {}
+  const errorFiles = await glob(`${root}/adapt-authoring-*/errors/*.json`, { absolute: true })
+  await Promise.all(errorFiles.map(async f => {
+    Object.keys(JSON.parse((await fs.readFile(f)))).forEach(e => {
+      const key = `error.${e}`
+      if (!usedStrings[key]) usedStrings[key] = new Set()
+      usedStrings[key].add(f.replace(root, '').split('/')[1]) // only add module name for errors
+    })
+  }))
+  const sourceFiles = await glob(`${root}/adapt-authoring-*/**/*.@(js|hbs)`, { absolute: true })
+  await Promise.all(sourceFiles.map(async f => {
+    const contents = (await fs.readFile(f)).toString()
+    translatedKeys.forEach(k => {
+      translatedStrings[k] = contents.includes(k) ? true : undefined
+    })
+    const match = contents.matchAll(/['|"|`|](app\.[\w|\.]+)\W/g)
+    if (match) {
+      for (const m of match) {
+        const key = m[1]
+        if (!usedStrings[key]) usedStrings[key] = new Set()
+        usedStrings[key].add(f.replace(root, ''))
+      }
+    }
+  }))
+  return usedStrings
+}
+
+function logUnusedStrings (data) {
+  const unusedKeys = Object.entries(data).filter(([k, v]) => !k.startsWith('error.') && !v).map(([k]) => k)
+  console.log('')
+  if (unusedKeys.length) {
+    unusedKeys.forEach(k => console.log(`- ${k}`))
+    console.log(`\n${unusedKeys.length} unused language strings found`)
+    process.exitCode = 1
+  } else {
+    console.log('\nNo unused strings!')
+  }
+}
+
+function logMissingStrings (translatedStrings, usedStrings) {
+  console.log('')
+  const translatedKeys = Object.keys(translatedStrings)
+  const missingStrings = Object.entries(usedStrings).filter(([key]) => !translatedKeys.includes(key) && key !== 'app.js')
+  if (missingStrings.length) {
+    const sep = '\n   => '
+    missingStrings.forEach(([key, files]) => console.log(`- ${key}${sep}${Array.from(files).join(sep)}`))
+    console.log(`\n${missingStrings.length} missing language strings found`)
+    process.exitCode = 1
+  } else {
+    console.log('\nNo missing strings!')
+  }
+}
+
+check()

package/conf/config.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "defaultLang": {
+      "description": "The default language used by the server",
+      "type": "string",
+      "default": "en"
+    }
+  }
+}

package/errors/errors.json

@@ -0,0 +1,9 @@
+{
+  "UNKNOWN_LANG": {
+    "data": {
+      "lang": "language"
+    },
+    "description": "unknown language",
+    "statusCode": 400
+  }
+}

package/index.js

@@ -0,0 +1,5 @@
+/**
+ * Internationalisation of language strings
+ * @namespace lang
+ */
+export { default } from './lib/LangModule.js'

package/lib/LangModule.js

@@ -0,0 +1,190 @@
+import { AbstractModule } from 'adapt-authoring-core'
+import fs from 'fs/promises'
+import { glob } from 'glob'
+import path from 'path'
+
+/**
+ * Module to handle localisation of language strings
+ * @memberof lang
+ * @extends {AbstractModule}
+ */
+class LangModule extends AbstractModule {
+  /** @override */
+  async init () {
+    this.app.lang = this
+    await this.loadPhrases()
+    this.loadRoutes()
+  }
+
+  /**
+   * Returns the languages supported by the application
+   * @type {Array<String>}
+   */
+  get supportedLanguages () {
+    return Object.keys(this.phrases)
+  }
+
+  /**
+   * Loads, validates and merges all defined langage phrases
+   * @return {Promise}
+   */
+  async loadPhrases () {
+    /**
+     * The loaded language phrases to be used for translation
+     * @type {Object}
+     */
+    this.phrases = {}
+    const deps = [
+      { name: this.app.name, rootDir: process.cwd() },
+      ...Object.values(this.app.dependencies)
+    ]
+    return Promise.all(deps.map(async d => this.loadPhrasesForDir(d.rootDir)))
+  }
+
+  /**
+   * Load all lang phrases for a given directory
+   * @param {String} dir Directory to search
+   * @return {Promise} Resolves with the phrases
+   */
+  async loadPhrasesForDir (dir) {
+    const files = await glob('lang/*.json', { cwd: dir, absolute: true })
+    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))
+      } catch (e) {
+        this.log('error', e.message, f)
+      }
+    }))
+  }
+
+  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
+  }
+
+  /**
+   * Loads the router & routes
+   * @return {Promise}
+   */
+  async loadRoutes () {
+    const [auth, server] = await this.app.waitForModule('auth', 'server')
+
+    server.api.addMiddleware(this.addTranslationUtils.bind(this))
+
+    const router = server.api.createChildRouter('lang')
+    router.addRoute({
+      route: '/{:lang}',
+      handlers: { get: this.requestHandler.bind(this) },
+      meta: {
+        get: {
+          summary: 'Retrieve lang strings for single locale',
+          responses: {
+            200: {
+              description: 'Lang strings for the specified locale',
+              content: {
+                'application/json': {}
+              }
+            }
+          }
+        }
+      }
+    })
+    auth.unsecureRoute(router.path, 'get')
+  }
+
+  /**
+   * Load all lang phrases for a language
+   * @param {String} lang The language of strings to load
+   * @return {Object} The phrases
+   */
+  getPhrasesForLang (lang) {
+    const phrases = {}
+    Object.entries(this.phrases).forEach(([key, value]) => {
+      const i = key.indexOf('.')
+      const keyLang = key.slice(0, i)
+      const newKey = key.slice(i + 1)
+      if (keyLang === lang) phrases[newKey] = value
+    })
+    return Object.keys(phrases).length > 1 ? phrases : undefined
+  }
+
+  /**
+   * Adds a translate function to incoming API requests for generating language strings in the original request's supported language
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {function} next
+   */
+  addTranslationUtils (req, res, next) {
+    const lang = req.acceptsLanguages(this.supportedLanguages)
+    req.translate = (key, data) => this.translate(lang, key, data)
+    next()
+  }
+
+  /**
+   * Shortcut to log a missing language key
+   * @param {external:ExpressRequest} req The client request object
+   * @param {external:ExpressResponse} res The server response object
+   * @param {Function} next The callback function
+   */
+  requestHandler (req, res, next) {
+    // defaults to the request (browser) lang
+    const lang = req.params.lang || req.acceptsLanguages(this.supportedLanguages)
+    if (!lang || !this.phrases[lang]) {
+      return next(this.app.errors.UNKNOWN_LANG.setData({ lang }))
+    }
+    res.json(this.phrases[lang])
+  }
+
+  /**
+   * Returns translated language string
+   * @param {String} lang The target language (if undefined, the default server 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}
+   */
+  translate (lang, key, data) {
+    if (typeof lang !== 'string') {
+      lang = this.getConfig('defaultLang')
+    }
+    if (key.constructor.name === 'AdaptError') {
+      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)
+  }
+
+  /**
+   * Translates an AdaptError
+   * @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)
+   */
+  translateError (lang, error) {
+    return error?.constructor?.name === 'AdaptError' ? this.translate(lang, `error.${error.code}`, error.data) : error
+  }
+}
+
+export default LangModule

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "adapt-authoring-lang",
+  "version": "0.0.1",
+  "description": "Localisation for the Adapt authoring tool",
+  "homepage": "https://github.com/taylortom/adapt-authoring-lang",
+  "license": "GPL-3.0",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "at-langcheck": "./bin/check.js"
+  },
+  "repository": "github:adapt-security/adapt-authoring-lang",
+  "dependencies": {
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.12.0",
+    "standard": "^17.1.0"
+  }
+}