@vocab/core 1.1.2 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+### MIT License
+
+Copyright (c) 2020 SEEK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -422,20 +422,81 @@ Or to re-run the compiler when files change use:
 $ vocab compile --watch
 ```
 
-## External translation tooling
+## External Translation Tooling
 
 Vocab can be used to synchronize your translations with translations from a remote translation platform.
 
-| Platform                                     | Environment Variables               |
-| -------------------------------------------- | ----------------------------------- |
-| [Phrase](https://developers.phrase.com/api/) | PHRASE_PROJECT_ID, PHRASE_API_TOKEN |
+| Platform | Environment Variables               |
+| -------- | ----------------------------------- |
+| [Phrase] | PHRASE_PROJECT_ID, PHRASE_API_TOKEN |
 
 ```bash
 $ vocab push --branch my-branch
-$ vocab push --branch my-branch --delete-unused-keys
 $ vocab pull --branch my-branch
 ```
 
+### [Phrase] Platform Features
+
+#### Delete Unused keys
+
+When uploading translations, Phrase identifies keys that exist in the Phrase project, but were not
+referenced in the upload. These keys can be deleted from Phrase by providing the
+`---delete-unused-keys` flag to `vocab push`. E.g.
+
+```sh
+$ vocab push --branch my-branch --delete-unused-keys
+```
+
+[phrase]: https://developers.phrase.com/api/
+
+#### [Tags]
+
+`vocab push` supports uploading [tags] to Phrase.
+
+Tags can be added to an individual key via the `tags` property:
+
+```jsonc
+// translations.json
+{
+  "Hello": {
+    "message": "Hello",
+    "tags": ["greeting", "home_page"]
+  },
+  "Goodbye": {
+    "message": "Goodbye",
+    "tags": ["home_page"]
+  }
+}
+```
+
+Tags can also be added under a top-level `_meta` field. This will result in the tags applying to all
+keys specified in the file:
+
+```jsonc
+// translations.json
+{
+  "_meta": {
+    "tags": ["home_page"]
+  },
+  "Hello": {
+    "message": "Hello",
+    "tags": ["greeting"]
+  },
+  "Goodbye": {
+    "message": "Goodbye"
+  }
+}
+```
+
+In the above example, both the `Hello` and `Goodbye` keys would have the `home_page` tag attached to
+them, but only the `Hello` key would have the `usage_greeting` tag attached to it.
+
+**NOTE**: Only tags specified on keys in your [`devLanguage`][configuration] will be uploaded.
+Tags on keys in other languages will be ignored.
+
+[tags]: https://support.phrase.com/hc/en-us/articles/5822598372252-Tags-Strings-
+[configuration]: #Configuration
+
 ## Troubleshooting
 
 ### Problem: Passed locale is being ignored or using en-US instead

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

@@ -1,5 +1,5 @@
-export declare class ValidationError extends Error {
-    code: string;
-    rawMessage: string;
-    constructor(code: string, message: string);
-}
+export declare class ValidationError extends Error {
+    code: string;
+    rawMessage: string;
+    constructor(code: string, message: string);
+}

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

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

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

@@ -1,4 +1,4 @@
-import { UserConfig } from '@vocab/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;
+import { UserConfig } from '@vocab/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,5 +1,5 @@
-import { MessageGenerator, TranslationsByKey } from '@vocab/types';
-export declare function generateLanguageFromTranslations({ baseTranslations, generator, }: {
-    baseTranslations: TranslationsByKey<string>;
-    generator: MessageGenerator;
-}): TranslationsByKey<string>;
+import { MessageGenerator, TranslationsByKey } from '@vocab/types';
+export declare function generateLanguageFromTranslations({ baseTranslations, generator, }: {
+    baseTranslations: TranslationsByKey<string>;
+    generator: MessageGenerator;
+}): TranslationsByKey<string>;

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

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

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

@@ -1,6 +1,6 @@
-export { compile, watch } from './compile';
-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 { compile, watch } from './compile';
+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';

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

@@ -1,30 +1,32 @@
-import { TranslationsByKey, UserConfig, LoadedTranslation, LanguageTarget } from '@vocab/types';
-import { Fallback } from './utils';
-export declare function getUniqueKey(key: string, namespace: string): string;
-export declare function mergeWithDevLanguageTranslation({ translation, devTranslation, }: {
-    translation: TranslationsByKey;
-    devTranslation: TranslationsByKey;
-}): TranslationsByKey<string>;
-export declare function getLanguageHierarchy({ languages, }: {
-    languages: Array<LanguageTarget>;
-}): Map<string, string[]>;
-export declare function getFallbackLanguageOrder({ languages, languageName, devLanguage, fallbacks, }: {
-    languages: LanguageTarget[];
-    languageName: string;
-    devLanguage: string;
-    fallbacks: Fallback;
-}): string[];
-export declare function loadAltLanguageFile({ filePath, languageName, devTranslation, fallbacks, }: {
-    filePath: string;
-    languageName: string;
-    devTranslation: TranslationsByKey;
-    fallbacks: Fallback;
-}, { devLanguage, languages }: UserConfig): TranslationsByKey;
-export declare function loadTranslation({ filePath, fallbacks, }: {
-    filePath: string;
-    fallbacks: Fallback;
-}, userConfig: UserConfig): LoadedTranslation;
-export declare function loadAllTranslations({ fallbacks, includeNodeModules, }: {
-    fallbacks: Fallback;
-    includeNodeModules: boolean;
-}, config: UserConfig): Promise<Array<LoadedTranslation>>;
+import type { TranslationsByKey, UserConfig, LoadedTranslation, LanguageTarget } from '@vocab/types';
+import { Fallback } from './utils';
+export declare function getUniqueKey(key: string, namespace: string): string;
+export declare function mergeWithDevLanguageTranslation({ translation, devTranslation, }: {
+    translation: TranslationsByKey;
+    devTranslation: TranslationsByKey;
+}): TranslationsByKey<string>;
+export declare function getLanguageHierarchy({ languages, }: {
+    languages: Array<LanguageTarget>;
+}): Map<string, string[]>;
+export declare function getFallbackLanguageOrder({ languages, languageName, devLanguage, fallbacks, }: {
+    languages: LanguageTarget[];
+    languageName: string;
+    devLanguage: string;
+    fallbacks: Fallback;
+}): string[];
+export declare function loadAltLanguageFile({ filePath, languageName, devTranslation, fallbacks, }: {
+    filePath: string;
+    languageName: string;
+    devTranslation: TranslationsByKey;
+    fallbacks: Fallback;
+}, { devLanguage, languages }: UserConfig): TranslationsByKey;
+export declare function loadTranslation({ filePath, fallbacks, withTags, }: {
+    filePath: string;
+    fallbacks: Fallback;
+    withTags?: boolean;
+}, userConfig: UserConfig): LoadedTranslation;
+export declare function loadAllTranslations({ fallbacks, includeNodeModules, withTags, }: {
+    fallbacks: Fallback;
+    includeNodeModules: boolean;
+    withTags?: boolean;
+}, config: UserConfig): Promise<Array<LoadedTranslation>>;

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

@@ -1,3 +1,3 @@
-import debug from 'debug';
-export declare const trace: debug.Debugger;
-export declare const log: (...params: unknown[]) => void;
+import debug from 'debug';
+export declare const trace: debug.Debugger;
+export declare const log: (...params: unknown[]) => void;

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

@@ -1,3 +1,3 @@
-import { TranslationModule, TranslationMessagesByKey } from '@vocab/types';
-export { createTranslationFile } from './translation-file';
-export declare const createLanguage: (module: TranslationMessagesByKey) => TranslationModule<any>;
+import { TranslationModule, TranslationMessagesByKey } from '@vocab/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';
-export declare function createTranslationFile<Language extends LanguageName, FormatFnByKey extends ParsedFormatFnByKey>(translationsByLanguage: TranslationModuleByLanguage<Language, FormatFnByKey>): TranslationFile<Language, FormatFnByKey>;
+import { TranslationModuleByLanguage, LanguageName, ParsedFormatFnByKey, TranslationFile } from '@vocab/types';
+export declare function createTranslationFile<Language extends LanguageName, FormatFnByKey extends ParsedFormatFnByKey>(translationsByLanguage: TranslationModuleByLanguage<Language, FormatFnByKey>): TranslationFile<Language, FormatFnByKey>;

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

@@ -1,26 +1,26 @@
-import type { LanguageName, LanguageTarget, TranslationsByKey, TranslationMessagesByKey, UserConfig } from '@vocab/types';
-export declare const defaultTranslationDirSuffix = ".vocab";
-export declare const devTranslationFileName = "translations.json";
-export declare type Fallback = 'none' | 'valid' | 'all';
-export declare function isDevLanguageFile(filePath: string): boolean;
-export declare function isAltLanguageFile(filePath: string): boolean;
-export declare function isTranslationDirectory(filePath: string, { translationsDirectorySuffix, }: {
-    translationsDirectorySuffix?: string;
-}): boolean;
-export declare function getTranslationFolderGlob({ translationsDirectorySuffix, }: {
-    translationsDirectorySuffix?: string;
-}): string;
-export declare function getDevTranslationFileGlob({ translationsDirectorySuffix, }: {
-    translationsDirectorySuffix?: string;
-}): string;
-export declare function getAltTranslationFileGlob(config: UserConfig): string;
-export declare function getAltLanguages({ devLanguage, languages, }: {
-    devLanguage: LanguageName;
-    languages: Array<LanguageTarget>;
-}): string[];
-export declare function getDevLanguageFileFromTsFile(tsFilePath: string): string;
-export declare function getDevLanguageFileFromAltLanguageFile(altLanguageFilePath: string): string;
-export declare function getTSFileFromDevLanguageFile(devLanguageFilePath: string): string;
-export declare function getAltLanguageFilePath(devLanguageFilePath: string, language: string): string;
-export declare function mapValues<Key extends string, OriginalValue, ReturnValue>(obj: Record<Key, OriginalValue>, func: (val: OriginalValue) => ReturnValue): TranslationMessagesByKey<Key>;
-export declare function getTranslationMessages<Key extends string>(translations: TranslationsByKey<Key>): TranslationMessagesByKey<Key>;
+import type { LanguageName, LanguageTarget, TranslationsByKey, TranslationMessagesByKey, UserConfig } from '@vocab/types';
+export declare const defaultTranslationDirSuffix = ".vocab";
+export declare const devTranslationFileName = "translations.json";
+export type Fallback = 'none' | 'valid' | 'all';
+export declare function isDevLanguageFile(filePath: string): boolean;
+export declare function isAltLanguageFile(filePath: string): boolean;
+export declare function isTranslationDirectory(filePath: string, { translationsDirectorySuffix, }: {
+    translationsDirectorySuffix?: string;
+}): boolean;
+export declare function getTranslationFolderGlob({ translationsDirectorySuffix, }: {
+    translationsDirectorySuffix?: string;
+}): string;
+export declare function getDevTranslationFileGlob({ translationsDirectorySuffix, }: {
+    translationsDirectorySuffix?: string;
+}): string;
+export declare function getAltTranslationFileGlob(config: UserConfig): string;
+export declare function getAltLanguages({ devLanguage, languages, }: {
+    devLanguage: LanguageName;
+    languages: Array<LanguageTarget>;
+}): string[];
+export declare function getDevLanguageFileFromTsFile(tsFilePath: string): string;
+export declare function getDevLanguageFileFromAltLanguageFile(altLanguageFilePath: string): string;
+export declare function getTSFileFromDevLanguageFile(devLanguageFilePath: string): string;
+export declare function getAltLanguageFilePath(devLanguageFilePath: string, language: string): string;
+export declare function mapValues<Key extends string, OriginalValue, ReturnValue>(obj: Record<Key, OriginalValue>, func: (val: OriginalValue) => ReturnValue): TranslationMessagesByKey<Key>;
+export declare function getTranslationMessages<Key extends string>(translations: TranslationsByKey<Key>): TranslationMessagesByKey<Key>;

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

@@ -1,3 +1,3 @@
-import { UserConfig, LoadedTranslation, LanguageName } from '@vocab/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>;
+import { UserConfig, LoadedTranslation, LanguageName } from '@vocab/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>;