locize-cli 12.1.1 → 12.3.0

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,27 @@ 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.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
+
 ## [12.1.1](https://github.com/locize/locize-cli/compare/v12.1.0...v12.1.1) - 2026-04-21
 
 - sync: fix default for `--auto-translate` option

package/README.md

@@ -178,6 +178,7 @@ locize sync --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-pro
 - all non reference languages will always be just locally replaced by what is published on locize, unless the *--skip-delete true* argument is used
 - if you change the values of existing keys in the reference language, it will not change them in locize (to change the existing values you have to change it directly in locize or use the *--update-values true* argument)
 - if you update existing keys (with *--update-values true*) the automatic translation is not triggered, unless the *--auto-translate true* argument us used
+- if you want to restrict the automatic translation to specific target languages only, you can use the *--auto-translate-languages de,fr* argument (together with *--auto-translate true*); if omitted, all languages are auto-translated
 - **if you want to take into account all languages instead of the reference language only while comparing the namespace content between local and remote, you can use the command argument *--reference-language-only false***
 - **if you want to take into account the modification time while comparing the namespace content between local and remote, you can use the command argument *--compare-modification-time true***
 

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.1.1'); // This string is replaced with the actual version at build time by rollup
+  .version('12.3.0'); // 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})`);
 
@@ -419,6 +419,7 @@ program
   .option('-u, --update-values <true|false>', 'This will update values of existing translations. (default: false)', 'false')
   .option('--auto-translate <true|false>', 'This will trigger auto-translation of updated translations.')
   .option('--auto-translate-review <true|false>', 'When auto-translating, route results through the review workflow for languages that have review enabled. (default: false)', 'false')
+  .option('--auto-translate-languages <lng1,lng2>', 'Restrict auto-translation to these target languages only (comma separated). Only effective together with --auto-translate and when updating the reference language. If omitted, all languages are auto-translated.')
   .option('-S, --skip-delete <true|false>', 'This will skip the removal of keys on locize. (default: false)', 'false')
   .option('-D, --delete-remote-namespace <true|false>', 'This will delete a complete namespace on locize, if a local file in reference language was deleted. (default: false)', 'false')
   .option('-m, --path-mask <mask>', 'This will define the folder and file structure; do not add a file extension (default: {{language}}/{{namespace}})', `{{language}}${path.sep}{{namespace}}`)
@@ -476,6 +477,7 @@ program
     const updateValues = options.updateValues === 'true';
     const autoTranslate = options.autoTranslate === 'true' ? true : options.autoTranslate === 'false' ? false : undefined;
     const autoTranslateReview = options.autoTranslateReview === 'true';
+    const autoTranslateLanguages = options.autoTranslateLanguages;
     const skipDelete = options.skipDelete === 'true';
     const deleteRemoteNamespace = options.deleteRemoteNamespace === 'true';
     const languageFolderPrefix = options.languageFolderPrefix || '';
@@ -500,6 +502,7 @@ program
       updateValues,
       autoTranslate,
       autoTranslateReview,
+      autoTranslateLanguages: autoTranslateLanguages && autoTranslateLanguages.split(',').map((l) => l.trim()).filter(Boolean),
       skipDelete,
       deleteRemoteNamespace,
       languageFolderPrefix,

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.1.1",
+  "version": "12.3.0",
   "type": "commonjs"
 }

package/dist/cjs/request.js

@@ -39,7 +39,7 @@ async function request (url, options) {
   }
 
   options.headers = options.headers || {};
-  options.headers['User-Agent'] = `locize-cli/v12.1.1 (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.0 (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) {

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');
 
@@ -435,6 +436,9 @@ async function update (opt, lng, ns, shouldOmit = false) {
     if (opt.autoTranslateReview && lng === opt.referenceLanguage) {
       queryParams.append('autotranslatereview', 'true');
     }
+    if (opt.autoTranslateLanguages && opt.autoTranslateLanguages.length > 0 && lng === opt.referenceLanguage) {
+      queryParams.append('autotranslatelanguages', opt.autoTranslateLanguages.join(','));
+    }
     if (so) {
       queryParams.append('omitstatsgeneration', 'true');
     }
@@ -667,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.1.1'); // This string is replaced with the actual version at build time by rollup
+  .version('12.3.0'); // 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})`);
 
@@ -417,6 +417,7 @@ program
   .option('-u, --update-values <true|false>', 'This will update values of existing translations. (default: false)', 'false')
   .option('--auto-translate <true|false>', 'This will trigger auto-translation of updated translations.')
   .option('--auto-translate-review <true|false>', 'When auto-translating, route results through the review workflow for languages that have review enabled. (default: false)', 'false')
+  .option('--auto-translate-languages <lng1,lng2>', 'Restrict auto-translation to these target languages only (comma separated). Only effective together with --auto-translate and when updating the reference language. If omitted, all languages are auto-translated.')
   .option('-S, --skip-delete <true|false>', 'This will skip the removal of keys on locize. (default: false)', 'false')
   .option('-D, --delete-remote-namespace <true|false>', 'This will delete a complete namespace on locize, if a local file in reference language was deleted. (default: false)', 'false')
   .option('-m, --path-mask <mask>', 'This will define the folder and file structure; do not add a file extension (default: {{language}}/{{namespace}})', `{{language}}${path.sep}{{namespace}}`)
@@ -474,6 +475,7 @@ program
     const updateValues = options.updateValues === 'true';
     const autoTranslate = options.autoTranslate === 'true' ? true : options.autoTranslate === 'false' ? false : undefined;
     const autoTranslateReview = options.autoTranslateReview === 'true';
+    const autoTranslateLanguages = options.autoTranslateLanguages;
     const skipDelete = options.skipDelete === 'true';
     const deleteRemoteNamespace = options.deleteRemoteNamespace === 'true';
     const languageFolderPrefix = options.languageFolderPrefix || '';
@@ -498,6 +500,7 @@ program
       updateValues,
       autoTranslate,
       autoTranslateReview,
+      autoTranslateLanguages: autoTranslateLanguages && autoTranslateLanguages.split(',').map((l) => l.trim()).filter(Boolean),
       skipDelete,
       deleteRemoteNamespace,
       languageFolderPrefix,

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

@@ -37,7 +37,7 @@ async function request (url, options) {
   }
 
   options.headers = options.headers || {};
-  options.headers['User-Agent'] = `locize-cli/v12.1.1 (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.0 (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) {

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';
 
@@ -433,6 +434,9 @@ async function update (opt, lng, ns, shouldOmit = false) {
     if (opt.autoTranslateReview && lng === opt.referenceLanguage) {
       queryParams.append('autotranslatereview', 'true');
     }
+    if (opt.autoTranslateLanguages && opt.autoTranslateLanguages.length > 0 && lng === opt.referenceLanguage) {
+      queryParams.append('autotranslatelanguages', opt.autoTranslateLanguages.join(','));
+    }
     if (so) {
       queryParams.append('omitstatsgeneration', 'true');
     }
@@ -665,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.1.1",
+  "version": "12.3.0",
   "description": "locize cli to import locales",
   "type": "module",
   "main": "./dist/cjs/index.js",