locize-cli 12.2.0 → 12.3.1

package/.github/workflows/node.yml

@@ -15,9 +15,9 @@ jobs:
         # os: [ubuntu-latest, windows-latest, macOS-latest]
         os: [ubuntu-latest, windows-latest, macOS-latest]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
       - run: npm install

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 Project versioning adheres to [Semantic Versioning](http://semver.org/).
 Change log format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## [12.3.1](https://github.com/locize/locize-cli/compare/v12.3.0...v12.3.1) - 2026-06-18
+
+- request: retry transient network failures with exponential backoff and jitter
+  instead of a fixed 5s delay. This spreads retries so that bursts of
+  concurrent CLI runs (e.g. in CI) no longer retry in lockstep and hit the API
+  at the same instant.
+
+## [12.3.0](https://github.com/locize/locize-cli/compare/v12.2.0...v12.3.0) - 2026-06-10
+
+- sync: creates missing remote languages on the fly. A project without any
+  languages yet is bootstrapped automatically from the local language folders
+  (or `--language`/`--languages`), and a language that exists locally but not
+  in the project is created too instead of being silently ignored — the server
+  decides whether the api-key may (admin keys always; any write-capable key
+  while the project still has no content). On rejection sync warns and
+  continues; `--dry` never creates languages.
+- migrate: also works on a project without any languages yet (previously both
+  sync and migrate failed with a misleading "Project not found" error when the
+  project's languages file was empty).
+- fix: the "wrong cdnType" hint no longer crashes (or fires) when the other
+  endpoint answers with a non-JSON response; the empty-project error now reads
+  "Project … not found — or it has no languages yet!" and carries an
+  `EMPTY_LANGUAGES` / `WRONG_CDN_TYPE` error code for programmatic consumers.
+
 ## [12.2.0](https://github.com/locize/locize-cli/compare/v12.1.1...v12.2.0) - 2026-06-01
 
 - sync: introduce `--auto-translate-languages <lng1,lng2>` option to restrict auto-translation to specific target languages

package/dist/cjs/addLanguage.js

@@ -0,0 +1,42 @@
+'use strict';
+
+var colors = require('colors');
+var request = require('./request.js');
+
+/**
+ * Adds a language to the project via POST /language/{projectId}/{language}.
+ *
+ * Idempotent for bootstrap flows: an "already exists" answer counts as
+ * success — the API responds 400 (ValidationError "Language already exists!"),
+ * and 412 is kept for backwards compatibility with older deployments.
+ *
+ * Other failures throw an Error carrying `status` (e.g. 401 when the key
+ * may not create languages) so callers can give role-specific guidance.
+ */
+const addLanguage = async (opt, l) => {
+  const url = opt.apiEndpoint + '/language/' + opt.projectId + '/' + l;
+  try {
+    const { res, obj } = await request(url, {
+      method: 'post',
+      headers: {
+        Authorization: opt.apiKey
+      }
+    });
+    if (res.status === 400 && ((obj && (obj.errorMessage || obj.message)) || '').indexOf('already exists') > -1) {
+      console.log(colors.yellow(`language ${l} already exists...`));
+      return
+    }
+    if (res.status >= 300 && res.status !== 412) {
+      const serverMessage = obj && (obj.errorMessage || obj.message);
+      const err = new Error(serverMessage ? `${res.statusText} (${res.status}) | ${serverMessage}` : `${res.statusText} (${res.status})`);
+      err.status = res.status;
+      throw err
+    }
+    console.log(colors.green(`added language ${l}...`));
+  } catch (err) {
+    console.log(colors.red(`failed to add language ${l}...`));
+    throw err
+  }
+};
+
+module.exports = addLanguage;

package/dist/cjs/cli.js

@@ -50,7 +50,7 @@ const program = new commander.Command();
 
 program
   .description('The official locize CLI.')
-  .version('12.2.0'); // This string is replaced with the actual version at build time by rollup
+  .version('12.3.1'); // This string is replaced with the actual version at build time by rollup
 // .option('-a, --api-endpoint <url>', `Specify the api-endpoint url that should be used (default: ${defaultApiEndpoint})`)
 // .option('-C, --config-path <configPath>', `Specify the path to the optional locize config file (default: ${configInWorkingDirectory} or ${configInHome})`);
 

package/dist/cjs/getRemoteLanguages.js

@@ -21,13 +21,26 @@ const getRemoteLanguages = async (opt) => {
   if (res.status >= 300) throw new Error(res.statusText + ' (' + res.status + ')')
 
   if (Object.keys(obj).length === 0) {
-    let errMsg = 'Project with id "' + opt.projectId + '" not found!';
+    // An empty object is ambiguous: unknown project, a project without
+    // languages, or a freshly created project whose languages file has not
+    // been generated yet.
+    let errMsg = 'Project with id "' + opt.projectId + '" not found — or it has no languages yet!';
     const otherEndpoint = getOtherApiEndpoint(opt.apiEndpoint);
-    const { res: res2, obj: obj2 } = await request(otherEndpoint + '/languages/' + opt.projectId + '?ts=' + Date.now() + (opt.cdnType === 'standard' ? '' : '&cache=no'), { method: 'get' });
-    if (res2.status === 200 && Object.keys(obj2).length > 0) {
-      errMsg += ` It seems you're using the wrong cdnType. Your Locize project is configured to use "${opt.cdnType === 'standard' ? 'pro' : 'standard'}" but here you've configured "${opt.cdnType}".`;
+    if (otherEndpoint) {
+      const { res: res2, obj: obj2 } = await request(otherEndpoint + '/languages/' + opt.projectId + '?ts=' + Date.now() + (opt.cdnType === 'standard' ? '' : '&cache=no'), { method: 'get' });
+      // obj2 is undefined for non-JSON responses (e.g. an HTML 404 page) —
+      // only a real, non-empty JSON object indicates the other cdnType.
+      if (res2.status === 200 && obj2 && typeof obj2 === 'object' && Object.keys(obj2).length > 0) {
+        errMsg += ` It seems you're using the wrong cdnType. Your Locize project is configured to use "${opt.cdnType === 'standard' ? 'pro' : 'standard'}" but here you've configured "${opt.cdnType}".`;
+        const cdnErr = new Error(errMsg);
+        cdnErr.code = 'WRONG_CDN_TYPE';
+        throw cdnErr
+      }
     }
-    throw new Error(errMsg)
+    const err = new Error(errMsg);
+    // lets callers (sync/migrate) bootstrap the languages instead of failing
+    err.code = 'EMPTY_LANGUAGES';
+    throw err
   }
 
   const lngs = Object.keys(obj);

package/dist/cjs/migrate.js

@@ -6,6 +6,7 @@ var flatten = require('flat');
 var colors = require('colors');
 var request = require('./request.js');
 var getRemoteLanguages = require('./getRemoteLanguages.js');
+var addLanguage = require('./addLanguage.js');
 var os = require('node:os');
 var mapLimit = require('./mapLimit.js');
 var download = require('./download.js');
@@ -149,23 +150,6 @@ const upload = async (opt, nss) => {
   await mapLimit(nssNonRefLng, concurrency, async (ns) => transfer(opt, ns));
 };
 
-const addLanguage = async (opt, l) => {
-  const url = opt.apiEndpoint + '/language/' + opt.projectId + '/' + l;
-  try {
-    const { res } = await request(url, {
-      method: 'post',
-      headers: {
-        Authorization: opt.apiKey
-      }
-    });
-    if (res.status >= 300 && res.status !== 412) throw new Error(res.statusText + ' (' + res.status + ')')
-    console.log(colors.green(`added language ${l}...`));
-  } catch (err) {
-    console.log(colors.red(`failed to add language ${l}...`));
-    throw err
-  }
-};
-
 const downloadAfterMigrate = async (opt) => {
   console.log(colors.yellow('downloading translations after migration...'));
   await new Promise((resolve) => setTimeout(resolve, 15000));
@@ -224,8 +208,14 @@ const migrate = async (opt) => {
     try {
       remoteLanguages = await getRemoteLanguages(opt);
     } catch (err) {
-      console.error(colors.red(err.stack));
-      process.exit(1);
+      // A project without any languages yet is fine for migrate — every local
+      // language is created below via addLanguage before the upload.
+      if (err.code === 'EMPTY_LANGUAGES' && opt.apiKey) {
+        remoteLanguages = [];
+      } else {
+        console.error(colors.red(err.stack));
+        process.exit(1);
+      }
     }
     const localLanguages = [];
     nss.forEach((n) => {

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "locize-cli",
-  "version": "12.2.0",
+  "version": "12.3.1",
   "type": "commonjs"
 }

package/dist/cjs/request.js

@@ -7,6 +7,10 @@ var CacheableLookup = require('cacheable-lookup');
 const cacheable = new CacheableLookup();
 cacheable.install(https.globalAgent);
 
+const RETRY_MAX_ATTEMPTS = 3;
+const RETRY_BASE_DELAY_MS = 2000;
+const RETRY_MAX_DELAY_MS = 30000;
+
 const httpProxy = process.env.http_proxy || process.env.HTTP_PROXY || process.env.https_proxy || process.env.HTTPS_PROXY;
 const isRetriableError = (err) => {
   return err && err.message && (
@@ -39,7 +43,7 @@ async function request (url, options) {
   }
 
   options.headers = options.headers || {};
-  options.headers['User-Agent'] = `locize-cli/v12.2.0 (node/${process.version}; ${process.platform} ${process.arch})`; // This string is replaced with the actual version at build time by rollup
+  options.headers['User-Agent'] = `locize-cli/v12.3.1 (node/${process.version}; ${process.platform} ${process.arch})`; // This string is replaced with the actual version at build time by rollup
   options.headers['X-User-Agent'] = options.headers['User-Agent'];
   if (options.body || options.method !== 'get') options.headers['Content-Type'] = 'application/json';
   if (options.body) {
@@ -49,19 +53,24 @@ async function request (url, options) {
   }
   if (options.headers['Authorization'] === undefined) delete options.headers['Authorization'];
 
-  async function retriableFetch (maxRetries) {
+  async function retriableFetch (retriesLeft, attempt = 0) {
     try {
       const response = await fetch(url, options);
       const result = await handleResponse(response);
       return result
     } catch (err) {
-      if (maxRetries < 1) throw err
+      if (retriesLeft < 1) throw err
       if (!isRetriableError(err)) throw err
-      await new Promise(resolve => setTimeout(resolve, 5000));
-      return retriableFetch(--maxRetries)
+      // Exponential backoff with equal jitter: spreads retries so a burst of
+      // concurrent CLI runs (e.g. CI) doesn't all retry in lockstep and
+      // hammer the API at the same instant.
+      const expDelay = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * (2 ** attempt));
+      const delay = Math.round(expDelay / 2 + Math.random() * (expDelay / 2));
+      await new Promise(resolve => setTimeout(resolve, delay));
+      return retriableFetch(retriesLeft - 1, attempt + 1)
     }
   }
-  return retriableFetch(3)
+  return retriableFetch(RETRY_MAX_ATTEMPTS)
 }
 
 module.exports = request;

package/dist/cjs/sync.js

@@ -19,6 +19,7 @@ var getProjectStats = require('./getProjectStats.js');
 var xcstrings = require('locize-xcstrings');
 var getBranches = require('./getBranches.js');
 var isValidUuid = require('./isValidUuid.js');
+var addLanguage = require('./addLanguage.js');
 var os = require('node:os');
 var lngs = require('./lngs.js');
 
@@ -670,9 +671,101 @@ const checkForMissingLocalNamespaces = (downloads, localNamespaces, opt) => {
   return localMissingNamespaces
 };
 
+/**
+ * Discovers which languages the local files intend, independent of the remote
+ * state: explicit --language/--languages win; otherwise the language folders
+ * under opt.path (only when the path mask starts with the language segment —
+ * the default `{{language}}/{{namespace}}` layout).
+ */
+const discoverLocalLanguages = (opt) => {
+  if (opt.languages && opt.languages.length > 0) return [...opt.languages]
+  if (opt.language) return [opt.language]
+  const languageToken = `${opt.pathMaskInterpolationPrefix || '{{'}language${opt.pathMaskInterpolationSuffix || '}}'}`;
+  const pathMask = opt.pathMask || `${languageToken}${path.sep}{{namespace}}`;
+  if (!pathMask.startsWith(`${opt.languageFolderPrefix || ''}${languageToken}`)) return []
+  try {
+    return fs.readdirSync(opt.path)
+      .filter((file) => fs.statSync(path.join(opt.path, file)).isDirectory())
+      .map((dir) => (opt.languageFolderPrefix ? dir.replace(opt.languageFolderPrefix, '') : dir))
+  } catch (err) {
+    return []
+  }
+};
+
+/**
+ * Bootstraps the remote languages of a project that has none yet by creating
+ * the locally intended languages (the server authorizes: admin keys always;
+ * any write-capable key while the project is still empty), then waits for the
+ * asynchronously regenerated languages file.
+ */
+const bootstrapRemoteLanguages = async (opt) => {
+  const noLanguagesHelp = `Project with id "${opt.projectId}" has no languages yet`;
+  const localLanguages = discoverLocalLanguages(opt);
+  if (localLanguages.length === 0) {
+    throw new Error(`${noLanguagesHelp} and no local languages were found to create — add languages in the project settings (or push initial content via "locize migrate"), then retry.`)
+  }
+
+  console.log(colors.yellow(`project has no languages yet — creating ${localLanguages.join(', ')}...`));
+  try {
+    for (const l of localLanguages) {
+      await addLanguage(opt, l);
+    }
+  } catch (err) {
+    if (err.status === 401) {
+      throw new Error(`${noLanguagesHelp} and this api-key may not create them — use an admin-scoped api-key (or any write-capable key while the project is still empty), or add the languages in the project settings, then retry.`)
+    }
+    throw err
+  }
+
+  // the languages file is regenerated asynchronously — retry a few times
+  let lastError;
+  for (let i = 0; i < 3; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+    try {
+      return await getRemoteLanguages(opt)
+    } catch (err) {
+      lastError = err;
+      if (err.code !== 'EMPTY_LANGUAGES') throw err
+    }
+  }
+  throw lastError
+};
+
 async function continueToSync (opt) {
   console.log(colors.grey('checking remote (locize)...'));
-  const remoteLanguages = await getRemoteLanguages(opt);
+  let remoteLanguages;
+  try {
+    remoteLanguages = await getRemoteLanguages(opt);
+  } catch (err) {
+    // A project without languages is bootstrapped on the fly (unless this is
+    // a dry run or we have no key to create them with).
+    if (err.code !== 'EMPTY_LANGUAGES' || !opt.apiKey || opt.dry) throw err
+    remoteLanguages = await bootstrapRemoteLanguages(opt);
+  }
+
+  // Languages that exist locally but not remotely are created too — the
+  // server decides whether the key may (admin always; write-capable keys
+  // while the project is empty). On rejection we warn instead of silently
+  // ignoring the local files (the pre-existing behavior).
+  const missingRemotely = discoverLocalLanguages(opt).filter((l) => remoteLanguages.indexOf(l) < 0);
+  if (missingRemotely.length > 0) {
+    if (opt.apiKey && !opt.dry) {
+      const created = [];
+      for (const l of missingRemotely) {
+        try {
+          await addLanguage(opt, l);
+          created.push(l);
+        } catch (err) {
+          console.log(colors.yellow(`language "${l}" exists locally but not in your locize project and this api-key may not create it (${err.message}) — add it in the project settings or use an admin api-key.`));
+        }
+      }
+      // the regenerated languages file lags behind — continue with the
+      // created languages included so this run already syncs them
+      created.forEach((l) => remoteLanguages.push(l));
+    } else {
+      missingRemotely.forEach((l) => console.log(colors.yellow(`language "${l}" exists locally but not in your locize project${opt.dry ? ' (dry run: not creating it)' : ' (no api-key: cannot create it)'}.`)));
+    }
+  }
 
   if (opt.referenceLanguageOnly && opt.language && opt.referenceLanguage !== opt.language) {
     opt.referenceLanguage = opt.language;

package/dist/esm/addLanguage.js

@@ -0,0 +1,40 @@
+import colors from 'colors';
+import request from './request.js';
+
+/**
+ * Adds a language to the project via POST /language/{projectId}/{language}.
+ *
+ * Idempotent for bootstrap flows: an "already exists" answer counts as
+ * success — the API responds 400 (ValidationError "Language already exists!"),
+ * and 412 is kept for backwards compatibility with older deployments.
+ *
+ * Other failures throw an Error carrying `status` (e.g. 401 when the key
+ * may not create languages) so callers can give role-specific guidance.
+ */
+const addLanguage = async (opt, l) => {
+  const url = opt.apiEndpoint + '/language/' + opt.projectId + '/' + l;
+  try {
+    const { res, obj } = await request(url, {
+      method: 'post',
+      headers: {
+        Authorization: opt.apiKey
+      }
+    });
+    if (res.status === 400 && ((obj && (obj.errorMessage || obj.message)) || '').indexOf('already exists') > -1) {
+      console.log(colors.yellow(`language ${l} already exists...`));
+      return
+    }
+    if (res.status >= 300 && res.status !== 412) {
+      const serverMessage = obj && (obj.errorMessage || obj.message);
+      const err = new Error(serverMessage ? `${res.statusText} (${res.status}) | ${serverMessage}` : `${res.statusText} (${res.status})`);
+      err.status = res.status;
+      throw err
+    }
+    console.log(colors.green(`added language ${l}...`));
+  } catch (err) {
+    console.log(colors.red(`failed to add language ${l}...`));
+    throw err
+  }
+};
+
+export { addLanguage as default };

package/dist/esm/cli.js

@@ -48,7 +48,7 @@ const program = new Command();
 
 program
   .description('The official locize CLI.')
-  .version('12.2.0'); // This string is replaced with the actual version at build time by rollup
+  .version('12.3.1'); // This string is replaced with the actual version at build time by rollup
 // .option('-a, --api-endpoint <url>', `Specify the api-endpoint url that should be used (default: ${defaultApiEndpoint})`)
 // .option('-C, --config-path <configPath>', `Specify the path to the optional locize config file (default: ${configInWorkingDirectory} or ${configInHome})`);
 

package/dist/esm/getRemoteLanguages.js

@@ -19,13 +19,26 @@ const getRemoteLanguages = async (opt) => {
   if (res.status >= 300) throw new Error(res.statusText + ' (' + res.status + ')')
 
   if (Object.keys(obj).length === 0) {
-    let errMsg = 'Project with id "' + opt.projectId + '" not found!';
+    // An empty object is ambiguous: unknown project, a project without
+    // languages, or a freshly created project whose languages file has not
+    // been generated yet.
+    let errMsg = 'Project with id "' + opt.projectId + '" not found — or it has no languages yet!';
     const otherEndpoint = getOtherApiEndpoint(opt.apiEndpoint);
-    const { res: res2, obj: obj2 } = await request(otherEndpoint + '/languages/' + opt.projectId + '?ts=' + Date.now() + (opt.cdnType === 'standard' ? '' : '&cache=no'), { method: 'get' });
-    if (res2.status === 200 && Object.keys(obj2).length > 0) {
-      errMsg += ` It seems you're using the wrong cdnType. Your Locize project is configured to use "${opt.cdnType === 'standard' ? 'pro' : 'standard'}" but here you've configured "${opt.cdnType}".`;
+    if (otherEndpoint) {
+      const { res: res2, obj: obj2 } = await request(otherEndpoint + '/languages/' + opt.projectId + '?ts=' + Date.now() + (opt.cdnType === 'standard' ? '' : '&cache=no'), { method: 'get' });
+      // obj2 is undefined for non-JSON responses (e.g. an HTML 404 page) —
+      // only a real, non-empty JSON object indicates the other cdnType.
+      if (res2.status === 200 && obj2 && typeof obj2 === 'object' && Object.keys(obj2).length > 0) {
+        errMsg += ` It seems you're using the wrong cdnType. Your Locize project is configured to use "${opt.cdnType === 'standard' ? 'pro' : 'standard'}" but here you've configured "${opt.cdnType}".`;
+        const cdnErr = new Error(errMsg);
+        cdnErr.code = 'WRONG_CDN_TYPE';
+        throw cdnErr
+      }
     }
-    throw new Error(errMsg)
+    const err = new Error(errMsg);
+    // lets callers (sync/migrate) bootstrap the languages instead of failing
+    err.code = 'EMPTY_LANGUAGES';
+    throw err
   }
 
   const lngs = Object.keys(obj);

package/dist/esm/migrate.js

@@ -4,6 +4,7 @@ import flatten from 'flat';
 import colors from 'colors';
 import request from './request.js';
 import getRemoteLanguages from './getRemoteLanguages.js';
+import addLanguage from './addLanguage.js';
 import os from 'node:os';
 import mapLimit from './mapLimit.js';
 import download from './download.js';
@@ -147,23 +148,6 @@ const upload = async (opt, nss) => {
   await mapLimit(nssNonRefLng, concurrency, async (ns) => transfer(opt, ns));
 };
 
-const addLanguage = async (opt, l) => {
-  const url = opt.apiEndpoint + '/language/' + opt.projectId + '/' + l;
-  try {
-    const { res } = await request(url, {
-      method: 'post',
-      headers: {
-        Authorization: opt.apiKey
-      }
-    });
-    if (res.status >= 300 && res.status !== 412) throw new Error(res.statusText + ' (' + res.status + ')')
-    console.log(colors.green(`added language ${l}...`));
-  } catch (err) {
-    console.log(colors.red(`failed to add language ${l}...`));
-    throw err
-  }
-};
-
 const downloadAfterMigrate = async (opt) => {
   console.log(colors.yellow('downloading translations after migration...'));
   await new Promise((resolve) => setTimeout(resolve, 15000));
@@ -222,8 +206,14 @@ const migrate = async (opt) => {
     try {
       remoteLanguages = await getRemoteLanguages(opt);
     } catch (err) {
-      console.error(colors.red(err.stack));
-      process.exit(1);
+      // A project without any languages yet is fine for migrate — every local
+      // language is created below via addLanguage before the upload.
+      if (err.code === 'EMPTY_LANGUAGES' && opt.apiKey) {
+        remoteLanguages = [];
+      } else {
+        console.error(colors.red(err.stack));
+        process.exit(1);
+      }
     }
     const localLanguages = [];
     nss.forEach((n) => {

package/dist/esm/request.js

@@ -5,6 +5,10 @@ import CacheableLookup from 'cacheable-lookup';
 const cacheable = new CacheableLookup();
 cacheable.install(https.globalAgent);
 
+const RETRY_MAX_ATTEMPTS = 3;
+const RETRY_BASE_DELAY_MS = 2000;
+const RETRY_MAX_DELAY_MS = 30000;
+
 const httpProxy = process.env.http_proxy || process.env.HTTP_PROXY || process.env.https_proxy || process.env.HTTPS_PROXY;
 const isRetriableError = (err) => {
   return err && err.message && (
@@ -37,7 +41,7 @@ async function request (url, options) {
   }
 
   options.headers = options.headers || {};
-  options.headers['User-Agent'] = `locize-cli/v12.2.0 (node/${process.version}; ${process.platform} ${process.arch})`; // This string is replaced with the actual version at build time by rollup
+  options.headers['User-Agent'] = `locize-cli/v12.3.1 (node/${process.version}; ${process.platform} ${process.arch})`; // This string is replaced with the actual version at build time by rollup
   options.headers['X-User-Agent'] = options.headers['User-Agent'];
   if (options.body || options.method !== 'get') options.headers['Content-Type'] = 'application/json';
   if (options.body) {
@@ -47,19 +51,24 @@ async function request (url, options) {
   }
   if (options.headers['Authorization'] === undefined) delete options.headers['Authorization'];
 
-  async function retriableFetch (maxRetries) {
+  async function retriableFetch (retriesLeft, attempt = 0) {
     try {
       const response = await fetch(url, options);
       const result = await handleResponse(response);
       return result
     } catch (err) {
-      if (maxRetries < 1) throw err
+      if (retriesLeft < 1) throw err
       if (!isRetriableError(err)) throw err
-      await new Promise(resolve => setTimeout(resolve, 5000));
-      return retriableFetch(--maxRetries)
+      // Exponential backoff with equal jitter: spreads retries so a burst of
+      // concurrent CLI runs (e.g. CI) doesn't all retry in lockstep and
+      // hammer the API at the same instant.
+      const expDelay = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * (2 ** attempt));
+      const delay = Math.round(expDelay / 2 + Math.random() * (expDelay / 2));
+      await new Promise(resolve => setTimeout(resolve, delay));
+      return retriableFetch(retriesLeft - 1, attempt + 1)
     }
   }
-  return retriableFetch(3)
+  return retriableFetch(RETRY_MAX_ATTEMPTS)
 }
 
 export { request as default };

package/dist/esm/sync.js

@@ -17,6 +17,7 @@ import getProjectStats from './getProjectStats.js';
 import xcstrings from 'locize-xcstrings';
 import getBranches from './getBranches.js';
 import isValidUuid from './isValidUuid.js';
+import addLanguage from './addLanguage.js';
 import os from 'node:os';
 import lngCodes from './lngs.js';
 
@@ -668,9 +669,101 @@ const checkForMissingLocalNamespaces = (downloads, localNamespaces, opt) => {
   return localMissingNamespaces
 };
 
+/**
+ * Discovers which languages the local files intend, independent of the remote
+ * state: explicit --language/--languages win; otherwise the language folders
+ * under opt.path (only when the path mask starts with the language segment —
+ * the default `{{language}}/{{namespace}}` layout).
+ */
+const discoverLocalLanguages = (opt) => {
+  if (opt.languages && opt.languages.length > 0) return [...opt.languages]
+  if (opt.language) return [opt.language]
+  const languageToken = `${opt.pathMaskInterpolationPrefix || '{{'}language${opt.pathMaskInterpolationSuffix || '}}'}`;
+  const pathMask = opt.pathMask || `${languageToken}${path.sep}{{namespace}}`;
+  if (!pathMask.startsWith(`${opt.languageFolderPrefix || ''}${languageToken}`)) return []
+  try {
+    return fs.readdirSync(opt.path)
+      .filter((file) => fs.statSync(path.join(opt.path, file)).isDirectory())
+      .map((dir) => (opt.languageFolderPrefix ? dir.replace(opt.languageFolderPrefix, '') : dir))
+  } catch (err) {
+    return []
+  }
+};
+
+/**
+ * Bootstraps the remote languages of a project that has none yet by creating
+ * the locally intended languages (the server authorizes: admin keys always;
+ * any write-capable key while the project is still empty), then waits for the
+ * asynchronously regenerated languages file.
+ */
+const bootstrapRemoteLanguages = async (opt) => {
+  const noLanguagesHelp = `Project with id "${opt.projectId}" has no languages yet`;
+  const localLanguages = discoverLocalLanguages(opt);
+  if (localLanguages.length === 0) {
+    throw new Error(`${noLanguagesHelp} and no local languages were found to create — add languages in the project settings (or push initial content via "locize migrate"), then retry.`)
+  }
+
+  console.log(colors.yellow(`project has no languages yet — creating ${localLanguages.join(', ')}...`));
+  try {
+    for (const l of localLanguages) {
+      await addLanguage(opt, l);
+    }
+  } catch (err) {
+    if (err.status === 401) {
+      throw new Error(`${noLanguagesHelp} and this api-key may not create them — use an admin-scoped api-key (or any write-capable key while the project is still empty), or add the languages in the project settings, then retry.`)
+    }
+    throw err
+  }
+
+  // the languages file is regenerated asynchronously — retry a few times
+  let lastError;
+  for (let i = 0; i < 3; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+    try {
+      return await getRemoteLanguages(opt)
+    } catch (err) {
+      lastError = err;
+      if (err.code !== 'EMPTY_LANGUAGES') throw err
+    }
+  }
+  throw lastError
+};
+
 async function continueToSync (opt) {
   console.log(colors.grey('checking remote (locize)...'));
-  const remoteLanguages = await getRemoteLanguages(opt);
+  let remoteLanguages;
+  try {
+    remoteLanguages = await getRemoteLanguages(opt);
+  } catch (err) {
+    // A project without languages is bootstrapped on the fly (unless this is
+    // a dry run or we have no key to create them with).
+    if (err.code !== 'EMPTY_LANGUAGES' || !opt.apiKey || opt.dry) throw err
+    remoteLanguages = await bootstrapRemoteLanguages(opt);
+  }
+
+  // Languages that exist locally but not remotely are created too — the
+  // server decides whether the key may (admin always; write-capable keys
+  // while the project is empty). On rejection we warn instead of silently
+  // ignoring the local files (the pre-existing behavior).
+  const missingRemotely = discoverLocalLanguages(opt).filter((l) => remoteLanguages.indexOf(l) < 0);
+  if (missingRemotely.length > 0) {
+    if (opt.apiKey && !opt.dry) {
+      const created = [];
+      for (const l of missingRemotely) {
+        try {
+          await addLanguage(opt, l);
+          created.push(l);
+        } catch (err) {
+          console.log(colors.yellow(`language "${l}" exists locally but not in your locize project and this api-key may not create it (${err.message}) — add it in the project settings or use an admin api-key.`));
+        }
+      }
+      // the regenerated languages file lags behind — continue with the
+      // created languages included so this run already syncs them
+      created.forEach((l) => remoteLanguages.push(l));
+    } else {
+      missingRemotely.forEach((l) => console.log(colors.yellow(`language "${l}" exists locally but not in your locize project${opt.dry ? ' (dry run: not creating it)' : ' (no api-key: cannot create it)'}.`)));
+    }
+  }
 
   if (opt.referenceLanguageOnly && opt.language && opt.referenceLanguage !== opt.language) {
     opt.referenceLanguage = opt.language;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locize-cli",
-  "version": "12.2.0",
+  "version": "12.3.1",
   "description": "locize cli to import locales",
   "type": "module",
   "main": "./dist/cjs/index.js",