@discord/intl-loader-core 0.0.5 → 0.0.6-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl-loader-core",
-  "version": "0.0.5",
+  "version": "0.0.6-rc.0",
   "license": "MIT",
   "description": "Core utilities for writing loaders and transformers using @discord/intl",
   "author": "Jon Egeland",
@@ -19,7 +19,7 @@
     "chokidar": "^3.6.0",
     "debug": "^4.3.6",
     "fast-glob": "^3.3.2",
-    "@discord/intl-message-database": "0.0.5"
+    "@discord/intl-message-database": "0.0.6-rc.0"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12"

package/src/processing.js

@@ -1,10 +1,21 @@
 const path = require('node:path');
 
+const debug = require('debug')('intl:loader-core');
 const { IntlCompiledMessageFormat } = require('@discord/intl-message-database');
 
 const { database } = require('./database');
 const { findAllTranslationFiles, getLocaleFromTranslationsFileName } = require('./util');
 
+/**
+ * @param {string} sourcePath
+ * @param {import('@discord/intl-message-database').IntlSourceFile} sourceFile
+ */
+function debugSourceFile(sourcePath, sourceFile) {
+  debug(
+    `[${sourcePath}] Parsed messages file: type=${sourceFile.type}, locale=${sourceFile.locale}, messageCount=${sourceFile.messageKeys.length}, meta=${JSON.stringify(sourceFile.meta)}`,
+  );
+}
+
 /**
  * @param {string} sourcePath
  * @param {string=} sourceContent
@@ -20,6 +31,8 @@ function processDefinitionsFile(sourcePath, sourceContent, options = {}) {
     // TODO: Make this more configurable/automatically determined.
     locale = 'en-US',
   } = options;
+  debug(`[${sourcePath}] Processing definitions with locale "${locale}"`);
+
   if (sourceContent != null) {
     database.processDefinitionsFileContent(sourcePath, sourceContent);
   } else {
@@ -27,15 +40,22 @@ function processDefinitionsFile(sourcePath, sourceContent, options = {}) {
   }
 
   const sourceFile = database.getSourceFile(sourcePath);
+  debugSourceFile(sourcePath, sourceFile);
   if (sourceFile.type !== 'definition') {
     throw new Error(
       `Expected ${sourcePath} to be a message definitions file, but it resulted in ${sourceFile.type} instead.`,
     );
   }
 
-  const hashedMessageKeys = database.getSourceFileHashedKeys(sourcePath);
+  const messageKeys = database.getSourceFileKeyMap(sourcePath);
   const translationsPath = path.resolve(path.dirname(sourcePath), sourceFile.meta.translationsPath);
-  const translationsLocaleMap = findAllTranslationFiles(translationsPath);
+  let translationsLocaleMap = findAllTranslationFiles(translationsPath);
+  if (translationsLocaleMap instanceof Error) {
+    debug(
+      `[${sourcePath}] Failed to build translations locale map: [${translationsLocaleMap.name}] ${translationsLocaleMap.message}`,
+    );
+    translationsLocaleMap = {};
+  }
 
   if (processTranslations) {
     database.processAllTranslationFiles(translationsLocaleMap);
@@ -44,7 +64,7 @@ function processDefinitionsFile(sourcePath, sourceContent, options = {}) {
   return {
     sourceFile,
     locale,
-    hashedMessageKeys,
+    messageKeys,
     translationsPath,
     translationsLocaleMap,
   };
@@ -56,12 +76,11 @@ function processDefinitionsFile(sourcePath, sourceContent, options = {}) {
  * @param {string=} sourceContent
  * @param {{
  *   locale?: string,
- *   outputFile?: string
  * }=} options
  * @returns {import('./types').ProcessTranslationsResult}
  */
 function processTranslationsFile(sourcePath, sourceContent, options = {}) {
-  const { locale = getLocaleFromTranslationsFileName(sourcePath), outputFile } = options;
+  const { locale = getLocaleFromTranslationsFileName(sourcePath) } = options;
   if (sourceContent) {
     database.processTranslationFileContent(sourcePath, locale, sourceContent);
   } else {
@@ -69,6 +88,7 @@ function processTranslationsFile(sourcePath, sourceContent, options = {}) {
   }
 
   const sourceFile = database.getSourceFile(sourcePath);
+  debugSourceFile(sourcePath, sourceFile);
   if (sourceFile.type !== 'translation') {
     throw new Error(
       `Expected ${sourcePath} to be a message translations file, but it resulted in ${sourceFile.type} instead.`,
@@ -78,7 +98,7 @@ function processTranslationsFile(sourcePath, sourceContent, options = {}) {
   return {
     sourceFile,
     locale,
-    hashedMessageKeys: database.getSourceFileHashedKeys(sourcePath),
+    messageKeys: database.getSourceFileKeyMap(sourcePath),
   };
 }
 

package/src/transformer.js

@@ -77,6 +77,20 @@ class MessageDefinitionsTransformer {
     return `{${localeProperties.join(',')}}`;
   }
 
+  /**
+   * Return a map of key hashes to their original values, as well as a plain-text map of locales
+   * to the file names that they import from.
+   *
+   * @returns {string[]}
+   */
+  debugModeSetup() {
+    if (!this.options.debug) return [];
+
+    return [
+      `loader.withDebugValues(${JSON.stringify(this.options.messageKeys)}, ${JSON.stringify(this.options.localeMap)})`,
+    ];
+  }
+
   /**
    * Returns the reduced, transformed output for this file. Currently not
    * configurable, but could be told to include default messages or preserve
@@ -90,7 +104,9 @@ class MessageDefinitionsTransformer {
       `const {createLoader} = require('@discord/intl');`,
       `const _keys = ${JSON.stringify(this.options.messageKeys)};`,
       `const _locales = ${this.getLocaleRequireMap()};`,
-      'const loader = createLoader(_keys, _locales);',
+      `const _defaultLocale = ${JSON.stringify(this.options.defaultLocale)};`,
+      'const loader = createLoader(_keys, _locales, _defaultLocale);',
+      ...this.debugModeSetup(),
       'export default loader.getBinds();',
     ].join('\n');
   }

package/src/types.d.ts

@@ -2,13 +2,20 @@ import { IntlSourceFile } from '@discord/intl-message-database';
 
 export interface MessageDefinitionsTransformerOptions {
   /**
-   * The list of hashed message keys that this file manages.
+   * The map of message keys that this file manages to their original values. By default, only the
+   * keys of this map are used (the hashed names), but in debug mode the values will also be
+   * included in the transformed file to provide context in errors and warnings.
    */
-  messageKeys: string[];
+  messageKeys: Record<string, string>;
   /**
    * Map of locale names to import paths used for loading translations.
    */
   localeMap: Record<string, string>;
+  /**
+   * Default locale to use for the runtime loader. This is almost always the locale of the source
+   * file being transformed, but can be set explicitly to something else for special cases.
+   */
+  defaultLocale: string;
   /**
    * Function to create a prelude that gets injected at the start of the transformed file to set up
    * anything needed for other injections later on.
@@ -27,6 +34,12 @@ export interface MessageDefinitionsTransformerOptions {
    * may need to wrap the result with the `default` key, like `.then((data) => ({default: data}))`.
    */
   getTranslationImport(importPath: string): string;
+
+  /**
+   * Whether to include additional information about keys and source files in the transformed loader
+   * code to provide context for debugging in errors and warning messages.
+   */
+  debug?: boolean;
 }
 
 /**
@@ -44,11 +57,11 @@ export interface ProcessDefinitionsResult {
    */
   locale: string;
   /**
-   * The full list of message keys contained by the processed source file. While `sourceFile`
-   * contains a list of key _symbols_, this list contains all of the resolved strings for the
-   * hashed message keys.
+   * The full map of message keys contained by the processed source file to their original values.
+   * While `sourceFile` contains a list of key _symbols_, this list contains all of the
+   * resolved strings for the hashed message keys.
    */
-  hashedMessageKeys: string[];
+  messageKeys: Record<string, string>;
   /**
    * Fully-resolved path to the translations directory that was scanned for entries for the
    * source file.
@@ -73,15 +86,15 @@ export interface ProcessTranslationsResult {
    * Direct source file from the database that was created or updated by this process.
    */
   sourceFile: IntlSourceFile;
+  /**
+   * The full map of message keys contained by the processed source file to their original values.
+   * While `sourceFile` contains a list of key _symbols_, this list contains all of the
+   * resolved strings for the hashed message keys.
+   */
+  messageKeys: Record<string, string>;
   /**
    * The locale that was either determined from the sourceFile name or overridden by the options
    * provided to this call.
    */
   locale: string;
-  /**
-   * The full list of message keys contained by the processed source file. While `sourceFile`
-   * contains a list of key _symbols_, this list contains all of the resolved strings for the
-   * hashed message keys.
-   */
-  hashedMessageKeys: string[];
 }

package/src/util.js

@@ -21,7 +21,7 @@ function getLocaleFromTranslationsFileName(fileName) {
  * as a map from locale name to the path for importing.
  *
  * @param {string} translationsPath
- * @returns {Record<string, string>}
+ * @returns {Record<string, string> | Error}
  */
 function findAllTranslationFiles(translationsPath) {
   /** @type {Record<string, string>} */
@@ -40,7 +40,7 @@ function findAllTranslationFiles(translationsPath) {
       localeMap[locale] = filePath;
     }
   } catch (e) {
-    throw new Error(
+    return new Error(
       `The translations directory ${translationsPath} was not found. No translations will be loaded for these messages`,
     );
   }