@vocab/phrase 1.1.0 → 1.2.0

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/csv.d.ts

@@ -0,0 +1,10 @@
+import type { TranslationsByLanguage } from '@vocab/types';
+export declare function translationsToCsv(translations: TranslationsByLanguage, devLanguage: string): {
+    csvString: string;
+    localeMapping: {
+        [k: string]: number;
+    };
+    keyIndex: number;
+    commentIndex: number;
+    tagColumn: number;
+};

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

@@ -1,10 +1,12 @@
-import { TranslationsByKey } from './../../types/src/index';
 import type { TranslationsByLanguage } from '@vocab/types';
 import fetch from 'node-fetch';
 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<{
+export declare function pushTranslations(translationsByLanguage: TranslationsByLanguage, { devLanguage, branch }: {
+    devLanguage: string;
+    branch: string;
+}): Promise<{
     uploadId: string;
 }>;
-export declare function deleteUnusedKeys(uploadId: string, locale: string, branch: string): Promise<void>;
+export declare function deleteUnusedKeys(uploadId: string, branch: string): Promise<void>;
 export declare function ensureBranch(branch: string): Promise<void>;

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

@@ -4,7 +4,8 @@ interface PushOptions {
     deleteUnusedKeys?: boolean;
 }
 /**
- * Uploading to the Phrase API for each language. Adding a unique namespace to each key using file path they key came from
+ * Uploads translations to the Phrase API for each language.
+ * A unique namespace is appended to each key using the file path the key came from.
  */
 export declare function push({ branch, deleteUnusedKeys }: PushOptions, config: UserConfig): Promise<void>;
 export {};

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

@@ -9,6 +9,7 @@ var FormData = require('form-data');
 var fetch = require('node-fetch');
 var chalk = require('chalk');
 var debug = require('debug');
+var sync = require('csv-stringify/sync');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
 
@@ -27,6 +28,44 @@ const log = (...params) => {
   console.log(chalk__default['default'].yellow('Vocab'), ...params);
 };
 
+function translationsToCsv(translations, devLanguage) {
+  const languages = Object.keys(translations);
+  const altLanguages = languages.filter(language => language !== devLanguage); // Ensure languages are ordered for locale mapping
+
+  const orderedLanguages = [devLanguage, ...altLanguages];
+  const devLanguageTranslations = translations[devLanguage];
+  const csv = Object.entries(devLanguageTranslations).map(([key, {
+    message,
+    description,
+    tags
+  }]) => {
+    const altTranslationMessages = altLanguages.map(language => {
+      var _translations$languag, _translations$languag2;
+
+      return (_translations$languag = translations[language]) === null || _translations$languag === void 0 ? void 0 : (_translations$languag2 = _translations$languag[key]) === null || _translations$languag2 === void 0 ? void 0 : _translations$languag2.message;
+    });
+    return [message, ...altTranslationMessages, key, description, tags === null || tags === void 0 ? void 0 : tags.join(',')];
+  });
+  const csvString = sync.stringify(csv, {
+    delimiter: ',',
+    header: false
+  }); // Column indices start at 1
+
+  const localeMapping = Object.fromEntries(orderedLanguages.map((language, index) => [language, index + 1]));
+  const keyIndex = orderedLanguages.length + 1;
+  const commentIndex = keyIndex + 1;
+  const tagColumn = commentIndex + 1;
+  return {
+    csvString,
+    localeMapping,
+    keyIndex,
+    commentIndex,
+    tagColumn
+  };
+}
+
+/* eslint-disable no-console */
+
 function _callPhrase(path, options = {}) {
   const phraseApiToken = process.env.PHRASE_API_TOKEN;
 
@@ -109,31 +148,56 @@ async function pullAllTranslations(branch) {
 
   return translations;
 }
-async function pushTranslationsByLocale(contents, locale, branch) {
+async function pushTranslations(translationsByLanguage, {
+  devLanguage,
+  branch
+}) {
   const formData = new FormData__default['default']();
-  const fileContents = Buffer.from(JSON.stringify(contents));
+  const {
+    csvString,
+    localeMapping,
+    keyIndex,
+    commentIndex,
+    tagColumn
+  } = translationsToCsv(translationsByLanguage, devLanguage);
+  const fileContents = Buffer.from(csvString);
   formData.append('file', fileContents, {
-    contentType: 'application/json',
-    filename: `${locale}.json`
+    contentType: 'text/csv',
+    filename: 'translations.csv'
   });
-  formData.append('file_format', 'json');
-  formData.append('locale_id', locale);
+  formData.append('file_format', 'csv');
   formData.append('branch', branch);
   formData.append('update_translations', 'true');
-  log('Starting to upload:', locale, '\n');
-  const {
-    id
-  } = await callPhrase(`uploads`, {
+
+  for (const [locale, index] of Object.entries(localeMapping)) {
+    formData.append(`locale_mapping[${locale}]`, index);
+  }
+
+  formData.append('format_options[key_index]', keyIndex);
+  formData.append('format_options[comment_index]', commentIndex);
+  formData.append('format_options[tag_column]', tagColumn);
+  formData.append('format_options[enable_pluralization]', 'false');
+  log('Uploading translations');
+  const result = await callPhrase(`uploads`, {
     method: 'POST',
     body: formData
   });
-  log('Upload ID:', id, '\n');
-  log('Successfully Uploaded:', locale, '\n');
+  trace('Upload result:\n', result);
+
+  if (result && 'id' in result) {
+    log('Upload ID:', result.id, '\n');
+    log('Successfully Uploaded\n');
+  } else {
+    log(`Error uploading: ${result === null || result === void 0 ? void 0 : result.message}\n`);
+    log('Response:', result);
+    throw new Error('Error uploading');
+  }
+
   return {
-    uploadId: id
+    uploadId: result.id
   };
 }
-async function deleteUnusedKeys(uploadId, locale, branch) {
+async function deleteUnusedKeys(uploadId, branch) {
   const query = `unmentioned_in_upload:${uploadId}`;
   const {
     records_affected
@@ -144,7 +208,6 @@ async function deleteUnusedKeys(uploadId, locale, branch) {
     },
     body: JSON.stringify({
       branch,
-      locale_id: locale,
       q: query
     })
   });
@@ -180,7 +243,8 @@ async function pull({
 
   const allVocabTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
-    includeNodeModules: false
+    includeNodeModules: false,
+    withTags: true
   }, config);
 
   for (const loadedTranslation of allVocabTranslations) {
@@ -198,6 +262,11 @@ async function pull({
       defaultValues[key] = { ...defaultValues[key],
         ...allPhraseTranslations[config.devLanguage][core.getUniqueKey(key, loadedTranslation.namespace)]
       };
+    } // Only write a `_meta` field if necessary
+
+
+    if (Object.keys(loadedTranslation.metadata).length > 0) {
+      defaultValues._meta = loadedTranslation.metadata;
     }
 
     await writeFile(loadedTranslation.filePath, `${JSON.stringify(defaultValues, null, 2)}\n`);
@@ -235,7 +304,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
+ * Uploads translations to the Phrase API for each language.
+ * A unique namespace is appended to each key using the file path the key came from.
  */
 async function push({
   branch,
@@ -243,7 +313,8 @@ async function push({
 }, config) {
   const allLanguageTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
-    includeNodeModules: false
+    includeNodeModules: false,
+    withTags: true
   }, config);
   trace(`Pushing translations to branch ${branch}`);
   const allLanguages = config.languages.map(v => v.name);
@@ -263,23 +334,37 @@ async function push({
         phraseTranslations[language] = {};
       }
 
+      const {
+        metadata: {
+          tags: sharedTags = []
+        }
+      } = loadedTranslation;
+
       for (const localKey of Object.keys(localTranslations)) {
         const phraseKey = core.getUniqueKey(localKey, loadedTranslation.namespace);
-        phraseTranslations[language][phraseKey] = localTranslations[localKey];
+        const {
+          tags = [],
+          ...localTranslation
+        } = localTranslations[localKey];
+
+        if (language === config.devLanguage) {
+          localTranslation.tags = [...tags, ...sharedTags];
+        }
+
+        phraseTranslations[language][phraseKey] = localTranslation;
       }
     }
   }
 
-  for (const language of allLanguages) {
-    if (phraseTranslations[language]) {
-      const {
-        uploadId
-      } = await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+  const {
+    uploadId
+  } = await pushTranslations(phraseTranslations, {
+    devLanguage: config.devLanguage,
+    branch
+  });
 
-      if (deleteUnusedKeys$1) {
-        await deleteUnusedKeys(uploadId, language, branch);
-      }
-    }
+  if (deleteUnusedKeys$1) {
+    await deleteUnusedKeys(uploadId, branch);
   }
 }
 

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

@@ -9,6 +9,7 @@ var FormData = require('form-data');
 var fetch = require('node-fetch');
 var chalk = require('chalk');
 var debug = require('debug');
+var sync = require('csv-stringify/sync');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
 
@@ -27,6 +28,44 @@ const log = (...params) => {
   console.log(chalk__default['default'].yellow('Vocab'), ...params);
 };
 
+function translationsToCsv(translations, devLanguage) {
+  const languages = Object.keys(translations);
+  const altLanguages = languages.filter(language => language !== devLanguage); // Ensure languages are ordered for locale mapping
+
+  const orderedLanguages = [devLanguage, ...altLanguages];
+  const devLanguageTranslations = translations[devLanguage];
+  const csv = Object.entries(devLanguageTranslations).map(([key, {
+    message,
+    description,
+    tags
+  }]) => {
+    const altTranslationMessages = altLanguages.map(language => {
+      var _translations$languag, _translations$languag2;
+
+      return (_translations$languag = translations[language]) === null || _translations$languag === void 0 ? void 0 : (_translations$languag2 = _translations$languag[key]) === null || _translations$languag2 === void 0 ? void 0 : _translations$languag2.message;
+    });
+    return [message, ...altTranslationMessages, key, description, tags === null || tags === void 0 ? void 0 : tags.join(',')];
+  });
+  const csvString = sync.stringify(csv, {
+    delimiter: ',',
+    header: false
+  }); // Column indices start at 1
+
+  const localeMapping = Object.fromEntries(orderedLanguages.map((language, index) => [language, index + 1]));
+  const keyIndex = orderedLanguages.length + 1;
+  const commentIndex = keyIndex + 1;
+  const tagColumn = commentIndex + 1;
+  return {
+    csvString,
+    localeMapping,
+    keyIndex,
+    commentIndex,
+    tagColumn
+  };
+}
+
+/* eslint-disable no-console */
+
 function _callPhrase(path, options = {}) {
   const phraseApiToken = process.env.PHRASE_API_TOKEN;
 
@@ -109,31 +148,56 @@ async function pullAllTranslations(branch) {
 
   return translations;
 }
-async function pushTranslationsByLocale(contents, locale, branch) {
+async function pushTranslations(translationsByLanguage, {
+  devLanguage,
+  branch
+}) {
   const formData = new FormData__default['default']();
-  const fileContents = Buffer.from(JSON.stringify(contents));
+  const {
+    csvString,
+    localeMapping,
+    keyIndex,
+    commentIndex,
+    tagColumn
+  } = translationsToCsv(translationsByLanguage, devLanguage);
+  const fileContents = Buffer.from(csvString);
   formData.append('file', fileContents, {
-    contentType: 'application/json',
-    filename: `${locale}.json`
+    contentType: 'text/csv',
+    filename: 'translations.csv'
   });
-  formData.append('file_format', 'json');
-  formData.append('locale_id', locale);
+  formData.append('file_format', 'csv');
   formData.append('branch', branch);
   formData.append('update_translations', 'true');
-  log('Starting to upload:', locale, '\n');
-  const {
-    id
-  } = await callPhrase(`uploads`, {
+
+  for (const [locale, index] of Object.entries(localeMapping)) {
+    formData.append(`locale_mapping[${locale}]`, index);
+  }
+
+  formData.append('format_options[key_index]', keyIndex);
+  formData.append('format_options[comment_index]', commentIndex);
+  formData.append('format_options[tag_column]', tagColumn);
+  formData.append('format_options[enable_pluralization]', 'false');
+  log('Uploading translations');
+  const result = await callPhrase(`uploads`, {
     method: 'POST',
     body: formData
   });
-  log('Upload ID:', id, '\n');
-  log('Successfully Uploaded:', locale, '\n');
+  trace('Upload result:\n', result);
+
+  if (result && 'id' in result) {
+    log('Upload ID:', result.id, '\n');
+    log('Successfully Uploaded\n');
+  } else {
+    log(`Error uploading: ${result === null || result === void 0 ? void 0 : result.message}\n`);
+    log('Response:', result);
+    throw new Error('Error uploading');
+  }
+
   return {
-    uploadId: id
+    uploadId: result.id
   };
 }
-async function deleteUnusedKeys(uploadId, locale, branch) {
+async function deleteUnusedKeys(uploadId, branch) {
   const query = `unmentioned_in_upload:${uploadId}`;
   const {
     records_affected
@@ -144,7 +208,6 @@ async function deleteUnusedKeys(uploadId, locale, branch) {
     },
     body: JSON.stringify({
       branch,
-      locale_id: locale,
       q: query
     })
   });
@@ -180,7 +243,8 @@ async function pull({
 
   const allVocabTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
-    includeNodeModules: false
+    includeNodeModules: false,
+    withTags: true
   }, config);
 
   for (const loadedTranslation of allVocabTranslations) {
@@ -198,6 +262,11 @@ async function pull({
       defaultValues[key] = { ...defaultValues[key],
         ...allPhraseTranslations[config.devLanguage][core.getUniqueKey(key, loadedTranslation.namespace)]
       };
+    } // Only write a `_meta` field if necessary
+
+
+    if (Object.keys(loadedTranslation.metadata).length > 0) {
+      defaultValues._meta = loadedTranslation.metadata;
     }
 
     await writeFile(loadedTranslation.filePath, `${JSON.stringify(defaultValues, null, 2)}\n`);
@@ -235,7 +304,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
+ * Uploads translations to the Phrase API for each language.
+ * A unique namespace is appended to each key using the file path the key came from.
  */
 async function push({
   branch,
@@ -243,7 +313,8 @@ async function push({
 }, config) {
   const allLanguageTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
-    includeNodeModules: false
+    includeNodeModules: false,
+    withTags: true
   }, config);
   trace(`Pushing translations to branch ${branch}`);
   const allLanguages = config.languages.map(v => v.name);
@@ -263,23 +334,37 @@ async function push({
         phraseTranslations[language] = {};
       }
 
+      const {
+        metadata: {
+          tags: sharedTags = []
+        }
+      } = loadedTranslation;
+
       for (const localKey of Object.keys(localTranslations)) {
         const phraseKey = core.getUniqueKey(localKey, loadedTranslation.namespace);
-        phraseTranslations[language][phraseKey] = localTranslations[localKey];
+        const {
+          tags = [],
+          ...localTranslation
+        } = localTranslations[localKey];
+
+        if (language === config.devLanguage) {
+          localTranslation.tags = [...tags, ...sharedTags];
+        }
+
+        phraseTranslations[language][phraseKey] = localTranslation;
       }
     }
   }
 
-  for (const language of allLanguages) {
-    if (phraseTranslations[language]) {
-      const {
-        uploadId
-      } = await pushTranslationsByLocale(phraseTranslations[language], language, branch);
+  const {
+    uploadId
+  } = await pushTranslations(phraseTranslations, {
+    devLanguage: config.devLanguage,
+    branch
+  });
 
-      if (deleteUnusedKeys$1) {
-        await deleteUnusedKeys(uploadId, language, branch);
-      }
-    }
+  if (deleteUnusedKeys$1) {
+    await deleteUnusedKeys(uploadId, branch);
   }
 }