@vocab/phrase 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @vocab/phrase
 
+## 1.1.0
+
+### Minor Changes
+
+- [`66ed22c`](https://github.com/seek-oss/vocab/commit/66ed22cac6f89018d5fd69fd6f6408e090e1a382) [#93](https://github.com/seek-oss/vocab/pull/93) Thanks [@askoufis](https://github.com/askoufis)! - Add an optional `deleteUnusedKeys` flag to the `push` function. If set to `true`, unused keys will be deleted from Phrase after translations are pushed.
+
+  **EXAMPLE USAGE**:
+
+  ```js
+  import { push } from '@vocab/phrase';
+
+  const vocabConfig = {
+    devLanguage: 'en',
+    language: ['en', 'fr'],
+  };
+
+  await push({ branch: 'myBranch', deleteUnusedKeys: true }, vocabConfig);
+  ```
+
+### Patch Changes
+
+- [`159d559`](https://github.com/seek-oss/vocab/commit/159d559c87c66c3e91c707fb45a1f67ebec07b4d) [#91](https://github.com/seek-oss/vocab/pull/91) Thanks [@askoufis](https://github.com/askoufis)! - Improve error message when Phrase doesn't return any translations for the dev language
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -184,6 +184,14 @@ Configuration can either be passed into the Node API directly or be gathered fro
 **vocab.config.js**
 
 ```js
+function capitalize(element) {
+  return element.toUpperCase();
+}
+
+function pad(message) {
+  return '[' + message + ']';
+}
+
 module.exports = {
   devLanguage: 'en',
   languages: [
@@ -192,11 +200,25 @@ module.exports = {
     { name: 'en-US', extends: 'en' },
     { name: 'fr-FR' }
   ],
+  /**
+   * An array of languages to generate based off translations for existing languages
+   * Default: []
+   */
+  generatedLanguages: [
+    {
+      name: 'generatedLangauge',
+      extends: 'en',
+      generator: {
+        transformElement: capitalize,
+        transformMessage: pad
+      }
+    }
+  ],
   /**
    * The root directory to compile and validate translations
    * Default: Current working directory
    */
-  projectRoot: './example/';
+  projectRoot: './example/',
   /**
    * A custom suffix to name vocab translation directories
    * Default: '.vocab'
@@ -209,6 +231,131 @@ module.exports = {
 };
 ```
 
+## Generated languages
+
+Vocab supports the creation of generated languages via the `generatedLanguages` config.
+
+Generated languages are created by running a message `generator` over every translation message in an existing translation.
+A `generator` may contain a `transformElement` function, a `transformMessage` function, or both.
+Both of these functions accept a single string parameter and return a string.
+
+`transformElement` is applied to string literal values contained within `MessageFormatElement`s.
+A `MessageFormatElement` is an object representing a node in the AST of a compiled translation message.
+Simply put, any text that would end up being translated by a translator, i.e. anything that is not part of the [ICU Message syntax], will be passed to `transformElement`.
+An example of a use case for this function would be adding [diacritics] to every letter in order to stress your UI from a vertical line-height perspective.
+
+`transformMessage` receives the entire translation message _after_ `transformElement` has been applied to its individual elements.
+An example of a use case for this function would be adding padding text to the start/end of your messages in order to easily identify which text in your app has not been extracted into a `translations.json` file.
+
+By default, a generated language's messages will be based off the `devLanguage`'s messages, but this can be overridden by providing an `extends` value that references another language.
+
+**vocab.config.js**
+
+```js
+function capitalize(message) {
+  return message.toUpperCase();
+}
+
+function pad(message) {
+  return '[' + message + ']';
+}
+
+module.exports = {
+  devLanguage: 'en',
+  languages: [{ name: 'en' }, { name: 'fr' }],
+  generatedLanguages: [
+    {
+      name: 'generatedLanguage',
+      extends: 'en',
+      generator: {
+        transformElement: capitalize,
+        transformMessage: pad
+      }
+    }
+  ]
+};
+```
+
+Generated languages are consumed the same way as regular languages.
+Any Vocab API that accepts a `language` parameter will work with a generated language as well as a regular language.
+
+**App.tsx**
+
+```tsx
+const App = () => (
+  <VocabProvider language="generatedLanguage">
+    ...
+  </VocabProvider>
+);
+```
+
+[icu message syntax]: https://formatjs.io/docs/intl-messageformat/#message-syntax
+[diacritics]: https://en.wikipedia.org/wiki/Diacritic
+
+## Pseudo-localization
+
+The `@vocab/pseudo-localize` package exports low-level functions that can be used for pseudo-localization of translation messages.
+
+```ts
+import {
+  extendVowels,
+  padString,
+  pseudoLocalize,
+  substituteCharacters
+} from '@vocab/pseudo-localize';
+
+const message = 'Hello';
+
+// [Hello]
+const paddedMessage = padString(message);
+
+// Ḩẽƚƚö
+const substitutedMessage = substituteCharacters(message);
+
+// Heelloo
+const extendedMessage = extendVowels(message);
+
+// Extend the message and then substitute characters
+// Ḩẽẽƚƚöö
+const pseudoLocalizedMessage = pseudoLocalize(message);
+```
+
+Pseudo-localization is a transformation that can be applied to a translation message.
+Vocab's implementation of this transformation contains the following elements:
+
+- _Start and end markers (`padString`):_ All strings are encapsulated in `[` and `]`. If a developer doesn’t see these characters they know the string has been clipped by an inflexible UI element.
+- _Transformation of ASCII characters to extended character equivalents (`substituteCharacters`):_ Stresses the UI from a vertical line-height perspective, tests font and encoding support, and weeds out strings that haven’t been externalized correctly (they will not have the pseudo-localization applied to them).
+- _Padding text (`extendVowels`):_ Simulates translation-induced expansion. Vocab's implementation of this involves repeating vowels (and `y`) to simulate a 40% expansion in the message's length.
+
+This Netflix technology [blog post][blog post] inspired Vocab's implementation of this
+functionality.
+
+### Generating a pseudo-localized language using Vocab
+
+Vocab can generate a pseudo-localized language via the [`generatedLanguages` config][generated languages config], either via the webpack plugin or your `vocab.config.js` file.
+`@vocab/pseudo-localize` exports a `generator` that can be used directly in your config.
+
+**vocab.config.js**
+
+```js
+const { generator } = require('@vocab/pseudo-localize');
+
+module.exports = {
+  devLanguage: 'en',
+  languages: [{ name: 'en' }, { name: 'fr' }],
+  generatedLanguages: [
+    {
+      name: 'pseudo',
+      extends: 'en',
+      generator
+    }
+  ]
+};
+```
+
+[blog post]: https://netflixtechblog.com/pseudo-localization-netflix-12fff76fbcbe
+[generated languages config]: #generated-languages
+
 ## Use without React
 
 If you need to use Vocab outside of React, you can access the returned Vocab file directly. You'll then be responsible for when to load translations and how to update on translation load.
@@ -285,6 +432,7 @@ Vocab can be used to synchronize your translations with translations from a remo
 
 ```bash
 $ vocab push --branch my-branch
+$ vocab push --branch my-branch --delete-unused-keys
 $ vocab pull --branch my-branch
 ```
 

package/dist/declarations/src/phrase-api.d.ts

@@ -1,7 +1,10 @@
 import { TranslationsByKey } from './../../types/src/index';
 import type { TranslationsByLanguage } from '@vocab/types';
 import fetch from 'node-fetch';
-export declare function callPhrase(relativePath: string, options?: Parameters<typeof fetch>[1]): Promise<any>;
+export declare function callPhrase<T = any>(relativePath: string, options?: Parameters<typeof fetch>[1]): Promise<T>;
 export declare function pullAllTranslations(branch: string): Promise<TranslationsByLanguage>;
-export declare function pushTranslationsByLocale(contents: TranslationsByKey, locale: string, branch: string): Promise<void>;
+export declare function pushTranslationsByLocale(contents: TranslationsByKey, locale: string, branch: string): Promise<{
+    uploadId: string;
+}>;
+export declare function deleteUnusedKeys(uploadId: string, locale: string, branch: string): Promise<void>;
 export declare function ensureBranch(branch: string): Promise<void>;

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

@@ -1,6 +1,7 @@
 import type { UserConfig } from '@vocab/types';
 interface PullOptions {
     branch?: string;
+    deleteUnusedKeys?: boolean;
 }
 export declare function pull({ branch }: PullOptions, config: UserConfig): Promise<void>;
 export {};

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

@@ -1,9 +1,10 @@
 import { UserConfig } from '@vocab/types';
 interface PushOptions {
     branch: string;
+    deleteUnusedKeys?: boolean;
 }
 /**
  * Uploading to the Phrase API for each language. Adding a unique namespace to each key using file path they key came from
  */
-export declare function push({ branch }: PushOptions, config: UserConfig): Promise<void>;
+export declare function push({ branch, deleteUnusedKeys }: PushOptions, config: UserConfig): Promise<void>;
 export {};

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

@@ -44,14 +44,14 @@ function _callPhrase(path, options = {}) {
   }).then(async response => {
     console.log(`${path}: ${response.status} - ${response.statusText}`);
     console.log(`Rate Limit: ${response.headers.get('X-Rate-Limit-Remaining')} of ${response.headers.get('X-Rate-Limit-Limit')} remaining. (${response.headers.get('X-Rate-Limit-Reset')} seconds remaining})`);
-    console.log('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
+    trace('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
     // console.log(Array.from(r.headers.entries()));
 
     try {
       var _response$headers$get;
 
       const result = await response.json();
-      console.log(`Internal Result (Length: ${result.length})\n`);
+      trace(`Internal Result (Length: ${result.length})\n`);
 
       if ((!options.method || options.method === 'GET') && (_response$headers$get = response.headers.get('Link')) !== null && _response$headers$get !== void 0 && _response$headers$get.includes('rel=next')) {
         var _response$headers$get2, _response$headers$get3;
@@ -59,10 +59,10 @@ function _callPhrase(path, options = {}) {
         const [, nextPageUrl] = (_response$headers$get2 = (_response$headers$get3 = response.headers.get('Link')) === null || _response$headers$get3 === void 0 ? void 0 : _response$headers$get3.match(/<([^>]*)>; rel=next/)) !== null && _response$headers$get2 !== void 0 ? _response$headers$get2 : [];
 
         if (!nextPageUrl) {
-          throw new Error('Cant parse next page URL');
+          throw new Error("Can't parse next page URL");
         }
 
-        console.log('Results recieved with next page: ', nextPageUrl);
+        console.log('Results received with next page: ', nextPageUrl);
         const nextPageResult = await _callPhrase(nextPageUrl, options);
         return [...result, ...nextPageResult];
       }
@@ -120,12 +120,35 @@ async function pushTranslationsByLocale(contents, locale, branch) {
   formData.append('locale_id', locale);
   formData.append('branch', branch);
   formData.append('update_translations', 'true');
-  trace('Starting to upload:', locale);
-  await callPhrase(`uploads`, {
+  log('Starting to upload:', locale, '\n');
+  const {
+    id
+  } = await callPhrase(`uploads`, {
     method: 'POST',
     body: formData
   });
+  log('Upload ID:', id, '\n');
   log('Successfully Uploaded:', locale, '\n');
+  return {
+    uploadId: id
+  };
+}
+async function deleteUnusedKeys(uploadId, locale, branch) {
+  const query = `unmentioned_in_upload:${uploadId}`;
+  const {
+    records_affected
+  } = await callPhrase('keys', {
+    method: 'DELETE',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      branch,
+      locale_id: locale,
+      q: query
+    })
+  });
+  log('Successfully deleted', records_affected, 'unused keys from branch', branch);
 }
 async function ensureBranch(branch) {
   await callPhrase(`branches`, {
@@ -137,7 +160,7 @@ async function ensureBranch(branch) {
       name: branch
     })
   });
-  trace('Created branch:', branch);
+  log('Created branch:', branch);
 }
 
 async function pull({
@@ -148,6 +171,13 @@ async function pull({
   const alternativeLanguages = core.getAltLanguages(config);
   const allPhraseTranslations = await pullAllTranslations(branch);
   trace(`Pulling translations from Phrase for languages ${config.devLanguage} and ${alternativeLanguages.join(', ')}`);
+  const phraseLanguages = Object.keys(allPhraseTranslations);
+  trace(`Found Phrase translations for languages ${phraseLanguages.join(', ')}`);
+
+  if (!phraseLanguages.includes(config.devLanguage)) {
+    throw new Error(`Phrase did not return any translations for the configured development language "${config.devLanguage}".\nPlease ensure this language is present in your Phrase project's configuration.`);
+  }
+
   const allVocabTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
     includeNodeModules: false
@@ -208,7 +238,8 @@ async function pull({
  * Uploading to the Phrase API for each language. Adding a unique namespace to each key using file path they key came from
  */
 async function push({
-  branch
+  branch,
+  deleteUnusedKeys: deleteUnusedKeys$1
 }, config) {
   const allLanguageTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
@@ -241,7 +272,13 @@ async function push({
 
   for (const language of allLanguages) {
     if (phraseTranslations[language]) {
-      await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+      const {
+        uploadId
+      } = await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+
+      if (deleteUnusedKeys$1) {
+        await deleteUnusedKeys(uploadId, language, branch);
+      }
     }
   }
 }

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

@@ -44,14 +44,14 @@ function _callPhrase(path, options = {}) {
   }).then(async response => {
     console.log(`${path}: ${response.status} - ${response.statusText}`);
     console.log(`Rate Limit: ${response.headers.get('X-Rate-Limit-Remaining')} of ${response.headers.get('X-Rate-Limit-Limit')} remaining. (${response.headers.get('X-Rate-Limit-Reset')} seconds remaining})`);
-    console.log('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
+    trace('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
     // console.log(Array.from(r.headers.entries()));
 
     try {
       var _response$headers$get;
 
       const result = await response.json();
-      console.log(`Internal Result (Length: ${result.length})\n`);
+      trace(`Internal Result (Length: ${result.length})\n`);
 
       if ((!options.method || options.method === 'GET') && (_response$headers$get = response.headers.get('Link')) !== null && _response$headers$get !== void 0 && _response$headers$get.includes('rel=next')) {
         var _response$headers$get2, _response$headers$get3;
@@ -59,10 +59,10 @@ function _callPhrase(path, options = {}) {
         const [, nextPageUrl] = (_response$headers$get2 = (_response$headers$get3 = response.headers.get('Link')) === null || _response$headers$get3 === void 0 ? void 0 : _response$headers$get3.match(/<([^>]*)>; rel=next/)) !== null && _response$headers$get2 !== void 0 ? _response$headers$get2 : [];
 
         if (!nextPageUrl) {
-          throw new Error('Cant parse next page URL');
+          throw new Error("Can't parse next page URL");
         }
 
-        console.log('Results recieved with next page: ', nextPageUrl);
+        console.log('Results received with next page: ', nextPageUrl);
         const nextPageResult = await _callPhrase(nextPageUrl, options);
         return [...result, ...nextPageResult];
       }
@@ -120,12 +120,35 @@ async function pushTranslationsByLocale(contents, locale, branch) {
   formData.append('locale_id', locale);
   formData.append('branch', branch);
   formData.append('update_translations', 'true');
-  trace('Starting to upload:', locale);
-  await callPhrase(`uploads`, {
+  log('Starting to upload:', locale, '\n');
+  const {
+    id
+  } = await callPhrase(`uploads`, {
     method: 'POST',
     body: formData
   });
+  log('Upload ID:', id, '\n');
   log('Successfully Uploaded:', locale, '\n');
+  return {
+    uploadId: id
+  };
+}
+async function deleteUnusedKeys(uploadId, locale, branch) {
+  const query = `unmentioned_in_upload:${uploadId}`;
+  const {
+    records_affected
+  } = await callPhrase('keys', {
+    method: 'DELETE',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      branch,
+      locale_id: locale,
+      q: query
+    })
+  });
+  log('Successfully deleted', records_affected, 'unused keys from branch', branch);
 }
 async function ensureBranch(branch) {
   await callPhrase(`branches`, {
@@ -137,7 +160,7 @@ async function ensureBranch(branch) {
       name: branch
     })
   });
-  trace('Created branch:', branch);
+  log('Created branch:', branch);
 }
 
 async function pull({
@@ -148,6 +171,13 @@ async function pull({
   const alternativeLanguages = core.getAltLanguages(config);
   const allPhraseTranslations = await pullAllTranslations(branch);
   trace(`Pulling translations from Phrase for languages ${config.devLanguage} and ${alternativeLanguages.join(', ')}`);
+  const phraseLanguages = Object.keys(allPhraseTranslations);
+  trace(`Found Phrase translations for languages ${phraseLanguages.join(', ')}`);
+
+  if (!phraseLanguages.includes(config.devLanguage)) {
+    throw new Error(`Phrase did not return any translations for the configured development language "${config.devLanguage}".\nPlease ensure this language is present in your Phrase project's configuration.`);
+  }
+
   const allVocabTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
     includeNodeModules: false
@@ -208,7 +238,8 @@ async function pull({
  * Uploading to the Phrase API for each language. Adding a unique namespace to each key using file path they key came from
  */
 async function push({
-  branch
+  branch,
+  deleteUnusedKeys: deleteUnusedKeys$1
 }, config) {
   const allLanguageTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
@@ -241,7 +272,13 @@ async function push({
 
   for (const language of allLanguages) {
     if (phraseTranslations[language]) {
-      await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+      const {
+        uploadId
+      } = await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+
+      if (deleteUnusedKeys$1) {
+        await deleteUnusedKeys(uploadId, language, branch);
+      }
     }
   }
 }

package/dist/vocab-phrase.esm.js

@@ -32,14 +32,14 @@ function _callPhrase(path, options = {}) {
   }).then(async response => {
     console.log(`${path}: ${response.status} - ${response.statusText}`);
     console.log(`Rate Limit: ${response.headers.get('X-Rate-Limit-Remaining')} of ${response.headers.get('X-Rate-Limit-Limit')} remaining. (${response.headers.get('X-Rate-Limit-Reset')} seconds remaining})`);
-    console.log('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
+    trace('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
     // console.log(Array.from(r.headers.entries()));
 
     try {
       var _response$headers$get;
 
       const result = await response.json();
-      console.log(`Internal Result (Length: ${result.length})\n`);
+      trace(`Internal Result (Length: ${result.length})\n`);
 
       if ((!options.method || options.method === 'GET') && (_response$headers$get = response.headers.get('Link')) !== null && _response$headers$get !== void 0 && _response$headers$get.includes('rel=next')) {
         var _response$headers$get2, _response$headers$get3;
@@ -47,10 +47,10 @@ function _callPhrase(path, options = {}) {
         const [, nextPageUrl] = (_response$headers$get2 = (_response$headers$get3 = response.headers.get('Link')) === null || _response$headers$get3 === void 0 ? void 0 : _response$headers$get3.match(/<([^>]*)>; rel=next/)) !== null && _response$headers$get2 !== void 0 ? _response$headers$get2 : [];
 
         if (!nextPageUrl) {
-          throw new Error('Cant parse next page URL');
+          throw new Error("Can't parse next page URL");
         }
 
-        console.log('Results recieved with next page: ', nextPageUrl);
+        console.log('Results received with next page: ', nextPageUrl);
         const nextPageResult = await _callPhrase(nextPageUrl, options);
         return [...result, ...nextPageResult];
       }
@@ -108,12 +108,35 @@ async function pushTranslationsByLocale(contents, locale, branch) {
   formData.append('locale_id', locale);
   formData.append('branch', branch);
   formData.append('update_translations', 'true');
-  trace('Starting to upload:', locale);
-  await callPhrase(`uploads`, {
+  log('Starting to upload:', locale, '\n');
+  const {
+    id
+  } = await callPhrase(`uploads`, {
     method: 'POST',
     body: formData
   });
+  log('Upload ID:', id, '\n');
   log('Successfully Uploaded:', locale, '\n');
+  return {
+    uploadId: id
+  };
+}
+async function deleteUnusedKeys(uploadId, locale, branch) {
+  const query = `unmentioned_in_upload:${uploadId}`;
+  const {
+    records_affected
+  } = await callPhrase('keys', {
+    method: 'DELETE',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      branch,
+      locale_id: locale,
+      q: query
+    })
+  });
+  log('Successfully deleted', records_affected, 'unused keys from branch', branch);
 }
 async function ensureBranch(branch) {
   await callPhrase(`branches`, {
@@ -125,7 +148,7 @@ async function ensureBranch(branch) {
       name: branch
     })
   });
-  trace('Created branch:', branch);
+  log('Created branch:', branch);
 }
 
 async function pull({
@@ -136,6 +159,13 @@ async function pull({
   const alternativeLanguages = getAltLanguages(config);
   const allPhraseTranslations = await pullAllTranslations(branch);
   trace(`Pulling translations from Phrase for languages ${config.devLanguage} and ${alternativeLanguages.join(', ')}`);
+  const phraseLanguages = Object.keys(allPhraseTranslations);
+  trace(`Found Phrase translations for languages ${phraseLanguages.join(', ')}`);
+
+  if (!phraseLanguages.includes(config.devLanguage)) {
+    throw new Error(`Phrase did not return any translations for the configured development language "${config.devLanguage}".\nPlease ensure this language is present in your Phrase project's configuration.`);
+  }
+
   const allVocabTranslations = await loadAllTranslations({
     fallbacks: 'none',
     includeNodeModules: false
@@ -196,7 +226,8 @@ async function pull({
  * Uploading to the Phrase API for each language. Adding a unique namespace to each key using file path they key came from
  */
 async function push({
-  branch
+  branch,
+  deleteUnusedKeys: deleteUnusedKeys$1
 }, config) {
   const allLanguageTranslations = await loadAllTranslations({
     fallbacks: 'none',
@@ -229,7 +260,13 @@ async function push({
 
   for (const language of allLanguages) {
     if (phraseTranslations[language]) {
-      await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+      const {
+        uploadId
+      } = await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+
+      if (deleteUnusedKeys$1) {
+        await deleteUnusedKeys(uploadId, language, branch);
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocab/phrase",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "main": "dist/vocab-phrase.cjs.js",
   "module": "dist/vocab-phrase.esm.js",
   "author": "SEEK",

package/src/phrase-api.ts

@@ -31,14 +31,14 @@ function _callPhrase(path: string, options: Parameters<typeof fetch>[1] = {}) {
         'X-Rate-Limit-Reset',
       )} seconds remaining})`,
     );
-    console.log('\nLink:', response.headers.get('Link'), '\n');
+    trace('\nLink:', response.headers.get('Link'), '\n');
     // Print All Headers:
     // console.log(Array.from(r.headers.entries()));
 
     try {
       const result = await response.json();
 
-      console.log(`Internal Result (Length: ${result.length})\n`);
+      trace(`Internal Result (Length: ${result.length})\n`);
 
       if (
         (!options.method || options.method === 'GET') &&
@@ -48,10 +48,10 @@ function _callPhrase(path: string, options: Parameters<typeof fetch>[1] = {}) {
           response.headers.get('Link')?.match(/<([^>]*)>; rel=next/) ?? [];
 
         if (!nextPageUrl) {
-          throw new Error('Cant parse next page URL');
+          throw new Error("Can't parse next page URL");
         }
 
-        console.log('Results recieved with next page: ', nextPageUrl);
+        console.log('Results received with next page: ', nextPageUrl);
 
         const nextPageResult = (await _callPhrase(nextPageUrl, options)) as any;
 
@@ -66,10 +66,10 @@ function _callPhrase(path: string, options: Parameters<typeof fetch>[1] = {}) {
   });
 }
 
-export async function callPhrase(
+export async function callPhrase<T = any>(
   relativePath: string,
   options: Parameters<typeof fetch>[1] = {},
-) {
+): Promise<T> {
   const projectId = process.env.PHRASE_PROJECT_ID;
 
   if (!projectId) {
@@ -94,18 +94,23 @@ export async function callPhrase(
 export async function pullAllTranslations(
   branch: string,
 ): Promise<TranslationsByLanguage> {
-  const phraseResult: Array<{
-    key: { name: string };
-    locale: { code: string };
-    content: string;
-  }> = await callPhrase(`translations?branch=${branch}&per_page=100`);
+  const phraseResult = await callPhrase<
+    Array<{
+      key: { name: string };
+      locale: { code: string };
+      content: string;
+    }>
+  >(`translations?branch=${branch}&per_page=100`);
+
   const translations: TranslationsByLanguage = {};
+
   for (const r of phraseResult) {
     if (!translations[r.locale.code]) {
       translations[r.locale.code] = {};
     }
     translations[r.locale.code][r.key.name] = { message: r.content };
   }
+
   return translations;
 }
 
@@ -126,13 +131,41 @@ export async function pushTranslationsByLocale(
   formData.append('branch', branch);
   formData.append('update_translations', 'true');
 
-  trace('Starting to upload:', locale);
+  log('Starting to upload:', locale, '\n');
 
-  await callPhrase(`uploads`, {
+  const { id } = await callPhrase<{ id: string }>(`uploads`, {
     method: 'POST',
     body: formData,
   });
+  log('Upload ID:', id, '\n');
   log('Successfully Uploaded:', locale, '\n');
+
+  return { uploadId: id };
+}
+
+export async function deleteUnusedKeys(
+  uploadId: string,
+  locale: string,
+  branch: string,
+) {
+  const query = `unmentioned_in_upload:${uploadId}`;
+  const { records_affected } = await callPhrase<{ records_affected: number }>(
+    'keys',
+    {
+      method: 'DELETE',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ branch, locale_id: locale, q: query }),
+    },
+  );
+
+  log(
+    'Successfully deleted',
+    records_affected,
+    'unused keys from branch',
+    branch,
+  );
 }
 
 export async function ensureBranch(branch: string) {
@@ -143,5 +176,6 @@ export async function ensureBranch(branch: string) {
     },
     body: JSON.stringify({ name: branch }),
   });
-  trace('Created branch:', branch);
+
+  log('Created branch:', branch);
 }

package/src/pull-translations.test.ts

@@ -2,7 +2,7 @@ import path from 'path';
 import { pull } from './pull-translations';
 import { pullAllTranslations } from './phrase-api';
 import { writeFile } from './file';
-import { LanguageTarget } from '@vocab/types';
+import { GeneratedLanguageTarget, LanguageTarget } from '@vocab/types';
 
 jest.mock('./file', () => ({
   writeFile: jest.fn(() => Promise.resolve),
@@ -14,12 +14,17 @@ jest.mock('./phrase-api', () => ({
   pullAllTranslations: jest.fn(() => Promise.resolve({ en: {}, fr: {} })),
 }));
 
-function runPhrase(options: { languages: LanguageTarget[] }) {
+const devLanguage = 'en';
+
+function runPhrase(options: {
+  languages: LanguageTarget[];
+  generatedLanguages: GeneratedLanguageTarget[];
+}) {
   return pull(
     { branch: 'tester' },
     {
       ...options,
-      devLanguage: 'en',
+      devLanguage,
       projectRoot: path.resolve(__dirname, '..', '..', '..', 'fixtures/phrase'),
     },
   );
@@ -28,121 +33,182 @@ function runPhrase(options: { languages: LanguageTarget[] }) {
 describe('pull translations', () => {
   describe('when pulling translations for languages that already have translations', () => {
     beforeEach(() => {
-      (pullAllTranslations as jest.Mock).mockClear();
-      (writeFile as jest.Mock).mockClear();
-    });
-    (pullAllTranslations as jest.Mock).mockImplementation(() =>
-      Promise.resolve({
-        en: {
-          'hello.mytranslations': {
-            message: 'Hi there',
+      jest.mocked(pullAllTranslations).mockClear();
+      jest.mocked(writeFile).mockClear();
+      jest.mocked(pullAllTranslations).mockImplementation(() =>
+        Promise.resolve({
+          en: {
+            'hello.mytranslations': {
+              message: 'Hi there',
+            },
           },
-        },
-        fr: {
-          'hello.mytranslations': {
-            message: 'merci',
+          fr: {
+            'hello.mytranslations': {
+              message: 'merci',
+            },
           },
-        },
-      }),
-    );
+        }),
+      );
+    });
 
     const options = {
       languages: [{ name: 'en' }, { name: 'fr' }],
+      generatedLanguages: [
+        {
+          name: 'generatedLanguage',
+          extends: 'en',
+          generator: {
+            transformMessage: (message: string) => `[${message}]`,
+          },
+        },
+      ],
     };
 
     it('should resolve', async () => {
       await expect(runPhrase(options)).resolves.toBeUndefined();
 
-      expect(writeFile as jest.Mock).toHaveBeenCalledTimes(2);
+      expect(jest.mocked(writeFile)).toHaveBeenCalledTimes(2);
     });
 
     it('should update keys', async () => {
       await expect(runPhrase(options)).resolves.toBeUndefined();
 
       expect(
-        (writeFile as jest.Mock).mock.calls.map(
-          ([_filePath, contents]: [string, string]) => JSON.parse(contents),
-        ),
+        jest
+          .mocked(writeFile)
+          .mock.calls.map(([_filePath, contents]) =>
+            JSON.parse(contents as string),
+          ),
       ).toMatchInlineSnapshot(`
-      Array [
-        Object {
-          "hello": Object {
-            "message": "Hi there",
+        [
+          {
+            "hello": {
+              "message": "Hi there",
+            },
+            "world": {
+              "message": "world",
+            },
           },
-          "world": Object {
-            "message": "world",
+          {
+            "hello": {
+              "message": "merci",
+            },
+            "world": {
+              "message": "monde",
+            },
           },
-        },
-        Object {
-          "hello": Object {
-            "message": "merci",
-          },
-          "world": Object {
-            "message": "monde",
-          },
-        },
-      ]
-    `);
+        ]
+      `);
     });
   });
 
   describe('when pulling translations and some languages do not have any translations', () => {
     beforeEach(() => {
-      (pullAllTranslations as jest.Mock).mockClear();
-      (writeFile as jest.Mock).mockClear();
-    });
-    (pullAllTranslations as jest.Mock).mockImplementation(() =>
-      Promise.resolve({
-        en: {
-          'hello.mytranslations': {
-            message: 'Hi there',
+      jest.mocked(pullAllTranslations).mockClear();
+      jest.mocked(writeFile).mockClear();
+      jest.mocked(pullAllTranslations).mockImplementation(() =>
+        Promise.resolve({
+          en: {
+            'hello.mytranslations': {
+              message: 'Hi there',
+            },
           },
-        },
-        fr: {
-          'hello.mytranslations': {
-            message: 'merci',
+          fr: {
+            'hello.mytranslations': {
+              message: 'merci',
+            },
           },
-        },
-      }),
-    );
+        }),
+      );
+    });
 
     const options = {
       languages: [{ name: 'en' }, { name: 'fr' }, { name: 'ja' }],
+      generatedLanguages: [
+        {
+          name: 'generatedLanguage',
+          extends: 'en',
+          generator: {
+            transformMessage: (message: string) => `[${message}]`,
+          },
+        },
+      ],
     };
 
     it('should resolve', async () => {
       await expect(runPhrase(options)).resolves.toBeUndefined();
 
-      expect(writeFile as jest.Mock).toHaveBeenCalledTimes(2);
+      expect(jest.mocked(writeFile)).toHaveBeenCalledTimes(2);
     });
 
     it('should update keys', async () => {
       await expect(runPhrase(options)).resolves.toBeUndefined();
 
       expect(
-        (writeFile as jest.Mock).mock.calls.map(
-          ([_filePath, contents]: [string, string]) => JSON.parse(contents),
-        ),
+        jest
+          .mocked(writeFile)
+          .mock.calls.map(([_filePath, contents]) =>
+            JSON.parse(contents as string),
+          ),
       ).toMatchInlineSnapshot(`
-      Array [
-        Object {
-          "hello": Object {
-            "message": "Hi there",
+        [
+          {
+            "hello": {
+              "message": "Hi there",
+            },
+            "world": {
+              "message": "world",
+            },
           },
-          "world": Object {
-            "message": "world",
+          {
+            "hello": {
+              "message": "merci",
+            },
+            "world": {
+              "message": "monde",
+            },
           },
-        },
-        Object {
-          "hello": Object {
-            "message": "merci",
+        ]
+      `);
+    });
+  });
+
+  describe('when pulling translations and the project has not configured translations for the dev language', () => {
+    beforeEach(() => {
+      jest.mocked(pullAllTranslations).mockClear();
+      jest.mocked(writeFile).mockClear();
+      jest.mocked(pullAllTranslations).mockImplementation(() =>
+        Promise.resolve({
+          fr: {
+            'hello.mytranslations': {
+              message: 'merci',
+            },
           },
-          "world": Object {
-            "message": "monde",
+        }),
+      );
+    });
+
+    const options = {
+      languages: [{ name: 'en' }, { name: 'fr' }],
+      generatedLanguages: [
+        {
+          name: 'generatedLanguage',
+          extends: 'en',
+          generator: {
+            transformMessage: (message: string) => `[${message}]`,
           },
         },
-      ]
-    `);
+      ],
+    };
+
+    it('should throw an error', async () => {
+      await expect(runPhrase(options)).rejects.toThrow(
+        new Error(
+          `Phrase did not return any translations for the configured development language "en".\nPlease ensure this language is present in your Phrase project's configuration.`,
+        ),
+      );
+
+      expect(jest.mocked(writeFile)).toHaveBeenCalledTimes(0);
     });
   });
 });

package/src/pull-translations.ts

@@ -14,6 +14,7 @@ import { trace } from './logger';
 
 interface PullOptions {
   branch?: string;
+  deleteUnusedKeys?: boolean;
 }
 
 export async function pull(
@@ -30,6 +31,17 @@ export async function pull(
     } and ${alternativeLanguages.join(', ')}`,
   );
 
+  const phraseLanguages = Object.keys(allPhraseTranslations);
+  trace(
+    `Found Phrase translations for languages ${phraseLanguages.join(', ')}`,
+  );
+
+  if (!phraseLanguages.includes(config.devLanguage)) {
+    throw new Error(
+      `Phrase did not return any translations for the configured development language "${config.devLanguage}".\nPlease ensure this language is present in your Phrase project's configuration.`,
+    );
+  }
+
   const allVocabTranslations = await loadAllTranslations(
     { fallbacks: 'none', includeNodeModules: false },
     config,

package/src/push-translations.test.ts

@@ -1,6 +1,6 @@
 import path from 'path';
 import { push } from './push-translations';
-import { pushTranslationsByLocale } from './phrase-api';
+import { pushTranslationsByLocale, deleteUnusedKeys } from './phrase-api';
 import { writeFile } from './file';
 
 jest.mock('./file', () => ({
@@ -11,55 +11,158 @@ jest.mock('./file', () => ({
 jest.mock('./phrase-api', () => ({
   ensureBranch: jest.fn(() => Promise.resolve()),
   pushTranslationsByLocale: jest.fn(() => Promise.resolve({ en: {}, fr: {} })),
+  deleteUnusedKeys: jest.fn(() => Promise.resolve()),
 }));
 
-function runPhrase() {
+const uploadId = '1234';
+
+function runPhrase(config: { deleteUnusedKeys: boolean }) {
   return push(
-    { branch: 'tester' },
+    { branch: 'tester', deleteUnusedKeys: config.deleteUnusedKeys },
     {
       devLanguage: 'en',
       languages: [{ name: 'en' }, { name: 'fr' }],
+      generatedLanguages: [
+        {
+          name: 'generatedLanguage',
+          extends: 'en',
+          generator: {
+            transformMessage: (message: string) => `[${message}]`,
+          },
+        },
+      ],
       projectRoot: path.resolve(__dirname, '..', '..', '..', 'fixtures/phrase'),
     },
   );
 }
 
 describe('push', () => {
-  beforeEach(() => {
-    (pushTranslationsByLocale as jest.Mock).mockClear();
-    (writeFile as jest.Mock).mockClear();
-  });
-  it('should resolve', async () => {
-    await expect(runPhrase()).resolves.toBeUndefined();
+  describe('when deleteUnusedKeys is false', () => {
+    const config = { deleteUnusedKeys: false };
 
-    expect(pushTranslationsByLocale as jest.Mock).toHaveBeenCalledTimes(2);
-  });
-  it('should update keys', async () => {
-    await expect(runPhrase()).resolves.toBeUndefined();
+    beforeEach(() => {
+      jest.mocked(pushTranslationsByLocale).mockClear();
+      jest.mocked(writeFile).mockClear();
+      jest.mocked(deleteUnusedKeys).mockClear();
 
-    expect(pushTranslationsByLocale as jest.Mock).toHaveBeenCalledWith(
-      {
-        'hello.mytranslations': {
-          message: 'Hello',
-        },
-        'world.mytranslations': {
-          message: 'world',
-        },
-      },
-      'en',
-      'tester',
-    );
-    expect(pushTranslationsByLocale as jest.Mock).toHaveBeenCalledWith(
-      {
-        'hello.mytranslations': {
-          message: 'Bonjour',
+      jest
+        .mocked(pushTranslationsByLocale)
+        .mockImplementation(() => Promise.resolve({ uploadId }));
+    });
+
+    it('should resolve', async () => {
+      await expect(runPhrase(config)).resolves.toBeUndefined();
+
+      expect(jest.mocked(pushTranslationsByLocale)).toHaveBeenCalledTimes(2);
+    });
+
+    it('should update keys', async () => {
+      await expect(runPhrase(config)).resolves.toBeUndefined();
+
+      expect(jest.mocked(pushTranslationsByLocale)).toHaveBeenCalledWith(
+        {
+          'hello.mytranslations': {
+            message: 'Hello',
+          },
+          'world.mytranslations': {
+            message: 'world',
+          },
         },
-        'world.mytranslations': {
-          message: 'monde',
+        'en',
+        'tester',
+      );
+
+      expect(jest.mocked(pushTranslationsByLocale)).toHaveBeenCalledWith(
+        {
+          'hello.mytranslations': {
+            message: 'Bonjour',
+          },
+          'world.mytranslations': {
+            message: 'monde',
+          },
         },
-      },
-      'fr',
-      'tester',
-    );
+        'fr',
+        'tester',
+      );
+    });
+
+    it('should not delete unused keys', () => {
+      expect(deleteUnusedKeys).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('when deleteUnusedKeys is true', () => {
+    const config = { deleteUnusedKeys: true };
+
+    beforeEach(() => {
+      jest.mocked(pushTranslationsByLocale).mockClear();
+      jest.mocked(writeFile).mockClear();
+      jest.mocked(deleteUnusedKeys).mockClear();
+    });
+
+    describe('and the upload succeeds', () => {
+      beforeEach(() => {
+        jest
+          .mocked(pushTranslationsByLocale)
+          .mockImplementation(() => Promise.resolve({ uploadId }));
+      });
+
+      it('should resolve', async () => {
+        await expect(runPhrase(config)).resolves.toBeUndefined();
+
+        expect(jest.mocked(pushTranslationsByLocale)).toHaveBeenCalledTimes(2);
+      });
+
+      it('should update keys', async () => {
+        await expect(runPhrase(config)).resolves.toBeUndefined();
+
+        expect(jest.mocked(pushTranslationsByLocale)).toHaveBeenCalledWith(
+          {
+            'hello.mytranslations': {
+              message: 'Hello',
+            },
+            'world.mytranslations': {
+              message: 'world',
+            },
+          },
+          'en',
+          'tester',
+        );
+
+        expect(jest.mocked(pushTranslationsByLocale)).toHaveBeenCalledWith(
+          {
+            'hello.mytranslations': {
+              message: 'Bonjour',
+            },
+            'world.mytranslations': {
+              message: 'monde',
+            },
+          },
+          'fr',
+          'tester',
+        );
+      });
+
+      it('should delete unused keys', async () => {
+        await expect(runPhrase(config)).resolves.toBeUndefined();
+
+        expect(deleteUnusedKeys).toHaveBeenCalledWith(uploadId, 'en', 'tester');
+        expect(deleteUnusedKeys).toHaveBeenCalledWith(uploadId, 'fr', 'tester');
+      });
+    });
+
+    describe('and the upload fails', () => {
+      beforeEach(() => {
+        jest
+          .mocked(pushTranslationsByLocale)
+          .mockImplementation(() => Promise.reject('Upload failed'));
+      });
+
+      it('should not delete unused keys', async () => {
+        await expect(runPhrase(config)).rejects.toBe('Upload failed');
+
+        expect(deleteUnusedKeys).not.toHaveBeenCalled();
+      });
+    });
   });
 });

package/src/push-translations.ts

@@ -1,18 +1,26 @@
 import { TranslationsByLanguage } from './../../types/src/index';
 
-import { ensureBranch, pushTranslationsByLocale } from './phrase-api';
+import {
+  ensureBranch,
+  pushTranslationsByLocale,
+  deleteUnusedKeys as phraseDeleteUnusedKeys,
+} from './phrase-api';
 import { trace } from './logger';
 import { loadAllTranslations, getUniqueKey } from '@vocab/core';
 import { UserConfig } from '@vocab/types';
 
 interface PushOptions {
   branch: string;
+  deleteUnusedKeys?: boolean;
 }
 
 /**
  * Uploading to the Phrase API for each language. Adding a unique namespace to each key using file path they key came from
  */
-export async function push({ branch }: PushOptions, config: UserConfig) {
+export async function push(
+  { branch, deleteUnusedKeys }: PushOptions,
+  config: UserConfig,
+) {
   const allLanguageTranslations = await loadAllTranslations(
     { fallbacks: 'none', includeNodeModules: false },
     config,
@@ -45,11 +53,15 @@ export async function push({ branch }: PushOptions, config: UserConfig) {
 
   for (const language of allLanguages) {
     if (phraseTranslations[language]) {
-      await pushTranslationsByLocale(
+      const { uploadId } = await pushTranslationsByLocale(
         phraseTranslations[language],
         language,
         branch,
       );
+
+      if (deleteUnusedKeys) {
+        await phraseDeleteUnusedKeys(uploadId, language, branch);
+      }
     }
   }
 }