@vocab/core 1.2.4 → 1.3.0

package/dist/declarations/src/compile.d.ts

@@ -1,4 +1,4 @@
-import { LoadedTranslation, UserConfig } from '@vocab/types';
+import { LoadedTranslation, UserConfig } from './types';
 export declare function generateRuntime(loadedTranslation: LoadedTranslation): Promise<void>;
 export declare function watch(config: UserConfig): () => Promise<void>;
 export declare function compile({ watch: shouldWatch }: {

package/dist/declarations/src/config.d.ts

@@ -1,4 +1,4 @@
-import { UserConfig } from '@vocab/types';
+import type { UserConfig } from './types';
 export declare function validateConfig(c: UserConfig): boolean;
 export declare function resolveConfig(customConfigFilePath?: string): Promise<UserConfig | null>;
 export declare function resolveConfigSync(customConfigFilePath?: string): UserConfig | null;

package/dist/declarations/src/generate-language.d.ts

@@ -1,4 +1,4 @@
-import { MessageGenerator, TranslationsByKey } from '@vocab/types';
+import type { MessageGenerator, TranslationsByKey } from './types';
 export declare function generateLanguageFromTranslations({ baseTranslations, generator, }: {
     baseTranslations: TranslationsByKey<string>;
     generator: MessageGenerator;

package/dist/declarations/src/icu-handler.d.ts

@@ -1,2 +1,2 @@
-import { ParsedICUMessages, TranslationMessagesByKey } from '@vocab/types';
+import type { ParsedICUMessages, TranslationMessagesByKey } from './types';
 export declare const getParsedICUMessages: (m: TranslationMessagesByKey, locale: string) => ParsedICUMessages<any>;

package/dist/declarations/src/index.d.ts

@@ -3,4 +3,4 @@ export { validate } from './validate';
 export { resolveConfig, resolveConfigSync, validateConfig } from './config';
 export { getAltLanguages, getAltLanguageFilePath, getDevLanguageFileFromTsFile, } from './utils';
 export { getUniqueKey, loadAllTranslations, loadTranslation, } from './load-translations';
-export type { TranslationFile } from '@vocab/types';
+export * from './types';

package/dist/declarations/src/load-translations.d.ts

@@ -1,4 +1,4 @@
-import type { TranslationsByKey, UserConfig, LoadedTranslation, LanguageTarget } from '@vocab/types';
+import type { TranslationsByKey, UserConfig, LoadedTranslation, LanguageTarget } from './types';
 import { Fallback } from './utils';
 export declare function getUniqueKey(key: string, namespace: string): string;
 export declare function mergeWithDevLanguageTranslation({ translation, devTranslation, }: {

package/dist/declarations/src/runtime.d.ts

@@ -1,3 +1,3 @@
-import { TranslationModule, TranslationMessagesByKey } from '@vocab/types';
+import type { TranslationModule, TranslationMessagesByKey } from './types';
 export { createTranslationFile } from './translation-file';
 export declare const createLanguage: (module: TranslationMessagesByKey) => TranslationModule<any>;

package/dist/declarations/src/translation-file.d.ts

@@ -1,2 +1,2 @@
-import { TranslationModuleByLanguage, LanguageName, ParsedFormatFnByKey, TranslationFile } from '@vocab/types';
+import type { TranslationModuleByLanguage, LanguageName, ParsedFormatFnByKey, TranslationFile } from './types';
 export declare function createTranslationFile<Language extends LanguageName, FormatFnByKey extends ParsedFormatFnByKey>(translationsByLanguage: TranslationModuleByLanguage<Language, FormatFnByKey>): TranslationFile<Language, FormatFnByKey>;

package/dist/declarations/src/types.d.ts

@@ -0,0 +1,115 @@
+export type { FormatXMLElementFn } from 'intl-messageformat';
+export type LanguageName = string;
+export type TranslationKey = string;
+export type TranslationMessage = string;
+export type ParsedFormatFn = (parts: any) => any;
+export type ParsedFormatFnByKey = Record<string, ParsedFormatFn>;
+/**
+ * Equivalent to the `string` type, but tricks the language server into prodiving
+ * suggestions for string literals passed into the `Suggestions` generic parameter
+ *
+ * @example
+ * Accept any string, but suggest specific animals
+ * ```
+ * type AnyAnimal = StringWithSuggestions<"cat" | "dog">;
+ * // Suggests cat and dog, but accepts any string
+ * const animal: AnyAnimal = "";
+ * ```
+ */
+export type StringWithSuggestions<Suggestions extends string> = Suggestions | Omit<string, Suggestions>;
+/**
+ * ParsedICUMessage A strictly typed formatter from intl-messageformat
+ */
+interface ParsedICUMessage<FormatFn extends ParsedFormatFn> {
+    format: FormatFn;
+}
+export type ParsedICUMessages<FormatFnByKey extends ParsedFormatFnByKey> = {
+    [key in keyof FormatFnByKey]: ParsedICUMessage<FormatFnByKey[key]>;
+};
+/**
+ * TranslationModule is a wrapper around a potentially asynchronously loaded set of ParsedICUMessages
+ */
+export type TranslationModule<FormatFnByKey extends ParsedFormatFnByKey> = {
+    getValue: (locale: string) => ParsedICUMessages<FormatFnByKey> | undefined;
+    load: () => Promise<void>;
+};
+export type TranslationModuleByLanguage<Language extends LanguageName, FormatFnByKey extends ParsedFormatFnByKey> = Record<Language, TranslationModule<FormatFnByKey>>;
+/**
+ * TranslationFile contains a record of TranslationModules per language, exposing a set of methods to load and return the module by language
+ */
+export type TranslationFile<Language extends LanguageName, FormatFnByKey extends ParsedFormatFnByKey> = {
+    /**
+     *  Retrieve messages. If not loaded, will attempt to load messages and resolve once complete.
+     */
+    getMessages: (language: Language, locale?: string) => Promise<ParsedICUMessages<FormatFnByKey>>;
+    /**
+     *  Retrieve already loaded messages. Will return null if no messages have been loaded.
+     */
+    getLoadedMessages: (language: Language, locale?: string) => ParsedICUMessages<FormatFnByKey> | null;
+    /**
+     *  Load messages for the given language. Resolving once complete.
+     */
+    load: (language: Language) => Promise<void>;
+};
+export interface LanguageTarget {
+    name: LanguageName;
+    extends?: LanguageName;
+}
+export interface MessageGenerator {
+    transformElement?: (element: string) => string;
+    transformMessage?: (message: string) => string;
+}
+export interface GeneratedLanguageTarget {
+    name: LanguageName;
+    extends?: LanguageName;
+    generator: MessageGenerator;
+}
+export interface UserConfig {
+    /**
+     * The root directory to compile and validate translations
+     */
+    projectRoot?: string;
+    /**
+     * The language used in translations.json
+     */
+    devLanguage: LanguageName;
+    /**
+     * An array of languages to build for
+     */
+    languages: Array<LanguageTarget>;
+    /**
+     * An array of languages to generate from existing translations
+     */
+    generatedLanguages?: Array<GeneratedLanguageTarget>;
+    /**
+     * A custom suffix to name vocab translation directories
+     */
+    translationsDirectorySuffix?: string;
+    /**
+     * An array of glob paths to ignore from compilation and validation
+     */
+    ignore?: Array<string>;
+}
+export type Tags = Array<string>;
+export interface TranslationFileMetadata {
+    tags?: Tags;
+}
+export interface TranslationData {
+    message: TranslationMessage;
+    description?: string;
+    tags?: Tags;
+}
+export type TranslationsByKey<Key extends TranslationKey = string> = Record<Key, TranslationData>;
+export type TranslationFileContents = TranslationsByKey & {
+    _meta?: TranslationFileMetadata;
+};
+export type TranslationMessagesByKey<Key extends TranslationKey = string> = Record<Key, TranslationMessage>;
+export type TranslationsByLanguage<Key extends TranslationKey = string> = Record<LanguageName, TranslationsByKey<Key>>;
+export type LoadedTranslation<Key extends TranslationKey = string> = {
+    namespace: string;
+    keys: Array<Key>;
+    filePath: string;
+    relativePath: string;
+    languages: TranslationsByLanguage<Key>;
+    metadata: TranslationFileMetadata;
+};

package/dist/declarations/src/utils.d.ts

@@ -1,4 +1,4 @@
-import type { LanguageName, LanguageTarget, TranslationsByKey, TranslationMessagesByKey, UserConfig } from '@vocab/types';
+import type { LanguageName, LanguageTarget, TranslationsByKey, TranslationMessagesByKey, UserConfig } from './types';
 export declare const defaultTranslationDirSuffix = ".vocab";
 export declare const devTranslationFileName = "translations.json";
 export type Fallback = 'none' | 'valid' | 'all';

package/dist/declarations/src/validate/index.d.ts

@@ -1,3 +1,3 @@
-import { UserConfig, LoadedTranslation, LanguageName } from '@vocab/types';
+import { UserConfig, LoadedTranslation, LanguageName } from '../types';
 export declare function findMissingKeys(loadedTranslation: LoadedTranslation, devLanguageName: LanguageName, altLanguages: Array<LanguageName>): readonly [boolean, Record<string, string[]>];
 export declare function validate(config: UserConfig): Promise<boolean>;

package/dist/vocab-core.cjs.dev.js

@@ -438,8 +438,6 @@ async function loadAllTranslations({
   return result;
 }
 
-const encodeWithinSingleQuotes = v => v.replace(/'/g, "\\'");
-const encodeBackslash = v => v.replace(/\\/g, '\\\\');
 function extractHasTags(ast) {
   return ast.some(element => {
     if (icuMessageformatParser.isSelectElement(element)) {
@@ -500,18 +498,16 @@ function extractParamTypes(ast, currentParams) {
 function serialiseObjectToType(v) {
   let result = '';
   for (const [key, value] of Object.entries(v)) {
-    if (value && typeof value === 'object') {
-      result += `'${encodeWithinSingleQuotes(key)}': ${serialiseObjectToType(value)},`;
-    } else {
-      result += `'${encodeWithinSingleQuotes(key)}': ${value},`;
-    }
+    result += `${JSON.stringify(key)}: ${value && typeof value === 'object' ? serialiseObjectToType(value) : value},`;
   }
   return `{ ${result} }`;
 }
-const banner = `// This file is automatically generated by Vocab.\n// To make changes update translation.json files directly.`;
-const serializeModuleImports = (imports, moduleName) => {
+const serializeTypeImports = (imports, moduleName) => {
+  if (imports.size === 0) {
+    return '';
+  }
   const importNames = Array.from(imports);
-  return `import { ${Array.from(importNames).join(', ')} } from '${moduleName}'`;
+  return `import type { ${importNames.join(', ')} } from '${moduleName}';`;
 };
 function serialiseTranslationRuntime(value, imports, loadedTranslation) {
   trace('Serialising translations:', loadedTranslation);
@@ -524,21 +520,30 @@ function serialiseTranslationRuntime(value, imports, loadedTranslation) {
     let translationFunctionString = `() => ${message}`;
     if (Object.keys(params).length > 0) {
       const formatGeneric = hasTags ? '<T = string>' : '';
-      const formatReturn = hasTags ? 'string | T | Array<string | T>' : 'string';
+      const formatReturn = hasTags && imports.has('FormatXMLElementFn') ? 'ReturnType<FormatXMLElementFn<T>>' : 'string';
       translationFunctionString = `${formatGeneric}(values: ${serialiseObjectToType(params)}) => ${formatReturn}`;
     }
-    translationsType[encodeBackslash(key)] = translationFunctionString;
+    translationsType[key] = translationFunctionString;
   }
-  const content = Object.entries(loadedTranslation.languages).map(([languageName, translations]) => `'${encodeWithinSingleQuotes(languageName)}': createLanguage(${JSON.stringify(getTranslationMessages(translations))})`).join(',');
   const languagesUnionAsString = Object.keys(loadedTranslation.languages).map(l => `'${l}'`).join(' | ');
-  return `${banner}
+  const languageEntries = Object.entries(loadedTranslation.languages).map(([languageName, translations]) => `${JSON.stringify(languageName)}: createLanguage(${JSON.stringify(getTranslationMessages(translations))})`).join(',');
+  return (/* ts */`
+    // This file is automatically generated by Vocab.
+    // To make changes update translation.json files directly.
 
-  ${serializeModuleImports(imports, '@vocab/types')}
-  import { createLanguage, createTranslationFile } from '@vocab/core/runtime';
+    ${serializeTypeImports(imports, '@vocab/core')}
+    import { createLanguage, createTranslationFile } from '@vocab/core/runtime';
 
-  const translations = createTranslationFile<${languagesUnionAsString}, ${serialiseObjectToType(translationsType)}>({${content}});
+    const translations = createTranslationFile<
+      ${languagesUnionAsString},
+      ${serialiseObjectToType(translationsType)}
+    >({
+      ${languageEntries}
+    });
 
-  export default translations;`;
+    export default translations;
+  `
+  );
 }
 async function generateRuntime(loadedTranslation) {
   const {
@@ -559,15 +564,13 @@ async function generateRuntime(loadedTranslation) {
         const [parsedParams, vocabTypesImports] = extractParamTypes(ast, params);
         imports = new Set([...imports, ...vocabTypesImports]);
         params = parsedParams;
-        messages.add(`'${encodeWithinSingleQuotes(translatedLanguage[key].message)}'`);
+        messages.add(JSON.stringify(translatedLanguage[key].message));
       }
     }
-    const returnType = hasTags ? 'NonNullable<ReactNode>' : 'string';
     translationTypes.set(key, {
       params,
       hasTags,
-      message: Array.from(messages).join(' | '),
-      returnType
+      message: Array.from(messages).join(' | ')
     });
   }
   const prettierConfig = await prettier__default["default"].resolveConfig(filePath);

package/dist/vocab-core.cjs.prod.js

@@ -438,8 +438,6 @@ async function loadAllTranslations({
   return result;
 }
 
-const encodeWithinSingleQuotes = v => v.replace(/'/g, "\\'");
-const encodeBackslash = v => v.replace(/\\/g, '\\\\');
 function extractHasTags(ast) {
   return ast.some(element => {
     if (icuMessageformatParser.isSelectElement(element)) {
@@ -500,18 +498,16 @@ function extractParamTypes(ast, currentParams) {
 function serialiseObjectToType(v) {
   let result = '';
   for (const [key, value] of Object.entries(v)) {
-    if (value && typeof value === 'object') {
-      result += `'${encodeWithinSingleQuotes(key)}': ${serialiseObjectToType(value)},`;
-    } else {
-      result += `'${encodeWithinSingleQuotes(key)}': ${value},`;
-    }
+    result += `${JSON.stringify(key)}: ${value && typeof value === 'object' ? serialiseObjectToType(value) : value},`;
   }
   return `{ ${result} }`;
 }
-const banner = `// This file is automatically generated by Vocab.\n// To make changes update translation.json files directly.`;
-const serializeModuleImports = (imports, moduleName) => {
+const serializeTypeImports = (imports, moduleName) => {
+  if (imports.size === 0) {
+    return '';
+  }
   const importNames = Array.from(imports);
-  return `import { ${Array.from(importNames).join(', ')} } from '${moduleName}'`;
+  return `import type { ${importNames.join(', ')} } from '${moduleName}';`;
 };
 function serialiseTranslationRuntime(value, imports, loadedTranslation) {
   trace('Serialising translations:', loadedTranslation);
@@ -524,21 +520,30 @@ function serialiseTranslationRuntime(value, imports, loadedTranslation) {
     let translationFunctionString = `() => ${message}`;
     if (Object.keys(params).length > 0) {
       const formatGeneric = hasTags ? '<T = string>' : '';
-      const formatReturn = hasTags ? 'string | T | Array<string | T>' : 'string';
+      const formatReturn = hasTags && imports.has('FormatXMLElementFn') ? 'ReturnType<FormatXMLElementFn<T>>' : 'string';
       translationFunctionString = `${formatGeneric}(values: ${serialiseObjectToType(params)}) => ${formatReturn}`;
     }
-    translationsType[encodeBackslash(key)] = translationFunctionString;
+    translationsType[key] = translationFunctionString;
   }
-  const content = Object.entries(loadedTranslation.languages).map(([languageName, translations]) => `'${encodeWithinSingleQuotes(languageName)}': createLanguage(${JSON.stringify(getTranslationMessages(translations))})`).join(',');
   const languagesUnionAsString = Object.keys(loadedTranslation.languages).map(l => `'${l}'`).join(' | ');
-  return `${banner}
+  const languageEntries = Object.entries(loadedTranslation.languages).map(([languageName, translations]) => `${JSON.stringify(languageName)}: createLanguage(${JSON.stringify(getTranslationMessages(translations))})`).join(',');
+  return (/* ts */`
+    // This file is automatically generated by Vocab.
+    // To make changes update translation.json files directly.
 
-  ${serializeModuleImports(imports, '@vocab/types')}
-  import { createLanguage, createTranslationFile } from '@vocab/core/runtime';
+    ${serializeTypeImports(imports, '@vocab/core')}
+    import { createLanguage, createTranslationFile } from '@vocab/core/runtime';
 
-  const translations = createTranslationFile<${languagesUnionAsString}, ${serialiseObjectToType(translationsType)}>({${content}});
+    const translations = createTranslationFile<
+      ${languagesUnionAsString},
+      ${serialiseObjectToType(translationsType)}
+    >({
+      ${languageEntries}
+    });
 
-  export default translations;`;
+    export default translations;
+  `
+  );
 }
 async function generateRuntime(loadedTranslation) {
   const {
@@ -559,15 +564,13 @@ async function generateRuntime(loadedTranslation) {
         const [parsedParams, vocabTypesImports] = extractParamTypes(ast, params);
         imports = new Set([...imports, ...vocabTypesImports]);
         params = parsedParams;
-        messages.add(`'${encodeWithinSingleQuotes(translatedLanguage[key].message)}'`);
+        messages.add(JSON.stringify(translatedLanguage[key].message));
       }
     }
-    const returnType = hasTags ? 'NonNullable<ReactNode>' : 'string';
     translationTypes.set(key, {
       params,
       hasTags,
-      message: Array.from(messages).join(' | '),
-      returnType
+      message: Array.from(messages).join(' | ')
     });
   }
   const prettierConfig = await prettier__default["default"].resolveConfig(filePath);

package/dist/vocab-core.esm.js

@@ -422,8 +422,6 @@ async function loadAllTranslations({
   return result;
 }
 
-const encodeWithinSingleQuotes = v => v.replace(/'/g, "\\'");
-const encodeBackslash = v => v.replace(/\\/g, '\\\\');
 function extractHasTags(ast) {
   return ast.some(element => {
     if (isSelectElement(element)) {
@@ -484,18 +482,16 @@ function extractParamTypes(ast, currentParams) {
 function serialiseObjectToType(v) {
   let result = '';
   for (const [key, value] of Object.entries(v)) {
-    if (value && typeof value === 'object') {
-      result += `'${encodeWithinSingleQuotes(key)}': ${serialiseObjectToType(value)},`;
-    } else {
-      result += `'${encodeWithinSingleQuotes(key)}': ${value},`;
-    }
+    result += `${JSON.stringify(key)}: ${value && typeof value === 'object' ? serialiseObjectToType(value) : value},`;
   }
   return `{ ${result} }`;
 }
-const banner = `// This file is automatically generated by Vocab.\n// To make changes update translation.json files directly.`;
-const serializeModuleImports = (imports, moduleName) => {
+const serializeTypeImports = (imports, moduleName) => {
+  if (imports.size === 0) {
+    return '';
+  }
   const importNames = Array.from(imports);
-  return `import { ${Array.from(importNames).join(', ')} } from '${moduleName}'`;
+  return `import type { ${importNames.join(', ')} } from '${moduleName}';`;
 };
 function serialiseTranslationRuntime(value, imports, loadedTranslation) {
   trace('Serialising translations:', loadedTranslation);
@@ -508,21 +504,30 @@ function serialiseTranslationRuntime(value, imports, loadedTranslation) {
     let translationFunctionString = `() => ${message}`;
     if (Object.keys(params).length > 0) {
       const formatGeneric = hasTags ? '<T = string>' : '';
-      const formatReturn = hasTags ? 'string | T | Array<string | T>' : 'string';
+      const formatReturn = hasTags && imports.has('FormatXMLElementFn') ? 'ReturnType<FormatXMLElementFn<T>>' : 'string';
       translationFunctionString = `${formatGeneric}(values: ${serialiseObjectToType(params)}) => ${formatReturn}`;
     }
-    translationsType[encodeBackslash(key)] = translationFunctionString;
+    translationsType[key] = translationFunctionString;
   }
-  const content = Object.entries(loadedTranslation.languages).map(([languageName, translations]) => `'${encodeWithinSingleQuotes(languageName)}': createLanguage(${JSON.stringify(getTranslationMessages(translations))})`).join(',');
   const languagesUnionAsString = Object.keys(loadedTranslation.languages).map(l => `'${l}'`).join(' | ');
-  return `${banner}
+  const languageEntries = Object.entries(loadedTranslation.languages).map(([languageName, translations]) => `${JSON.stringify(languageName)}: createLanguage(${JSON.stringify(getTranslationMessages(translations))})`).join(',');
+  return (/* ts */`
+    // This file is automatically generated by Vocab.
+    // To make changes update translation.json files directly.
 
-  ${serializeModuleImports(imports, '@vocab/types')}
-  import { createLanguage, createTranslationFile } from '@vocab/core/runtime';
+    ${serializeTypeImports(imports, '@vocab/core')}
+    import { createLanguage, createTranslationFile } from '@vocab/core/runtime';
 
-  const translations = createTranslationFile<${languagesUnionAsString}, ${serialiseObjectToType(translationsType)}>({${content}});
+    const translations = createTranslationFile<
+      ${languagesUnionAsString},
+      ${serialiseObjectToType(translationsType)}
+    >({
+      ${languageEntries}
+    });
 
-  export default translations;`;
+    export default translations;
+  `
+  );
 }
 async function generateRuntime(loadedTranslation) {
   const {
@@ -543,15 +548,13 @@ async function generateRuntime(loadedTranslation) {
         const [parsedParams, vocabTypesImports] = extractParamTypes(ast, params);
         imports = new Set([...imports, ...vocabTypesImports]);
         params = parsedParams;
-        messages.add(`'${encodeWithinSingleQuotes(translatedLanguage[key].message)}'`);
+        messages.add(JSON.stringify(translatedLanguage[key].message));
       }
     }
-    const returnType = hasTags ? 'NonNullable<ReactNode>' : 'string';
     translationTypes.set(key, {
       params,
       hasTags,
-      message: Array.from(messages).join(' | '),
-      returnType
+      message: Array.from(messages).join(' | ')
     });
   }
   const prettierConfig = await prettier.resolveConfig(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocab/core",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "main": "dist/vocab-core.cjs.js",
   "module": "dist/vocab-core.esm.js",
   "exports": {
@@ -40,7 +40,6 @@
   ],
   "dependencies": {
     "@formatjs/icu-messageformat-parser": "^2.0.10",
-    "@vocab/types": "^1.2.0",
     "chalk": "^4.1.0",
     "chokidar": "^3.4.3",
     "debug": "^4.3.1",