@sap/cds 8.4.1 → 8.5.0

package/lib/i18n/bundles.js

@@ -0,0 +1,111 @@
+const cds = require('..'), {i18n} = cds.env
+const I18nFiles = require ('./files')
+
+
+class I18nBundle {
+
+  constructor (options={}) {
+    this.files = new I18nFiles (options)
+    this.file = this.files.basename
+  }
+
+  #translations = {}
+
+  /** The default texts to use as fallbacks if a requested translation is not found. */
+  get defaults() { return super.defaults = this.texts4 (i18n.default_language, this.fallback) }
+  get fallback() { return super.fallback = this.texts4 ('',false) }
+
+  /** Synonym for {@link at `this.at`} */
+  get for() { return this.at }
+
+
+  /**
+   * Looks up the entry for the given key and locale.
+   * - if `locale` is omitted, the current locale is used.
+   * - if `args` are provided, fills in placeholders with them.
+   * @returns {string|undefined}
+   */
+  at (key, locale, args) {
+    if (typeof locale !== 'string') [ args, locale ] = [ locale, cds.context?.locale ?? i18n.default_language ]
+    if (typeof key === 'object') key = this.key4(key)
+    let t = this.texts4 (locale) [key]
+    if (t && args) t = t.replace (/{(\w+)}/g, (_,k) => args[k])
+    return t
+  }
+
+
+  /**
+   * Calls this.{@link at}() for all specified locales and returns an dictionary of results.
+   * @example cds.i18n.labels.all('CreatedBy')
+   */
+  all (key, locales, args) {
+    if (!key) return { ...this.translations() } // eslint-disable-line no-constant-binary-expression
+    const all={}, translations = this.translations4 (locales)
+    for (let locale in translations) {
+      let t = translations[locale][key]
+      if (t && args) t = t.replace (/{(\w+)}/g, (_,k) => args[k])
+      all[locale] = t
+    }
+    return all
+  }
+
+
+  /**
+   * Used by {@link at `this.at()`} to determine the i18n key for a given CSN definition.
+   */
+  key4 (d) {
+    const anno = d['@Common.Label'] || d['@title'] || d['@UI.HeaderInfo.TypeName']
+    if (anno) return /{i18n>([^}]+)}/.exec(anno)?.[1] || anno
+    else return d.name || d.type // if any
+  }
+
+
+  /**
+   * Returns translated texts for a specific locale.
+   */
+  texts4 (locale='', _defaults) {
+    const $ = this.#translations;             if (locale in $) return $[locale]
+    const suffix = locale.replace(/-/g,'_');  if (suffix in $) return $[locale] = $[suffix]
+    // nothing cached yet, load content and create translations ...
+    let all = this.files.content4 (locale, suffix)    // load content from all folders
+    if (all.length === 0 && suffix.includes('_')) {   // nothing found, try w/o region ...
+      const lang = suffix.match(/(\w+)_/)[1]          // i.e. en_UK => en
+      if (lang in $) return $[locale] = $[lang]       // already cached -> leave method
+      else all = this.files.content4 (lang, lang)     // load content for language only
+    }
+    const texts = Object.create ((_defaults ?? this.defaults) || Object.prototype)
+    return $[locale] = $[suffix] = Object.assign (texts, ...all)
+  }
+
+
+  /**
+   * Returns all translations for an array of locales or all locales.
+   * @example { de, fr } = cds.i18n.labels.translations('de','fr')
+   * @param { 'all' | string[] } [locale]
+   * @returns {{ [locale:string]: Record<string,string> }}
+   */
+  translations4 (...locales) {
+    let first = locales[0]
+    if (first == null)  locales = cds.env.i18n.languages
+    if (first == 'all') locales = this.files.locales()
+    else if (Array.isArray(first)) locales = first
+    return locales.reduce ((all,l) => (all[l] = this.texts4(l),all), {})
+  }
+
+
+  /**
+   * Returns a proxy to lazily access all translations by locales as object properties.
+   * @example { de, fr } = cds.i18n.labels.translations()
+   */
+  translations() {
+    const b = this, files = b.files, pd = { configurable: true, enumerable: true }
+    return new Proxy (this.#translations, {
+      *[Symbol.iterator](){ for (let l of files.locales()) yield [ l, b.texts4(l) ]},
+      ownKeys(){ return files.locales() }, getOwnPropertyDescriptor(){ return pd },
+      has(t,p) { return files.locales().includes(p) },
+      get(t,p) { return this[p] ?? b.texts4(p) },
+    })
+  }
+}
+
+module.exports = I18nBundle

package/lib/i18n/files.js

@@ -0,0 +1,134 @@
+const cds = require('../index')
+const LOG = cds.log('i18n')
+const { path, fs } = cds.utils
+const { existsSync: exists } = fs
+
+
+/**
+ * Instances of this class are used to fetch and read i18n resources from the file system.
+ * The constructor fetches all i18n files from the existing i18n folders and adds them to
+ * the instance in a files-by-folders fashion.
+ * @example
+ * new cds.i18n.Files
+ * new cds.i18n.Files ({ roots: [ cds.home, cds.root+'/cap/sflight' ] })
+ */
+class I18nFiles {
+
+  constructor (options) {
+
+    // resolve options with defaults from cds.env.i18n config
+    const {i18n} = cds.env, {
+      file = i18n.file, basename = file,
+      folders = i18n.folders,
+      roots = [ i18n.root || cds.root, cds.home ],
+      model = cds.model,
+    } = options || i18n
+
+    // prepare the things we need below...
+    const files = this; this.#options = { roots, folders, basename }
+    const base = RegExp(`${basename}[._]`)
+    const _folders = I18nFiles.folders ??= {}
+    const _entries = I18nFiles.entries ??= {}
+
+    // fetch relatively specified i18n.folders in the neighborhood of sources...
+    const relative_folders = folders.filter (f => f[0] !== '/')
+    if (relative_folders.length) {
+      const leafs = model?.$sources.map(path.dirname) ?? roots, visited = {}
+      ;[...new Set(leafs)].reverse() .forEach (function _visit (dir) {
+        if (dir in visited) return; else visited[dir] = true
+        LOG.debug ('searching for i18n files in the neighborhood of', dir)
+        // is there an i18n folder in the currently visited directory?
+        for (const each of relative_folders) {
+          const f = path.join(dir,each), _exists = _folders[f] ??= exists(f)
+          if (_exists && _add_entries4(f)) return // stop at first match from i18n.folders
+        }
+        // else recurse up the folder hierarchy till reaching package roots ...
+        if (leafs === roots || roots.includes(dir) || exists(path.join(dir,'package.json'))) return
+        else _visit (path.dirname(dir))
+      })
+    }
+
+    // fetch fully specified i18n.folders, i.e., those starting with /
+    const specific_folders = folders.filter (f => f[0] === '/')
+    for (const f of specific_folders) {
+      const _exists = _folders[f] ??= exists(f)
+      _add_entries4 (_exists ? f : path.join(cds.root,f))
+    }
+
+    // helper to add matching files from found folder, if any
+    function _add_entries4 (f) {
+      const matches = (_entries[f] ??= fs.readdirSync(f)) .filter (f => f.match(base))
+      if (matches.length) return files[f] = matches
+    }
+  }
+
+
+  /**
+   * Loads content from all files for the given locale.
+   * @returns {entries[]} An array of entries, one for each file found.
+   */
+  content4 (locale, suffix = locale?.replace(/-/g,'_')) {
+    const content = [], cached = I18nFiles.content ??= {}
+    const _suffix = suffix ? '_'+ suffix : ''
+    for (let dir in this) {
+      const all = cached[dir] ??= this.load('.json',dir) || this.load('.csv',dir) || false
+      if (all) { if (locale in all) content.push (all[locale]); continue }
+      const props = this.load ('.properties', dir, _suffix)
+      if (props) content.push (props)
+    }
+    return content
+  }
+
+  load (ext, dir, _suffix='') {
+    const fn = `${this.basename}${_suffix}${ext}`; if (!this[dir].includes(fn)) return
+    const file = path.join (dir, fn)
+    try { switch (ext) {
+      case '.properties': return _load_properties(file);
+      case '.json': return _load_json(file);
+      case '.csv': return _load_csv(file)
+    }}
+    finally { LOG.debug ('read:', file) }
+  }
+
+
+  /**
+   * Determines the locales for which translation files and content are available.
+   * @returns {string[]}
+   */
+  locales() {
+    return this.#locales ??= (()=>{
+      const unique_locales = new Set()
+      for (let [ folder, files ] of Object.entries(this)) {
+        for (let file of files) {
+          const { name, ext } = path.parse (file); switch (ext) {
+            case '.properties': unique_locales.add(/(?:_(\w+))?$/.exec(name)?.[1]||''); break
+            case '.json': for (let locale in _load_json(path.join(folder,file))) unique_locales.add(locale); break
+            case '.csv': return _load_csv (path.join(folder,file))[0].slice(1)
+          }
+        }
+      }
+      return [...unique_locales]
+    })()
+  }
+
+  #options
+  #locales
+
+  get basename(){ return this.#options.basename }
+  get options(){ return this.#options }
+}
+
+
+const _load_properties = cds.load.properties
+const _load_json = require
+const _load_csv = file => {
+  const csv = cds.load.csv(file); if (!csv) return
+  const [ header, ...rows ] = csv, all = {}
+  header.slice(1).forEach ((lang,i) => {
+    const entries = all[lang] = {}
+    for (let row of rows) if (row[i]) entries[row[0]] = row[i]
+  })
+  return all
+}
+
+module.exports = I18nFiles

package/lib/i18n/index.js

@@ -0,0 +1,63 @@
+const I18nBundle = require ('./bundles')
+const I18nFiles = require ('./files')
+const cds = require('../index')
+
+class I18nFacade {
+
+  Facade = I18nFacade
+  Bundle = I18nBundle
+  Files = I18nFiles
+
+  /** Shortcuts to config options */
+  get folders() { return cds.env.i18n.folders }
+  get file() { return cds.env.i18n.file }
+
+  /**
+   * The default bundle for runtime messages.
+   */
+  get messages() {
+    // ensure we always find our factory defaults as fallback
+    const factory_defaults = cds.utils.path.resolve (__dirname,'../../_i18n')
+    const folders = [ ...cds.env.i18n.folders, factory_defaults ]
+    return super.messages = this.bundle4 ('messages', { folders })
+  }
+
+
+  /**
+   * The default bundle for UI labels and texts.
+   */
+  get labels() {
+    return super.labels = this.bundle4 (cds.context?.model || cds.model)
+  }
+
+  /**
+   * Lazily constructs, caches and returns a bundle for the given subject.
+   * @param {string|object} [file] - a CSN model, or a string used as the bundle's basename
+   * @param {object} [options] - additional options to pass to the bundle constructor
+   * @returns {I18nBundle}
+   */
+  bundle4 (file, options) {
+    if (_is_string(file)) return super[file] ??= new I18nBundle ({ basename: file, ...options })
+    if (_is_model(file))  return _cached(file).texts ??= new I18nBundle ({ model: file })
+    else                  return new I18nBundle (options = file)
+  }
+
+
+  // -----------------------------------------------------------------------------------------------
+  // following are convenience methods, rather useful in cds repl
+
+  files4 (options) {
+    if (typeof options === 'string') options = { roots: [ cds.home, cds.utils.path.resolve(cds.root,options) ] }
+    return new I18nFiles (options)
+  }
+
+  folders4 (options) {
+    return Object.keys (this.files4(options))
+  }
+}
+
+const _cached = m => m._cached ??= Object.defineProperty (m,'_cached',{writable:true}) && {}
+const _is_model = x => typeof x === 'object' && '$sources' in x
+const _is_string = x => typeof x === 'string'
+
+module.exports = exports = new I18nFacade