i18nexus-cli 3.4.0 → 3.6.0

package/README.md

@@ -6,11 +6,11 @@
 
 [i18nexus](https://i18nexus.com) is a translation management web application designed for use with i18next, next-intl, and react-intl. Learn more with these quick tutorials:
 
-- [react-i18next Walkthrough](https://i18nexus.com/tutorials/react/react-i18next)
-- [react-intl Walkthrough](https://i18nexus.com/tutorials/react/react-intl)
 - [next-intl for Next.js App Router Walkthrough](https://i18nexus.com/tutorials/nextjs/next-intl)
 - [react-i18next for Next.js App Router Walkthrough](https://i18nexus.com/tutorials/nextjs/react-i18next)
 - [next-i18next for Next.js Pages Router Walkthrough](https://i18nexus.com/tutorials/nextjs/next-i18next)
+- [react-i18next Walkthrough](https://i18nexus.com/tutorials/react/react-i18next)
+- [react-intl Walkthrough](https://i18nexus.com/tutorials/react/react-intl)
 
 ## Who is this CLI meant for?
 
@@ -130,14 +130,15 @@ Translations for the string will be automatically generated and machine translat
 
 ### Options
 
-| Option                 | Required? |
-| ---------------------- | --------- |
-| `--api-key` or `-k`    | ✔  |
-| `--pat` or `-t`        | ✔  |
-| `--namespace` or `-ns` | ✔  |
-| `--key` or `-K`        | ✔  |
-| `--value` or `-v`      | ✔  |
-| `--details` or `-d`    |           |
+| Option                       | Required?     |
+| ---------------------------- | ------------- |
+| `--api-key` or `-k`          | ✔      |
+| `--pat` or `-t`              | ✔      |
+| `--key` or `-K`              | ✔      |
+| `--value` or `-v`            | ✔      |
+| `--namespace` or `-ns`       | Conditionally |
+| `--notes` or `-n`            |               |
+| `--ai-instructions` or `-ai` |               |
 
 ### Notes
 
@@ -148,7 +149,7 @@ Your project API key (Can also be set using environment variable `I18NEXUS_API_K
 A personal access token that you have generated in your i18nexus account (Can also be set using environment variable `I18NEXUS_PERSONAL_ACCESS_TOKEN`)
 
 `--namespace`
-The namespace in which to create the string
+The namespace in which to create the string. Only required if your project uses namespaces and has more than one namespace.
 
 `--key`
 The key of the string to create
@@ -156,35 +157,39 @@ The key of the string to create
 `--value`
 The value of the string to create
 
-`--details`
-The details of the string to create (optional)
+`--notes`
+Team notes about the string to create (optional)
+
+`--ai-instructions`
+Instructions or context for AI machine translator (optional)
 
 ## Updating existing strings
 
-`i18nexus update-string <namespace> <key>` or `i18nexus u <namespace> <key>`
+`i18nexus update-string <namespace:key>` or `i18nexus u <namespace:key>`
 
 ```sh
-i18nexus u common welcome_msg -v 'Welcome' -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>
+i18nexus u common:welcome_msg -v 'Welcome' -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>
 ```
 
 The above snippet will update a the value of the string with key `welcome_msg` in your `common` namespace to `Welcome`.
 
-The first 2 arguments are the namespace and the key of the string you wish to update.
+The required argument is the namespace and the key of the string you wish to update, joined with a colon (":"). If your project does not use namespaces or only has one namespace, only the key is necessary.
 
 You can then update the key, value, details, and/or namespace by using the command options:
 
 ### Options
 
-| Option                 | Required? |
-| ---------------------- | --------- |
-| `--api-key` or `-k`    | &#10004;  |
-| `--pat` or `-t`        | &#10004;  |
-| `--namespace` or `-ns` |           |
-| `--key` or `-K`        |           |
-| `--value` or `-v`      |           |
-| `--details` or `-d`    |           |
-| `--reset-confirmed`    |           |
-| `--retain-confirmed`   |           |
+| Option                       | Required? |
+| ---------------------------- | --------- |
+| `--api-key` or `-k`          | &#10004;  |
+| `--pat` or `-t`              | &#10004;  |
+| `--namespace` or `-ns`       |           |
+| `--key` or `-K`              |           |
+| `--value` or `-v`            |           |
+| `--details` or `-d`          |           |
+| `--ai-instructions` or `-ai` |           |
+| `--reset-confirmed`          |           |
+| `--retain-confirmed`         |           |
 
 ### Notes
 
@@ -203,8 +208,11 @@ The new key of the string
 `--value`
 The new value of the string
 
-`--details`
-The new details of the string
+`--notes`
+The new team notes of the string
+
+`--ai-instructions`
+Instructions or context for AI machine translator
 
 #### If you are updating the value of a string that contains translations that have been marked confirmed in i18nexus, you will be required to include one of the following options to your command:
 
@@ -216,13 +224,13 @@ Confirmed translations of this string will be retained
 
 ## Deleting strings
 
-`i18nexus delete-string <namespace> <key>` or `i18nexus d <namespace> <key>`
+`i18nexus delete-string <namespace:key>` or `i18nexus d <namespace:key>`
 
 ```sh
-i18nexus d common welcome_msg -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>
+i18nexus d common:welcome_msg -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>
 ```
 
-The above snippet will delete the string `welcome_msg` from your `common` namespace, along with its associated translations.
+The required argument is the namespace and the key of the string you wish to delete, joined with a colon (":"). If your project does not use namespaces or only has one namespace, only the key is necessary.
 
 ### Options
 
@@ -253,11 +261,12 @@ This is the equivalent of using the Import tool in the i18nexus web application.
 
 ### Options
 
-| Option              | Required? |
-| ------------------- | --------- |
-| `--api-key` or `-k` | &#10004;  |
-| `--pat` or `-t`     | &#10004;  |
-| `--overwrite`       |           |
+| Option                 | Required?     |
+| ---------------------- | ------------- |
+| `--api-key` or `-k`    | &#10004;      |
+| `--pat` or `-t`        | &#10004;      |
+| `--namespace` or `-ns` | Conditionally |
+| `--overwrite`          |               |
 
 ### Notes
 
@@ -267,6 +276,9 @@ Your project API key (Can also be set using environment variable `I18NEXUS_API_K
 `--pat`
 A personal access token that you have generated in your i18nexus account (Can also be set using environment variable `I18NEXUS_PERSONAL_ACCESS_TOKEN`)
 
+`--namespace`
+The namespace in which your strings will be imported. (Only required if your project uses namespaces and has more than one namespace)
+
 `--overwrite`
 If any keys already exist in the target namespace, overwrite the values with the imported values.
 
@@ -294,3 +306,33 @@ Your project API key (Can also be set using environment variable `I18NEXUS_API_K
 
 `--pat`
 A personal access token that you have generated in your i18nexus account (Can also be set using environment variable `I18NEXUS_PERSONAL_ACCESS_TOKEN`)
+
+## Listening for live translation updates
+
+`i18nexus listen`
+
+```sh
+i18nexus listen -k <PROJECT_API_KEY>
+```
+
+This command starts a tunnel to your local development server using [localtunnel](https://www.npmjs.com/package/localtunnel), allowing i18nexus to send real-time webhooks for translation updates.
+
+When a string is added, updated, or deleted in your project, a webhook is sent to your local server, automatically updating your local JSON files.
+
+### Options
+
+| Option              | Required? | Default                 |
+| ------------------- | --------- | ----------------------- |
+| `--api-key` or `-k` | &#10004;  |                         |
+| `--path` or `-p`    |           | See `pull` default path |
+| `--port`            |           | '3002'                  |
+
+### Notes
+
+`--api-key`  
+Your project API key (Can also be set using environment variable `I18NEXUS_API_KEY`)
+
+`--port`  
+The local port your server will listen on to receive incoming webhook requests from i18nexus. Defaults to `3002`.
+
+The tunnel will remain active as long as the CLI is running. Press `Ctrl+C` to stop listening.

package/bin/index.js

@@ -8,6 +8,7 @@ const updateString = require('../commands/updateString');
 const deleteString = require('../commands/deleteString');
 const importJson = require('../commands/importJson');
 const addNamespace = require('../commands/addNamespace');
+const listen = require('../commands/listen');
 
 // Using Next's env variable loader because
 // Next supports more than just one .env file
@@ -75,27 +76,32 @@ program
     '-v, --value <stringValue>',
     'The value of the string to create'
   )
-  .requiredOption(
+  .option(
     '-ns, --namespace <stringNamespace>',
-    'The namespace in which to create the string'
+    'The namespace in which to create the string (Only required if your project uses namespaces and has more than one namespace)'
+  )
+  .option(
+    '-n, --notes <teamNotes>',
+    'Team notes about the string to create (optional)'
   )
   .option(
-    '-d, --details <stringDetails>',
-    'The details of the string to create (optional)'
+    '-ai, --ai-instructions <stringAiInstructions>',
+    'Instructions/Context for AI machine translator (optional)'
   )
   .action(options => {
     addString({
       key: options.key,
       value: options.value,
-      details: options.details,
+      notes: options.notes,
       namespace: options.namespace,
       apiKey: options.apiKey,
-      pat: options.pat
+      pat: options.pat,
+      aiInstructions: options.aiInstructions
     });
   });
 
 program
-  .command('update-string <namespaceOfString> <keyOfString>')
+  .command('update-string <namespace:key>')
   .alias('u')
   .description('Update a base string through PATCH request')
   .requiredOption(
@@ -114,7 +120,11 @@ program
     '-ns, --namespace <stringNamespace>',
     'The new namespace of the string'
   )
-  .option('-d, --details <stringDetails>', 'The new details of the string')
+  .option('-n, --notes <teamNotes>', 'The new team notes of the string')
+  .option(
+    '-ai, --ai-instructions <stringAiInstructions>',
+    'Instructions/Context for AI machine translator (optional)'
+  )
   .option(
     '--reset-confirmed',
     'Reset confirmed translations of this string with machine translations.'
@@ -123,15 +133,27 @@ program
     '--retain-confirmed',
     'Do not reset confirmed translations of this string with machine translations.'
   )
-  .action((namespaceOfString, keyOfString, options) => {
+  .action((nsKey, options) => {
+    let ns, key;
+    const split = nsKey.split(':');
+
+    if (split.length === 1) {
+      key = nsKey;
+    } else {
+      ns = split[0];
+      // in case key contains :
+      key = split.slice(1).join(':');
+    }
+
     updateString({
       id: {
-        namespace: namespaceOfString,
-        key: keyOfString
+        namespace: ns,
+        key: key
       },
       key: options.key,
       value: options.value,
-      details: options.details,
+      notes: options.notes,
+      aiInstructions: options.aiInstructions,
       namespace: options.namespace,
       apiKey: options.apiKey,
       pat: options.pat,
@@ -141,7 +163,7 @@ program
   });
 
 program
-  .command('delete-string <namespaceOfString> <keyOfString>')
+  .command('delete-string <namespace:key>')
   .alias('d')
   .description('Delete a base string and its translations')
   .requiredOption(
@@ -154,11 +176,22 @@ program
     'A personal access token generated for your account in i18nexus.',
     process.env.I18NEXUS_PERSONAL_ACCESS_TOKEN
   )
-  .action((namespaceOfString, keyOfString, options) => {
+  .action((nsKey, options) => {
+    let ns, key;
+    const split = nsKey.split(':');
+
+    if (split.length === 1) {
+      key = nsKey;
+    } else {
+      ns = split[0];
+      // in case key contains :
+      key = split.slice(1).join(':');
+    }
+
     deleteString({
       id: {
-        namespace: namespaceOfString,
-        key: keyOfString
+        namespace: ns,
+        key: key
       },
       apiKey: options.apiKey,
       pat: options.pat
@@ -180,9 +213,9 @@ program
     'A personal access token generated for your account in i18nexus.',
     process.env.I18NEXUS_PERSONAL_ACCESS_TOKEN
   )
-  .requiredOption(
+  .option(
     '-ns, --namespace <namespace>',
-    'The namespace in which your strings will be imported.'
+    'The namespace in which your strings will be imported. (Only required if your project uses namespaces and has more than one namespace)'
   )
   .option(
     '--overwrite',
@@ -221,4 +254,27 @@ program
     });
   });
 
+program
+  .command('listen')
+  .description(
+    'Register a live webhook for local development and setup tunnel to listen for updates to translations.'
+  )
+  .requiredOption(
+    '-k, --api-key <apiKey>',
+    'The API key for your project',
+    process.env.I18NEXUS_API_KEY
+  )
+  .option(
+    '-p, --path <path>',
+    'The path to the destination folder in which translation files will be downloaded'
+  )
+  .option('--port <port>', 'Port your local dev server runs on', '3002')
+  .action(options => {
+    listen({
+      apiKey: options.apiKey,
+      port: options.port,
+      path: options.path
+    });
+  });
+
 program.parse(process.argv);

package/commands/addString.js

@@ -14,7 +14,8 @@ const addString = async opt => {
       key: opt.key,
       value: opt.value,
       namespace: opt.namespace,
-      description: opt.details
+      description: opt.notes,
+      ai_instructions: opt.aiInstructions
     }),
     headers: {
       Authorization: `Bearer ${opt.pat}`,
@@ -28,7 +29,13 @@ const addString = async opt => {
 
   await response.json();
 
-  console.log(colors.green(`New string added to namespace "${opt.namespace}"`));
+  if (opt.namespace) {
+    console.log(
+      colors.green(`New string added to namespace "${opt.namespace}":`)
+    );
+  } else {
+    console.log(colors.green(`New string added:`));
+  }
   console.log(colors.green(`"${opt.key}": "${opt.value}"`));
 };
 

package/commands/listen.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/* commands/listen.js */
+
+const http = require('http');
+const localtunnel = require('localtunnel');
+const colors = require('colors');
+const handleFetch = require('../handleFetch');
+const baseUrl = require('../baseUrl');
+const pull = require('../commands/pull');
+
+const LISTEN_PATH = '/webhook'; // fixed internal path
+
+const listen = async ({ apiKey, port, path }) => {
+  port = Number(port);
+
+  if (!Number.isInteger(port) || port <= 0) {
+    console.log(colors.red('Invalid port'));
+    return process.exit(1);
+  }
+
+  await pull(
+    {
+      apiKey,
+      version: 'latest',
+      path: path,
+      clean: false,
+      confirmed: false
+    },
+    {
+      logging: false,
+      successLog: 'Latest strings downloaded'
+    }
+  );
+
+  /* ────────────── 1. start local HTTP listener ────────────── */
+  const server = http.createServer(async (req, res) => {
+    if (req.method !== 'POST' || req.url !== LISTEN_PATH) {
+      res.writeHead(404).end();
+      return;
+    }
+
+    let body = '';
+    req.on('data', chunk => (body += chunk));
+    req.on('end', async () => {
+      try {
+        await pull(
+          {
+            apiKey,
+            version: 'latest',
+            path: path,
+            clean: false,
+            confirmed: false
+          },
+          {
+            logging: false,
+            successLog: '  ✔ Translations updated'
+          }
+        );
+
+        res.writeHead(200).end('ok');
+      } catch (e) {
+        console.error(colors.red('Failed to download translations:'), e);
+        res.writeHead(500).end('error');
+      }
+    });
+  });
+
+  /* ────────────── 2. start tunnel ────────────── */
+  const tunnel = await new Promise(res => {
+    server.listen(port, async () => {
+      res(await localtunnel({ port }));
+    });
+  });
+
+  const publicUrl = `${tunnel.url}${LISTEN_PATH}`;
+
+  /* ────────────── 3. register dev webhook with i18nexus ────────────── */
+  const createRes = await handleFetch(
+    `${baseUrl}/project_resources/dev_webhooks`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ api_key: apiKey, url: publicUrl })
+    }
+  );
+
+  let closing = false;
+
+  /* ────────────── graceful shutdown ────────────── */
+  const cleanUp = async (exitCode = 0) => {
+    if (closing) {
+      return;
+    }
+
+    closing = true;
+
+    try {
+      const { collection } = await createRes.json();
+      const webhookId = collection[0].id;
+
+      await handleFetch(`${baseUrl}/project_resources/dev_webhooks`, {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ api_key: apiKey, id: webhookId })
+      });
+    } catch (e) {}
+    tunnel.close();
+    server.close();
+    process.exit(exitCode);
+  };
+
+  if (createRes.status !== 200) {
+    console.log(colors.red('Failed to register webhook with i18nexus'));
+    cleanUp(1);
+    return;
+  }
+
+  console.log(colors.green('Listening for i18nexus updates…'));
+
+  process.on('SIGINT', () => cleanUp());
+  process.on('SIGTERM', () => cleanUp());
+
+  let connectionLost = false;
+  tunnel.on('error', () => {
+    if (connectionLost) {
+      return;
+    }
+    connectionLost = true;
+
+    console.error(colors.red('i18nexus listener connection lost'));
+
+    cleanUp(1);
+  });
+};
+
+module.exports = listen;

package/commands/pull.js

@@ -22,7 +22,12 @@ const cleanDirectory = path => {
   });
 };
 
-const pull = async opt => {
+const pull = async (opt, internalOptions = {}) => {
+  const {
+    logging = true,
+    successLog = 'Translations downloaded successfully'
+  } = internalOptions;
+
   let path = opt.path;
 
   const project = await getProject(opt.apiKey);
@@ -66,7 +71,9 @@ const pull = async opt => {
     return process.exit(1);
   }
 
-  console.log(`Downloading translations to ${path}...`);
+  if (logging) {
+    console.log(`Downloading translations to ${path}...`);
+  }
 
   const lngResponse = await handleFetch(
     `${baseUrl}/project_resources/languages.json?api_key=${opt.apiKey}`
@@ -143,7 +150,7 @@ const pull = async opt => {
     }
   }
 
-  console.log(colors.green('Translations downloaded successfully.'));
+  console.log(colors.green(successLog));
 };
 
 module.exports = pull;

package/commands/updateString.js

@@ -28,7 +28,8 @@ const addString = async opt => {
       key: opt.key,
       value: opt.value,
       namespace: opt.namespace,
-      description: opt.details,
+      description: opt.notes,
+      ai_instructions: opt.aiInstructions,
       reset_confirmed: resetConfirmed
     }),
     headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18nexus-cli",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Command line interface (CLI) for accessing the i18nexus API",
   "main": "index.js",
   "bin": {
@@ -9,7 +9,9 @@
   "keywords": [
     "i18nexus",
     "cli",
-    "i18next"
+    "react-intl",
+    "i18next",
+    "next-intl"
   ],
   "author": "i18nexus",
   "license": "MIT",
@@ -18,6 +20,7 @@
     "colors": "^1.4.0",
     "commander": "^7.2.0",
     "https-proxy-agent": "^5.0.0",
+    "localtunnel": "^2.0.2",
     "node-fetch": "^2.6.7"
   }
 }