@vocab/phrase 1.1.0 → 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/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/file.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="node" />
-import { promises as fs } from 'fs';
-export declare const mkdir: typeof fs.mkdir;
-export declare const writeFile: typeof fs.writeFile;
+/// <reference types="node" />
+import { promises as fs } from 'fs';
+export declare const mkdir: typeof fs.mkdir;
+export declare const writeFile: typeof fs.writeFile;

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

@@ -1,2 +1,2 @@
-export { pull } from './pull-translations';
-export { push } from './push-translations';
+export { pull } from './pull-translations';
+export { push } from './push-translations';

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/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<{
-    uploadId: string;
-}>;
-export declare function deleteUnusedKeys(uploadId: string, locale: string, branch: string): Promise<void>;
-export declare function ensureBranch(branch: string): Promise<void>;
+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 pushTranslations(translationsByLanguage: TranslationsByLanguage, { devLanguage, branch }: {
+    devLanguage: string;
+    branch: string;
+}): Promise<{
+    uploadId: string;
+}>;
+export declare function deleteUnusedKeys(uploadId: string, branch: string): Promise<void>;
+export declare function ensureBranch(branch: string): Promise<void>;

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

@@ -1,7 +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 {};
+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,10 +1,11 @@
-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, deleteUnusedKeys }: PushOptions, config: UserConfig): Promise<void>;
-export {};
+import { UserConfig } from '@vocab/types';
+interface PushOptions {
+    branch: string;
+    deleteUnusedKeys?: boolean;
+}
+/**
+ * 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 }; }
 
@@ -21,20 +22,56 @@ var debug__default = /*#__PURE__*/_interopDefault(debug);
 const mkdir = fs.promises.mkdir;
 const writeFile = fs.promises.writeFile;
 
-const trace = debug__default['default'](`vocab:phrase`);
+const trace = debug__default["default"](`vocab:phrase`);
 const log = (...params) => {
   // eslint-disable-next-line no-console
-  console.log(chalk__default['default'].yellow('Vocab'), ...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;
-
   if (!phraseApiToken) {
     throw new Error('Missing PHRASE_API_TOKEN');
   }
-
-  return fetch__default['default'](path, { ...options,
+  return fetch__default["default"](path, {
+    ...options,
     headers: {
       Authorization: `token ${phraseApiToken}`,
       // Provide identification via User Agent as requested in https://developers.phrase.com/api/#overview--identification-via-user-agent
@@ -43,30 +80,26 @@ 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})`);
-    trace('\nLink:', response.headers.get('Link'), '\n'); // Print All Headers:
+    const secondsUntilLimitReset = Math.ceil(Number.parseFloat(response.headers.get('X-Rate-Limit-Reset') || '0') - Date.now() / 1000);
+    console.log(`Rate Limit: ${response.headers.get('X-Rate-Limit-Remaining')} of ${response.headers.get('X-Rate-Limit-Limit')} remaining. (${secondsUntilLimitReset} seconds remaining)`);
+    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();
       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;
-
         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("Can't parse next page URL");
         }
-
         console.log('Results received with next page: ', nextPageUrl);
         const nextPageResult = await _callPhrase(nextPageUrl, options);
         return [...result, ...nextPageResult];
       }
-
       return result;
     } catch (e) {
       console.error('Unable to parse response as JSON', e);
@@ -74,19 +107,15 @@ function _callPhrase(path, options = {}) {
     }
   });
 }
-
 async function callPhrase(relativePath, options = {}) {
   const projectId = process.env.PHRASE_PROJECT_ID;
-
   if (!projectId) {
     throw new Error('Missing PHRASE_PROJECT_ID');
   }
-
   return _callPhrase(`https://api.phrase.com/v2/projects/${projectId}/${relativePath}`, options).then(result => {
     if (Array.isArray(result)) {
       console.log('Result length:', result.length);
     }
-
     return result;
   }).catch(error => {
     console.error(`Error calling phrase for ${relativePath}:`, error);
@@ -96,44 +125,62 @@ async function callPhrase(relativePath, options = {}) {
 async function pullAllTranslations(branch) {
   const phraseResult = await callPhrase(`translations?branch=${branch}&per_page=100`);
   const translations = {};
-
   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;
 }
-async function pushTranslationsByLocale(contents, locale, branch) {
-  const formData = new FormData__default['default']();
-  const fileContents = Buffer.from(JSON.stringify(contents));
+async function pushTranslations(translationsByLanguage, {
+  devLanguage,
+  branch
+}) {
+  const formData = new FormData__default["default"]();
+  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 +191,6 @@ async function deleteUnusedKeys(uploadId, locale, branch) {
     },
     body: JSON.stringify({
       branch,
-      locale_id: locale,
       q: query
     })
   });
@@ -173,59 +219,56 @@ async function pull({
   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
+    includeNodeModules: false,
+    withTags: true
   }, config);
-
   for (const loadedTranslation of allVocabTranslations) {
     const devTranslations = loadedTranslation.languages[config.devLanguage];
-
     if (!devTranslations) {
       throw new Error('No dev language translations loaded');
     }
-
-    const defaultValues = { ...devTranslations
+    const defaultValues = {
+      ...devTranslations
     };
     const localKeys = Object.keys(defaultValues);
-
     for (const key of localKeys) {
-      defaultValues[key] = { ...defaultValues[key],
+      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`);
-
     for (const alternativeLanguage of alternativeLanguages) {
       if (alternativeLanguage in allPhraseTranslations) {
-        const altTranslations = { ...loadedTranslation.languages[alternativeLanguage]
+        const altTranslations = {
+          ...loadedTranslation.languages[alternativeLanguage]
         };
         const phraseAltTranslations = allPhraseTranslations[alternativeLanguage];
-
         for (const key of localKeys) {
           var _phraseAltTranslation;
-
           const phraseKey = core.getUniqueKey(key, loadedTranslation.namespace);
           const phraseTranslationMessage = (_phraseAltTranslation = phraseAltTranslations[phraseKey]) === null || _phraseAltTranslation === void 0 ? void 0 : _phraseAltTranslation.message;
-
           if (!phraseTranslationMessage) {
             trace(`Missing translation. No translation for key ${key} in phrase as ${phraseKey} in language ${alternativeLanguage}.`);
             continue;
           }
-
-          altTranslations[key] = { ...altTranslations[key],
+          altTranslations[key] = {
+            ...altTranslations[key],
             message: phraseTranslationMessage
           };
         }
-
         const altTranslationFilePath = core.getAltLanguageFilePath(loadedTranslation.filePath, alternativeLanguage);
-        await mkdir(path__default['default'].dirname(altTranslationFilePath), {
+        await mkdir(path__default["default"].dirname(altTranslationFilePath), {
           recursive: true
         });
         await writeFile(altTranslationFilePath, `${JSON.stringify(altTranslations, null, 2)}\n`);
@@ -235,7 +278,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,43 +287,49 @@ 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);
   await ensureBranch(branch);
   trace(`Pushing translations to phrase for languages ${allLanguages.join(', ')}`);
   const phraseTranslations = {};
-
   for (const loadedTranslation of allLanguageTranslations) {
     for (const language of allLanguages) {
       const localTranslations = loadedTranslation.languages[language];
-
       if (!localTranslations) {
         continue;
       }
-
       if (!phraseTranslations[language]) {
         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);
-
-      if (deleteUnusedKeys$1) {
-        await deleteUnusedKeys(uploadId, language, branch);
-      }
-    }
+  const {
+    uploadId
+  } = await pushTranslations(phraseTranslations, {
+    devLanguage: config.devLanguage,
+    branch
+  });
+  if (deleteUnusedKeys$1) {
+    await deleteUnusedKeys(uploadId, branch);
   }
 }