feat: add experimentalPushAll option

Author: robrechtme

.gitignore

@@ -8,3 +8,6 @@ out
 
 # Env
 .env
+
+# macOS
+.DS_Store

README.md

@@ -90,6 +90,7 @@ module.exports = {
 <summary>PushOptions</summary>
 <br>
 
+- `experimentalPushAll`: Upload all locales in a single API request instead of one request per locale. This can significantly improve performance for projects with many locales.
 - `ignore-new`: Specify that new assets will NOT be added to the project.
 - `ignore-existing`: Specify that existing assets encountered in the file will NOT be updated.
 - `tag-new`: Tag any NEW assets added during the import with the given tags (comma separated).
@@ -144,6 +145,7 @@ Push changes to the translation files to Loco. Depending on the `push` options,
 #### Options
 
 - `-y, --yes`: Automatically answer yes to all confirmation prompts (default: false)
+- `--experimental-push-all`: Upload all locales in a single API request for improved performance. Reduces API calls from N (one per locale) to 1. Can also be set via `push.experimentalPushAll` in config.
 
 ## Contributing
 

cli.ts

@@ -30,6 +30,7 @@ program
     'The status option is removed in v2, use the `push.flag-new` option in `loco.config.js` instead'
   )
   .option('-y, --yes', 'Answer yes to all confirmation prompts', false)
+  .option('--experimental-push-all', 'Upload all locales in a single request')
   .description('Upload assets to Loco')
   .action(handleAsyncErrors(push));
 

src/commands/push.ts

@@ -2,21 +2,25 @@ import chalk from 'chalk';
 import { Command } from 'commander';
 import inquirer from 'inquirer';
 import cliProgress from 'cli-progress';
-import { apiPull, apiPush } from '../lib/api';
+import { apiPull, apiPush, apiPushAll } from '../lib/api';
 import { diff } from '../lib/diff';
 import { readFiles } from '../lib/readFiles';
 import { getGlobalOptions } from '../util/options';
 import { printDiff } from '../util/print';
-import { flattenTranslations } from '../lib/dotObject';
+import { flattenTranslations, flattenAllTranslations } from '../lib/dotObject';
 import { log } from '../util/logger';
 
 interface CommandOptions {
   yes?: boolean;
   status?: string;
   tag?: string;
+  experimentalPushAll?: boolean;
 }
 
-const push = async ({ yes, status, tag }: CommandOptions, program: Command) => {
+const push = async (
+  { yes, status, tag, experimentalPushAll }: CommandOptions,
+  program: Command
+) => {
   if (status) {
     log.warn(
       'The status option is removed in v2, use the `push.flag-new` option in `loco.config.js` instead'
@@ -32,10 +36,15 @@ const push = async ({ yes, status, tag }: CommandOptions, program: Command) => {
     accessKey,
     localesDir,
     namespaces,
-    push: pushOptions,
+    push: configPushOptions,
     pull: pullOptions,
     maxFiles
   } = options;
+  // Merge CLI flag with config options (CLI takes precedence)
+  const pushOptions = {
+    ...configPushOptions,
+    ...(experimentalPushAll !== undefined && { experimentalPushAll })
+  };
   const deleteAbsent = pushOptions?.['delete-absent'] ?? false;
   const local = await readFiles(localesDir, namespaces);
   const remote = await apiPull(accessKey, pullOptions);
@@ -84,19 +93,28 @@ const push = async ({ yes, status, tag }: CommandOptions, program: Command) => {
     }
   }
 
-  const length = Object.keys(remote).length;
-  const progressbar = new cliProgress.SingleBar({
-    format: `Uploading in ${length} locales |${chalk.cyan('{bar}')}| {value}/{total}`,
-    barCompleteChar: '\u2588',
-    barIncompleteChar: '\u2591',
-    hideCursor: true
-  });
-  progressbar.start(length, 0);
-  for (const [locale, translations] of Object.entries(local)) {
-    progressbar.increment();
-    await apiPush(accessKey, locale, flattenTranslations(translations), pushOptions);
+  if (pushOptions?.experimentalPushAll) {
+    const localeCount = Object.keys(local).length;
+    log.log(
+      `Uploading ${localeCount} locale${localeCount > 1 ? 's' : ''} (experimentalPushAll)...`
+    );
+    await apiPushAll(accessKey, flattenAllTranslations(local), pushOptions);
+    log.log('Done.');
+  } else {
+    const length = Object.keys(remote).length;
+    const progressbar = new cliProgress.SingleBar({
+      format: `Uploading in ${length} locales |${chalk.cyan('{bar}')}| {value}/{total}`,
+      barCompleteChar: '\u2588',
+      barIncompleteChar: '\u2591',
+      hideCursor: true
+    });
+    progressbar.start(length, 0);
+    for (const [locale, translations] of Object.entries(local)) {
+      progressbar.increment();
+      await apiPush(accessKey, locale, flattenTranslations(translations), pushOptions);
+    }
+    progressbar.stop();
   }
-  progressbar.stop();
 
   log.log();
 

src/lib/api.ts

@@ -55,7 +55,30 @@ export const apiPush = (
       locale,
       ...Object.fromEntries(
         Object.entries(options)
-          .filter(([, v]) => v !== undefined)
+          .filter(([k, v]) => v !== undefined && k !== 'experimentalPushAll')
+          .map(([k, v]) => [k, String(v)])
+      )
+    },
+    {
+      method: 'POST',
+      body: JSON.stringify(translations)
+    }
+  );
+
+export const apiPushAll = (
+  key: string,
+  translations: Record<string, FlatTranslations>,
+  options: PushOptions = {}
+) =>
+  fetchApi<void>(
+    key,
+    '/import/json',
+    {
+      locale: 'auto',
+      format: 'multi',
+      ...Object.fromEntries(
+        Object.entries(options)
+          .filter(([k, v]) => v !== undefined && k !== 'experimentalPushAll')
           .map(([k, v]) => [k, String(v)])
       )
     },

src/lib/dotObject.ts

@@ -1,4 +1,4 @@
-import { DiffRecord, TranslationValue } from '../../types';
+import { DiffRecord, TranslationValue, Translations } from '../../types';
 
 type DiffValue = string | undefined;
 type DiffObject = { [key: string]: DiffValue | DiffObject };
@@ -49,3 +49,14 @@ export const flattenTranslations = (obj: TranslationValue): Record<string, strin
   recurse(obj);
   return res;
 };
+
+/**
+ * Flatten all translations for all locales at once.
+ * Returns a Record mapping locale codes to their flattened translations.
+ */
+export const flattenAllTranslations = (
+  translations: Translations
+): Record<string, Record<string, string>> =>
+  Object.fromEntries(
+    Object.entries(translations).map(([locale, values]) => [locale, flattenTranslations(values)])
+  );

test/api.test.ts

@@ -11,7 +11,7 @@ import {
 vi.mock('isomorphic-unfetch');
 
 import fetch from 'isomorphic-unfetch';
-import { apiPull, apiPush } from '../src/lib/api';
+import { apiPull, apiPush, apiPushAll } from '../src/lib/api';
 
 const mockFetch = vi.mocked(fetch);
 
@@ -136,4 +136,74 @@ describe('apiPush', () => {
 
     await expect(apiPush('test-api-key', 'en', {})).rejects.toThrow('HTTPError: 403 Forbidden');
   });
+
+  test('excludes experimentalPushAll from query params', async () => {
+    mockFetch.mockResolvedValueOnce(createMockResponse({}) as Response);
+
+    await apiPush('test-api-key', 'en', { 'common.hello': 'Hello' }, { experimentalPushAll: true });
+
+    const call = mockFetch.mock.calls[0]!;
+    const url = call[0] as URL;
+    expect(url.searchParams.has('experimentalPushAll')).toBe(false);
+  });
+});
+
+describe('apiPushAll', () => {
+  test('sends POST to /import/json with locale=auto and format=multi', async () => {
+    mockFetch.mockResolvedValueOnce(createMockResponse({}) as Response);
+
+    await apiPushAll('test-api-key', { en: { 'common.hello': 'Hello' } });
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    const call = mockFetch.mock.calls[0]!;
+    const url = call[0] as URL;
+    expect(url.pathname).toBe('/api/import/json');
+    expect(url.searchParams.get('locale')).toBe('auto');
+    expect(url.searchParams.get('format')).toBe('multi');
+
+    const options = call[1] as RequestInit;
+    expect(options.method).toBe('POST');
+    expect(options.headers).toEqual({ Authorization: 'Loco test-api-key' });
+  });
+
+  test('sends multi-locale JSON body', async () => {
+    mockFetch.mockResolvedValueOnce(createMockResponse({}) as Response);
+
+    const translations = {
+      en: { 'common.hello': 'Hello', 'common.bye': 'Goodbye' },
+      es: { 'common.hello': 'Hola', 'common.bye': 'Adiós' }
+    };
+    await apiPushAll('test-api-key', translations);
+
+    const call = mockFetch.mock.calls[0]!;
+    const options = call[1] as RequestInit;
+    expect(options.body).toBe(JSON.stringify(translations));
+  });
+
+  test('converts boolean options to strings', async () => {
+    mockFetch.mockResolvedValueOnce(createMockResponse({}) as Response);
+
+    await apiPushAll('test-api-key', { en: {} }, { 'delete-absent': true });
+
+    const call = mockFetch.mock.calls[0]!;
+    const url = call[0] as URL;
+    expect(url.searchParams.get('delete-absent')).toBe('true');
+  });
+
+  test('excludes experimentalPushAll from query params', async () => {
+    mockFetch.mockResolvedValueOnce(createMockResponse({}) as Response);
+
+    await apiPushAll('test-api-key', { en: {} }, { experimentalPushAll: true });
+
+    const call = mockFetch.mock.calls[0]!;
+    const url = call[0] as URL;
+    expect(url.searchParams.has('experimentalPushAll')).toBe(false);
+  });
+
+  test('throws on non-2xx response', async () => {
+    mockFetch.mockResolvedValueOnce(createMockErrorResponse(403, 'Forbidden') as Response);
+
+    await expect(apiPushAll('test-api-key', {})).rejects.toThrow('HTTPError: 403 Forbidden');
+  });
 });

test/commands/push.test.ts

@@ -18,7 +18,7 @@ vi.mock('cli-progress', () => ({
 
 import { getGlobalOptions } from '../../src/util/options';
 import { readFiles } from '../../src/lib/readFiles';
-import { apiPull, apiPush } from '../../src/lib/api';
+import { apiPull, apiPush, apiPushAll } from '../../src/lib/api';
 import { log } from '../../src/util/logger';
 import inquirer from 'inquirer';
 import push from '../../src/commands/push';
@@ -27,6 +27,7 @@ const mockGetGlobalOptions = vi.mocked(getGlobalOptions);
 const mockReadFiles = vi.mocked(readFiles);
 const mockApiPull = vi.mocked(apiPull);
 const mockApiPush = vi.mocked(apiPush);
+const mockApiPushAll = vi.mocked(apiPushAll);
 const mockLog = vi.mocked(log);
 const mockInquirer = vi.mocked(inquirer);
 
@@ -58,6 +59,7 @@ beforeEach(() => {
   mockLog.warn = vi.fn();
   mockLog.info = vi.fn();
   mockApiPush.mockResolvedValue(undefined);
+  mockApiPushAll.mockResolvedValue(undefined);
   mockExit = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
     throw new ExitError(code ?? 0);
   }) as never);
@@ -114,8 +116,8 @@ describe('push command', () => {
     await expect(push({}, mockProgram)).rejects.toThrow(ExitError);
 
     expect(mockApiPush).toHaveBeenCalledTimes(2);
-    expect(mockApiPush).toHaveBeenCalledWith('test-key', 'en', { hello: 'Hello' }, undefined);
-    expect(mockApiPush).toHaveBeenCalledWith('test-key', 'es', { hello: 'Hola' }, undefined);
+    expect(mockApiPush).toHaveBeenCalledWith('test-key', 'en', { hello: 'Hello' }, {});
+    expect(mockApiPush).toHaveBeenCalledWith('test-key', 'es', { hello: 'Hola' }, {});
   });
 
   test('prompts for confirmation', async () => {
@@ -208,4 +210,52 @@ describe('push command', () => {
       { 'tag-new': 'from-code' }
     );
   });
+
+  test('uses apiPushAll when experimentalPushAll is enabled via CLI', async () => {
+    const local = { en: { hello: 'Hello' }, es: { hello: 'Hola' } };
+    const remote = { en: {}, es: {} };
+    mockReadFiles.mockResolvedValue(local);
+    mockApiPull.mockResolvedValue(remote);
+    vi.mocked(mockInquirer.prompt).mockResolvedValue({ confirm: true });
+
+    await expect(push({ experimentalPushAll: true }, mockProgram)).rejects.toThrow(ExitError);
+
+    expect(mockApiPushAll).toHaveBeenCalledTimes(1);
+    expect(mockApiPushAll).toHaveBeenCalledWith(
+      'test-key',
+      { en: { hello: 'Hello' }, es: { hello: 'Hola' } },
+      { experimentalPushAll: true }
+    );
+    expect(mockApiPush).not.toHaveBeenCalled();
+  });
+
+  test('uses apiPushAll when experimentalPushAll is enabled via config', async () => {
+    const local = { en: { hello: 'Hello' }, es: { hello: 'Hola' } };
+    const remote = { en: {}, es: {} };
+    mockGetGlobalOptions.mockResolvedValue({
+      ...defaultOptions,
+      push: { experimentalPushAll: true }
+    });
+    mockReadFiles.mockResolvedValue(local);
+    mockApiPull.mockResolvedValue(remote);
+    vi.mocked(mockInquirer.prompt).mockResolvedValue({ confirm: true });
+
+    await expect(push({}, mockProgram)).rejects.toThrow(ExitError);
+
+    expect(mockApiPushAll).toHaveBeenCalledTimes(1);
+    expect(mockApiPush).not.toHaveBeenCalled();
+  });
+
+  test('uses default per-locale push when experimentalPushAll is false', async () => {
+    const local = { en: { hello: 'Hello' }, es: { hello: 'Hola' } };
+    const remote = { en: {}, es: {} };
+    mockReadFiles.mockResolvedValue(local);
+    mockApiPull.mockResolvedValue(remote);
+    vi.mocked(mockInquirer.prompt).mockResolvedValue({ confirm: true });
+
+    await expect(push({}, mockProgram)).rejects.toThrow(ExitError);
+
+    expect(mockApiPush).toHaveBeenCalledTimes(2);
+    expect(mockApiPushAll).not.toHaveBeenCalled();
+  });
 });