Skip to content

The open alternative to Salesforce, designed for AI.

Restore app translation extraction in the standalone CLI (#28014)

Weikoa317016273ac
diff --git a/packages/twenty-cli/docs/commands.md b/packages/twenty-cli/docs/commands.md
index be4c3ae18ac..3bfbdd014b0 100644
--- a/packages/twenty-cli/docs/commands.md
+++ b/packages/twenty-cli/docs/commands.md
@@ -575,3 +575,34 @@ Exit codes:
| 5 | Partial failure |
| 6 | Conflict |
| 130 | Cancelled |
+
+## App translations
+
+```sh
+twenty app translations extract
+twenty app translations extract --locale fr-FR
+twenty app translations extract --path ./apps/billing --json
+```
+
+Use `--path` for an explicit app directory. Without `--path`, the CLI finds the
+app containing the current directory.
+
+Extraction runs locally, without a workspace connection. It reads app metadata
+and static `t`, `msg`, and `Trans` strings in front-component source files. It
+refreshes `locales/en.json` with source strings and updates existing target JSON
+catalogs. `--locale` also creates a missing supported target catalog, for example
+`locales/fr-FR.json`. The source locale `en` cannot be a target.
+
+Translations for unchanged message/context pairs are preserved. New entries have
+empty translations; obsolete entries are removed. Context groups remain separate.
+Malformed target catalogs fail with `INVALID_INPUT` before writing any catalogs.
+Unsafe catalog or staging paths report `APP_PATH_UNAVAILABLE`. Files under
+`locales/compiled` are left untouched. Temporary files live under `.twenty/cli`.
+Each catalog is replaced atomically; an
+interrupted run may update only some catalogs, so rerun extraction to finish.
+
+The command validates app definitions but does not bundle or upload them. Edit
+the target catalogs, then run `twenty app apply` to deploy translations. Build
+and apply already compile translations; no separate compile command is needed.
+JSON output includes the app, source-string count, updated catalog paths and
+diagnostics.
diff --git a/packages/twenty-cli/src/app/create-tooling-failure.ts b/packages/twenty-cli/src/app/create-tooling-failure.ts
index e7116d1c872..6a91e86e655 100644
--- a/packages/twenty-cli/src/app/create-tooling-failure.ts
+++ b/packages/twenty-cli/src/app/create-tooling-failure.ts
@@ -34,6 +34,8 @@ export const createToolingFailure = ({
};
switch (error.code) {
+ case 'INVALID_INPUT':
+ case 'APP_PATH_UNAVAILABLE':
case 'SDK_SOURCE_UNSUPPORTED':
case 'TYPESCRIPT_NOT_INSTALLED':
case 'TOOLING_UNSUPPORTED':
diff --git a/packages/twenty-cli/src/app/run-app-worker.ts b/packages/twenty-cli/src/app/run-app-worker.ts
index 87d63b7624d..fed2cb855b6 100644
--- a/packages/twenty-cli/src/app/run-app-worker.ts
+++ b/packages/twenty-cli/src/app/run-app-worker.ts
@@ -50,6 +50,7 @@ export const runAppWorker = async ({
| 'generateSourceClient'
| 'readSourceIdentity'
| 'buildManifest'
+ | 'extractTranslations'
| 'typecheckSource'
| 'bundleSnapshot'
| 'pull';
diff --git a/packages/twenty-cli/src/app/translations/__tests__/extract-application-translations.spec.ts b/packages/twenty-cli/src/app/translations/__tests__/extract-application-translations.spec.ts
new file mode 100644
index 00000000000..d11ea1f5885
--- /dev/null
+++ b/packages/twenty-cli/src/app/translations/__tests__/extract-application-translations.spec.ts
@@ -0,0 +1,172 @@
+import {
+ mkdir,
+ mkdtemp,
+ readFile,
+ readdir,
+ rm,
+ symlink,
+ writeFile,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { type Manifest } from 'twenty-shared/application';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { extractApplicationTranslations } from '@/app/translations/extract-application-translations';
+
+const MANIFEST = {
+ objects: [{ labelSingular: 'Invoice', labelPlural: 'Invoices' }],
+ fields: [{ label: 'Invoice' }],
+} as unknown as Manifest;
+
+describe('extractApplicationTranslations', () => {
+ let appPath: string;
+ const extract = (options = {}) =>
+ extractApplicationTranslations({
+ appPath,
+ manifest: MANIFEST,
+ signal: new AbortController().signal,
+ ...options,
+ });
+ const readCatalog = async (name: string) =>
+ JSON.parse(await readFile(join(appPath, 'locales', name), 'utf8'));
+
+ beforeEach(async () => {
+ appPath = await mkdtemp(join(tmpdir(), 'twenty-extract-translations-'));
+ });
+ afterEach(() => rm(appPath, { recursive: true, force: true }));
+
+ it('extracts metadata and front-component strings, preserves context-specific translations and removes obsolete entries', async () => {
+ const componentPath = join(appPath, 'panel.tsx');
+ await writeFile(
+ componentPath,
+ `
+ t('Welcome');
+ msg({ message: 'Open', context: 'door' });
+ t({ message: 'Open', context: 'status' });
+ t('Welcome');
+ t(dynamicMessage);
+ <Trans message="Save" />;
+ `,
+ );
+ await mkdir(join(appPath, 'locales/compiled'), { recursive: true });
+ await writeFile(
+ join(appPath, 'locales/fr-FR.json'),
+ JSON.stringify({
+ Welcome: 'Bienvenue',
+ Old: 'Ancien',
+ door: { Open: 'Ouvrir' },
+ status: { Open: 'Ouvert' },
+ 'objectMetadata.labelSingular': { Invoice: 'Facture' },
+ 'fieldMetadata.label': { Invoice: 'Facturation' },
+ }),
+ );
+ await writeFile(
+ join(appPath, 'locales/compiled/fr-FR.json'),
+ '{"opaque":"Preserved"}',
+ );
+
+ const result = await extract({
+ frontComponentSourcePaths: [componentPath],
+ });
+
+ expect(result).toEqual({
+ sourceCount: 7,
+ updatedLocaleFiles: ['locales/en.json', 'locales/fr-FR.json'],
+ });
+ expect(await readCatalog('en.json')).toEqual({
+ Welcome: 'Welcome',
+ Save: 'Save',
+ door: { Open: 'Open' },
+ status: { Open: 'Open' },
+ 'objectMetadata.labelSingular': { Invoice: 'Invoice' },
+ 'objectMetadata.labelPlural': { Invoices: 'Invoices' },
+ 'fieldMetadata.label': { Invoice: 'Invoice' },
+ });
+ expect(await readCatalog('fr-FR.json')).toEqual({
+ Welcome: 'Bienvenue',
+ Save: '',
+ door: { Open: 'Ouvrir' },
+ status: { Open: 'Ouvert' },
+ 'objectMetadata.labelSingular': { Invoice: 'Facture' },
+ 'objectMetadata.labelPlural': { Invoices: '' },
+ 'fieldMetadata.label': { Invoice: 'Facturation' },
+ });
+ expect(await readCatalog('compiled/fr-FR.json')).toEqual({
+ opaque: 'Preserved',
+ });
+ });
+
+ it('scaffolds a target catalog and preserves it on repeated extraction', async () => {
+ await extract({ scaffoldLocale: 'fr-FR' });
+ expect(await readCatalog('fr-FR.json')).toEqual({
+ 'objectMetadata.labelSingular': { Invoice: '' },
+ 'objectMetadata.labelPlural': { Invoices: '' },
+ 'fieldMetadata.label': { Invoice: '' },
+ });
+ await writeFile(
+ join(appPath, 'locales/fr-FR.json'),
+ JSON.stringify({
+ 'objectMetadata.labelSingular': { Invoice: 'Facture' },
+ }),
+ );
+ await extract({ scaffoldLocale: 'fr-FR' });
+ expect(
+ (await readCatalog('fr-FR.json'))['objectMetadata.labelSingular'],
+ ).toEqual({ Invoice: 'Facture' });
+ expect(await readdir(join(appPath, 'locales'))).toEqual([
+ 'en.json',
+ 'fr-FR.json',
+ ]);
+ });
+
+ it.each([
+ '{',
+ 'null',
+ '[]',
+ '{"Invoice":42}',
+ '{"context":{"Invoice":null}}',
+ ])(
+ 'rejects invalid target catalog %s before changing any catalog',
+ async (content) => {
+ await mkdir(join(appPath, 'locales'));
+ await writeFile(join(appPath, 'locales/en.json'), 'original source');
+ await writeFile(join(appPath, 'locales/de-DE.json'), '{"Old":"Alt"}');
+ await writeFile(join(appPath, 'locales/fr-FR.json'), content);
+ await expect(extract()).rejects.toMatchObject({ code: 'INVALID_INPUT' });
+ expect(await readFile(join(appPath, 'locales/en.json'), 'utf8')).toBe(
+ 'original source',
+ );
+ expect(await readCatalog('de-DE.json')).toEqual({ Old: 'Alt' });
+ expect(await readFile(join(appPath, 'locales/fr-FR.json'), 'utf8')).toBe(
+ content,
+ );
+ },
+ );
+
+ it('does not create catalogs when cancelled', async () => {
+ await expect(extract({ signal: AbortSignal.abort() })).rejects.toThrow();
+ expect(await readdir(appPath)).toEqual([]);
+ });
+
+ it('refuses a symlinked staging directory before creating catalogs', async () => {
+ const outside = join(appPath, 'outside');
+ await mkdir(outside);
+ await symlink(outside, join(appPath, '.twenty'));
+
+ await expect(extract()).rejects.toThrow('symbolic links');
+ expect(await readdir(outside)).toEqual([]);
+ expect(await readdir(appPath)).not.toContain('locales');
+ });
+
+ it('refuses a symlinked target catalog without modifying its destination', async () => {
+ const outside = join(appPath, 'outside.json');
+ await writeFile(outside, '{"Keep":"Me"}');
+ await mkdir(join(appPath, 'locales'));
+ await symlink(outside, join(appPath, 'locales/fr-FR.json'));
+ await expect(extract()).rejects.toThrow('symbolic links');
+ expect(await readFile(outside, 'utf8')).toBe('{"Keep":"Me"}');
+ expect(await readdir(join(appPath, 'locales'))).toEqual(['fr-FR.json']);
+ });
+});
diff --git a/packages/twenty-cli/src/app/translations/extract-application-translations.ts b/packages/twenty-cli/src/app/translations/extract-application-translations.ts
new file mode 100644
index 00000000000..4723143dffb
--- /dev/null
+++ b/packages/twenty-cli/src/app/translations/extract-application-translations.ts
@@ -0,0 +1,168 @@
+import { mkdtemp, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { isString } from '@sniptt/guards';
+
+import { type Manifest } from 'twenty-shared/application';
+import { SOURCE_LOCALE, type AppLocale } from 'twenty-shared/translations';
+import { isDefined, isPlainObject } from 'twenty-shared/utils';
+
+import { ensureDir, pathExists, readJson, writeJson } from '@/app/fs-utils';
+import { assertPullPaths } from '@/app/pull/assert-pull-paths';
+import { collectFrontComponentStrings } from '@/app/translations/collect-front-component-strings';
+import { collectTranslatableStrings } from '@/app/translations/collect-translatable-strings';
+import { isLocaleCatalog } from '@/app/translations/is-locale-catalog';
+import { LOCALES_DIR } from '@/app/translations/constants';
+import {
+ buildLocaleCatalog,
+ flattenLocaleCatalog,
+} from '@/app/translations/locale-catalog-format';
+import { getTranslationCatalogKey } from '@/app/translations/message';
+import { CliError } from '@/output/cli-error';
+
+type TranslationCatalog = Record<string, string | Record<string, string>>;
+
+const isTranslationCatalog = (value: unknown): value is TranslationCatalog =>
+ isPlainObject(value) &&
+ Object.values(value).every(
+ (entry) => isString(entry) || isLocaleCatalog(entry),
+ );
+
+const readExistingCatalogOrThrow = async (
+ filePath: string,
+): Promise<TranslationCatalog> => {
+ try {
+ const catalog = await readJson(filePath);
+
+ if (isTranslationCatalog(catalog)) {
+ return catalog;
+ }
+ } catch (error) {
+ throw new CliError({
+ code: 'INVALID_INPUT',
+ message: `Cannot read translation catalog ${filePath}. No catalogs were updated.`,
+ cause: error,
+ });
+ }
+ throw new CliError({
+ code: 'INVALID_INPUT',
+ message: `Invalid translation catalog ${filePath}. Expected messages or context groups with string translations. No catalogs were updated.`,
+ });
+};
+
+export const extractApplicationTranslations = async ({
+ appPath,
+ manifest,
+ frontComponentSourcePaths = [],
+ scaffoldLocale,
+ signal,
+}: {
+ appPath: string;
+ manifest: Manifest;
+ frontComponentSourcePaths?: string[];
+ scaffoldLocale?: AppLocale;
+ signal: AbortSignal;
+}) => {
+ signal.throwIfAborted();
+ const descriptorByKey = new Map(
+ [
+ ...collectTranslatableStrings(manifest),
+ ...(await collectFrontComponentStrings(frontComponentSourcePaths)),
+ ].map((descriptor) => [
+ getTranslationCatalogKey(descriptor.message, descriptor.context),
+ descriptor,
+ ]),
+ );
+ const descriptors = [...descriptorByKey.values()];
+ const localesDir = join(appPath, LOCALES_DIR);
+
+ await assertPullPaths({ appPath, relativePaths: [LOCALES_DIR] });
+ const localeFiles = new Set(
+ ((await pathExists(localesDir)) ? await readdir(localesDir) : []).filter(
+ (entry) => entry.endsWith('.json') && entry !== `${SOURCE_LOCALE}.json`,
+ ),
+ );
+
+ if (isDefined(scaffoldLocale)) {
+ localeFiles.add(`${scaffoldLocale}.json`);
+ }
+
+ const catalogs = new Map([
+ [
+ `${SOURCE_LOCALE}.json`,
+ buildLocaleCatalog(
+ descriptors.map(({ message, context }) => ({
+ message,
+ context,
+ translation: message,
+ })),
+ ),
+ ],
+ ]);
+
+ await assertPullPaths({
+ appPath,
+ relativePaths: [...catalogs.keys(), ...localeFiles].map((name) =>
+ join(LOCALES_DIR, name),
+ ),
+ });
+
+ for (const localeFile of [...localeFiles].sort()) {
+ const filePath = join(localesDir, localeFile);
+ const existing = (await pathExists(filePath))
+ ? await readExistingCatalogOrThrow(filePath)
+ : {};
+ const translationByKey = new Map(
+ flattenLocaleCatalog(existing).map((entry) => [
+ getTranslationCatalogKey(entry.message, entry.context),
+ entry.translation,
+ ]),
+ );
+
+ catalogs.set(
+ localeFile,
+ buildLocaleCatalog(
+ descriptors.map(({ message, context }) => ({
+ message,
+ context,
+ translation:
+ translationByKey.get(getTranslationCatalogKey(message, context)) ??
+ '',
+ })),
+ ),
+ );
+ }
+
+ signal.throwIfAborted();
+ const stagingRoot = join('.twenty', 'cli');
+
+ await assertPullPaths({ appPath, relativePaths: [stagingRoot] });
+ await ensureDir(localesDir);
+ await ensureDir(join(appPath, stagingRoot));
+ const stagingDirectory = await mkdtemp(
+ join(appPath, stagingRoot, 'extract-'),
+ );
+
+ try {
+ for (const [localeFile, catalog] of catalogs) {
+ signal.throwIfAborted();
+ await writeJson(join(stagingDirectory, localeFile), catalog);
+ }
+ for (const localeFile of catalogs.keys()) {
+ signal.throwIfAborted();
+ await rename(
+ join(stagingDirectory, localeFile),
+ join(localesDir, localeFile),
+ );
+ }
+ } finally {
+ await rm(stagingDirectory, { recursive: true, force: true });
+ }
+
+ return {
+ sourceCount: descriptors.length,
+ updatedLocaleFiles: [...catalogs.keys()].map((name) =>
+ join(LOCALES_DIR, name),
+ ),
+ };
+};
diff --git a/packages/twenty-cli/src/app/translations/parse-extraction-locale.ts b/packages/twenty-cli/src/app/translations/parse-extraction-locale.ts
new file mode 100644
index 00000000000..82d0acac647
--- /dev/null
+++ b/packages/twenty-cli/src/app/translations/parse-extraction-locale.ts
@@ -0,0 +1,29 @@
+import {
+ APP_LOCALES,
+ SOURCE_LOCALE,
+ type AppLocale,
+} from 'twenty-shared/translations';
+import { isDefined } from 'twenty-shared/utils';
+
+import { isSupportedLocale } from '@/app/translations/is-supported-locale';
+import { CliError } from '@/output/cli-error';
+import { EXIT_CODE } from '@/output/constants/exit-code.constant';
+
+export const parseExtractionLocale = (
+ locale?: string,
+): AppLocale | undefined => {
+ if (!isDefined(locale)) {
+ return undefined;
+ }
+ if (locale === SOURCE_LOCALE || !isSupportedLocale(locale)) {
+ throw new CliError({
+ code: 'USAGE',
+ exitCode: EXIT_CODE.USAGE,
+ message: `"${locale}" is not a supported target locale.`,
+ hint: `Choose one of: ${Object.keys(APP_LOCALES)
+ .filter((supportedLocale) => supportedLocale !== SOURCE_LOCALE)
+ .join(', ')}.`,
+ });
+ }
+ return locale;
+};
diff --git a/packages/twenty-cli/src/app/types/app-worker-message.type.ts b/packages/twenty-cli/src/app/types/app-worker-message.type.ts
index eab434e1200..2b03ee6735c 100644
--- a/packages/twenty-cli/src/app/types/app-worker-message.type.ts
+++ b/packages/twenty-cli/src/app/types/app-worker-message.type.ts
@@ -5,6 +5,7 @@ export type AppWorkerRequest =
| { type: 'generateSourceClient'; appPath: string; schema: string }
| { type: 'readSourceIdentity'; appPath: string }
| { type: 'buildManifest'; appPath: string }
+ | { type: 'extractTranslations'; appPath: string; locale?: string }
| { type: 'typecheckSource'; appPath: string }
| {
type: 'bundleSnapshot';
diff --git a/packages/twenty-cli/src/app/worker/app-worker.ts b/packages/twenty-cli/src/app/worker/app-worker.ts
index 74da3b39fd4..aebb97ea8f0 100644
--- a/packages/twenty-cli/src/app/worker/app-worker.ts
+++ b/packages/twenty-cli/src/app/worker/app-worker.ts
@@ -80,6 +80,17 @@ const parseRequest = (message: unknown): AppWorkerRequest | undefined => {
};
}
+ if (message.type === 'extractTranslations') {
+ return isNonEmptyString(message.appPath) &&
+ (!isDefined(message.locale) || isString(message.locale))
+ ? {
+ type: 'extractTranslations',
+ appPath: message.appPath,
+ locale: message.locale ?? undefined,
+ }
+ : undefined;
+ }
+
if (message.type === 'generateSourceClient') {
return isNonEmptyString(message.appPath) && isString(message.schema)
? {
@@ -297,6 +308,21 @@ process.on('message', (message: unknown) => {
return;
}
+ if (request.type === 'extractTranslations') {
+ import('@/app/worker/extract-source-translations')
+ .then(async ({ extractSourceTranslations }) => {
+ const result = await extractSourceTranslations({
+ appPath: request.appPath,
+ locale: request.locale,
+ signal: abortController.signal,
+ });
+ respond({ type: 'result', result, isSnapshotHeld: false });
+ })
+ .catch((error: unknown) => respond(toFailure(error)));
+
+ return;
+ }
+
if (request.type === 'buildManifest') {
import('@/app/worker/build-source-manifest')
.then(async ({ buildSourceManifest }) => {
diff --git a/packages/twenty-cli/src/app/worker/extract-source-translations.ts b/packages/twenty-cli/src/app/worker/extract-source-translations.ts
new file mode 100644
index 00000000000..38d1ec94d27
--- /dev/null
+++ b/packages/twenty-cli/src/app/worker/extract-source-translations.ts
@@ -0,0 +1,53 @@
+import { join } from 'node:path';
+
+import { getToolingErrorContext } from '@/app/get-tooling-error-context';
+import { AppPathError } from '@/app/pull/app-path-error';
+import { CliError } from '@/output/cli-error';
+import { extractApplicationTranslations } from '@/app/translations/extract-application-translations';
+import { parseExtractionLocale } from '@/app/translations/parse-extraction-locale';
+import { buildSourceManifest } from '@/app/worker/build-source-manifest';
+
+export const extractSourceTranslations = async ({
+ appPath,
+ locale,
+ signal,
+}: {
+ appPath: string;
+ locale?: string;
+ signal: AbortSignal;
+}) => {
+ const scaffoldLocale = parseExtractionLocale(locale);
+ const result = await buildSourceManifest({ appPath, signal });
+
+ if (!result.success) {
+ return result;
+ }
+
+ try {
+ const data = await extractApplicationTranslations({
+ appPath,
+ manifest: result.data.manifest,
+ frontComponentSourcePaths: result.data.filePaths.frontComponents.map(
+ (relativePath) => join(appPath, relativePath),
+ ),
+ scaffoldLocale,
+ signal,
+ });
+
+ return { success: true as const, data, diagnostics: result.diagnostics };
+ } catch (error) {
+ if (!(error instanceof CliError) && !(error instanceof AppPathError)) {
+ throw error;
+ }
+
+ return {
+ success: false as const,
+ error: {
+ code: error instanceof CliError ? error.code : 'APP_PATH_UNAVAILABLE',
+ message: error.message,
+ ...getToolingErrorContext(error),
+ },
+ diagnostics: result.diagnostics,
+ };
+ }
+};
diff --git a/packages/twenty-cli/src/catalog/command-catalog.ts b/packages/twenty-cli/src/catalog/command-catalog.ts
index 57fe5965658..1c8d0b41724 100644
--- a/packages/twenty-cli/src/catalog/command-catalog.ts
+++ b/packages/twenty-cli/src/catalog/command-catalog.ts
@@ -9,6 +9,7 @@ import { APP_BUILD_COMMAND_DEFINITION } from '@/commands/app/build/app-build.com
import { APP_INIT_COMMAND_DEFINITION } from '@/commands/app/init/app-init.command-definition';
import { APP_PULL_COMMAND_DEFINITION } from '@/commands/app/pull/app-pull.command-definition';
import { APP_PLAN_COMMAND_DEFINITION } from '@/commands/app/plan/app-plan.command-definition';
+import { APP_TRANSLATIONS_EXTRACT_COMMAND_DEFINITION } from '@/commands/app/translations/extract/app-translations-extract.command-definition';
import { APP_TYPECHECK_COMMAND_DEFINITION } from '@/commands/app/typecheck/app-typecheck.command-definition';
import { APP_UNINSTALL_COMMAND_DEFINITION } from '@/commands/app/uninstall/app-uninstall.command-definition';
import { AUTH_LOGIN_COMMAND_DEFINITION } from '@/commands/auth/login/auth-login.command-definition';
@@ -43,6 +44,7 @@ export const COMMAND_CATALOG: CommandDefinition[] = [
APP_INIT_COMMAND_DEFINITION,
APP_PLAN_COMMAND_DEFINITION,
APP_PULL_COMMAND_DEFINITION,
+ APP_TRANSLATIONS_EXTRACT_COMMAND_DEFINITION,
APP_TYPECHECK_COMMAND_DEFINITION,
APP_UNINSTALL_COMMAND_DEFINITION,
AUTH_LOGIN_COMMAND_DEFINITION,
diff --git a/packages/twenty-cli/src/catalog/command-topics.ts b/packages/twenty-cli/src/catalog/command-topics.ts
index 0d4f532f1cf..59ac2dabae6 100644
--- a/packages/twenty-cli/src/catalog/command-topics.ts
+++ b/packages/twenty-cli/src/catalog/command-topics.ts
@@ -7,6 +7,10 @@ export const COMMAND_TOPICS: CommandTopicDefinition[] = [
description: 'Create, develop and manage applications',
helpGroup: HELP_GROUP.APP,
},
+ {
+ path: ['app', 'translations'],
+ description: 'Manage app translation catalogs',
+ },
{
path: ['data'],
description: 'Read workspace records',
diff --git a/packages/twenty-cli/src/commands/app/__tests__/app-translations-extract.spec.ts b/packages/twenty-cli/src/commands/app/__tests__/app-translations-extract.spec.ts
new file mode 100644
index 00000000000..1d894a0109d
--- /dev/null
+++ b/packages/twenty-cli/src/commands/app/__tests__/app-translations-extract.spec.ts
@@ -0,0 +1,180 @@
+import {
+ cp,
+ mkdir,
+ mkdtemp,
+ readFile,
+ readdir,
+ rm,
+ symlink,
+ writeFile,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+ afterAll,
+ afterEach,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ it,
+ vi,
+} from 'vitest';
+
+import {
+ parseSingleJsonLine,
+ runCliForTest,
+} from '@/__tests__/utils/run-cli-for-test';
+import { buildTestAppWorker } from '@/app/__tests__/utils/build-test-app-worker';
+
+const worker = vi.hoisted(() => ({ modulePath: '', execArgv: [] as string[] }));
+vi.mock('@/app/get-app-worker-launch', () => ({
+ getAppWorkerLaunch: () => worker,
+}));
+
+const REPOSITORY_ROOT = fileURLToPath(
+ new URL('../../../../../../', import.meta.url),
+);
+
+describe('app translations extract', () => {
+ let workerDirectory: string;
+ let appPath: string;
+ const run = (args: string[] = []) =>
+ runCliForTest(['app', 'translations', 'extract', ...args]);
+
+ beforeAll(async () => {
+ workerDirectory = await mkdtemp(
+ join(tmpdir(), 'twenty-translation-worker-'),
+ );
+ await buildTestAppWorker(workerDirectory);
+ worker.modulePath = join(workerDirectory, 'app-worker.cjs');
+ }, 60_000);
+ afterAll(() => rm(workerDirectory, { recursive: true, force: true }));
+
+ beforeEach(async () => {
+ appPath = await mkdtemp(join(tmpdir(), 'twenty-translation-app-'));
+ await cp(
+ join(REPOSITORY_ROOT, 'packages/twenty-apps/fixtures/minimal-app'),
+ appPath,
+ {
+ recursive: true,
+ filter: (source) =>
+ !source
+ .split('/')
+ .some((part) => ['node_modules', '.twenty', 'dist'].includes(part)),
+ },
+ );
+ await symlink(
+ join(REPOSITORY_ROOT, 'node_modules'),
+ join(appPath, 'node_modules'),
+ );
+ vi.spyOn(process, 'cwd').mockReturnValue(appPath);
+ });
+ afterEach(async () => {
+ vi.restoreAllMocks();
+ await rm(appPath, { recursive: true, force: true });
+ });
+
+ it('runs the real worker offline, emits JSON, scaffolds a locale and extracts front-component messages', async () => {
+ const componentPath = join(appPath, 'my.front-component.tsx');
+ const source = await readFile(componentPath, 'utf8');
+ await writeFile(
+ componentPath,
+ source.replace('<h2>My Component</h2>', '<h2>{t("Welcome")}</h2>'),
+ );
+ const result = await run(['--locale', 'fr-FR', '--json']);
+ expect(result.exitCode, result.stdout + result.stderr).toBe(0);
+ const envelope = parseSingleJsonLine(result.stdout);
+ expect(envelope.data).toMatchObject({
+ app: { name: 'minimal-app', path: appPath },
+ updatedLocaleFiles: ['locales/en.json', 'locales/fr-FR.json'],
+ });
+ expect(
+ JSON.parse(await readFile(join(appPath, 'locales/en.json'), 'utf8')),
+ ).toMatchObject({
+ Welcome: 'Welcome',
+ 'objectMetadata.labelSingular': { 'My note': 'My note' },
+ });
+ expect(
+ JSON.parse(await readFile(join(appPath, 'locales/fr-FR.json'), 'utf8')),
+ ).toMatchObject({ Welcome: '' });
+ expect(await readdir(appPath)).not.toContain('dist');
+ }, 30_000);
+
+ it('discovers the containing app from a nested directory and honors --path', async () => {
+ const nested = join(appPath, 'src/nested');
+ await mkdir(nested, { recursive: true });
+ vi.spyOn(process, 'cwd').mockReturnValue(nested);
+ const result = await run();
+ expect(result.exitCode, result.stderr).toBe(0);
+ expect(result.stdout).toContain('strings to locales/');
+ vi.spyOn(process, 'cwd').mockReturnValue(tmpdir());
+ expect((await run(['--path', appPath])).exitCode).toBe(0);
+ }, 30_000);
+
+ it.each(['en', 'fr', '../outside', 'constructor'])(
+ 'rejects locale %s before loading app source',
+ async (locale) => {
+ await writeFile(
+ join(appPath, 'application.config.ts'),
+ 'throw new Error("must not load");',
+ );
+ const result = await run(['--locale', locale, '--json']);
+ expect(result.exitCode).toBe(2);
+ expect(parseSingleJsonLine(result.stdout).error.code).toBe('USAGE');
+ expect(await readdir(appPath)).not.toContain('locales');
+ },
+ );
+
+ it('reports manifest validation errors without writing catalogs', async () => {
+ await writeFile(
+ join(appPath, 'application.config.ts'),
+ 'throw new Error("bad app definition");',
+ );
+ const result = await run(['--json']);
+ expect(result.exitCode).toBe(1);
+ expect(parseSingleJsonLine(result.stdout).error.code).toBe('BUILD_FAILED');
+ expect(await readdir(appPath)).not.toContain('locales');
+ }, 30_000);
+
+ it('surfaces malformed existing catalogs without overwriting them', async () => {
+ await mkdir(join(appPath, 'locales'));
+ await writeFile(join(appPath, 'locales/fr-FR.json'), '{');
+ const result = await run(['--json']);
+ expect(result.exitCode).toBe(1);
+ expect(parseSingleJsonLine(result.stdout).error).toMatchObject({
+ code: 'INVALID_INPUT',
+ message: expect.stringContaining('Cannot read translation catalog'),
+ });
+ expect(await readdir(join(appPath, 'locales'))).toEqual(['fr-FR.json']);
+ expect(await readFile(join(appPath, 'locales/fr-FR.json'), 'utf8')).toBe(
+ '{',
+ );
+ }, 30_000);
+
+ it('reports an unsafe catalog path as APP_PATH_UNAVAILABLE', async () => {
+ const outside = join(appPath, 'outside');
+ await mkdir(outside);
+ await symlink(outside, join(appPath, 'locales'));
+
+ const result = await run(['--json']);
+
+ expect(result.exitCode).toBe(1);
+ expect(parseSingleJsonLine(result.stdout).error).toMatchObject({
+ code: 'APP_PATH_UNAVAILABLE',
+ message: expect.stringContaining('Cannot follow symbolic links'),
+ });
+ expect(await readdir(outside)).toEqual([]);
+ }, 30_000);
+
+ it('advertises extraction in topic help and machine-readable command discovery', async () => {
+ const help = await runCliForTest(['app', 'translations', '--help']);
+ expect(help.stdout).toContain('extract');
+ const commands = await runCliForTest(['commands', '--json']);
+ expect(commands.stdout).toContain(
+ 'Extract app strings and update translation catalogs',
+ );
+ });
+});
diff --git a/packages/twenty-cli/src/commands/app/translations/extract/app-translations-extract.command-definition.ts b/packages/twenty-cli/src/commands/app/translations/extract/app-translations-extract.command-definition.ts
new file mode 100644
index 00000000000..9e830ec93f9
--- /dev/null
+++ b/packages/twenty-cli/src/commands/app/translations/extract/app-translations-extract.command-definition.ts
@@ -0,0 +1,32 @@
+import { type LocalCommandDefinition } from '@/catalog/types/command-definition.type';
+
+export const APP_TRANSLATIONS_EXTRACT_COMMAND_DEFINITION: LocalCommandDefinition =
+ {
+ path: ['app', 'translations', 'extract'],
+ description: 'Extract app strings and update translation catalogs',
+ options: [
+ {
+ flags: '--path <directory>',
+ description:
+ 'App directory (default: the app containing the current folder)',
+ },
+ {
+ flags: '--locale <locale>',
+ description:
+ 'Create a target locale catalog if missing, for example fr-FR',
+ },
+ ],
+ examples: [
+ 'twenty app translations extract',
+ 'twenty app translations extract --locale fr-FR',
+ 'twenty app translations extract --path ./apps/billing --json',
+ ],
+ outputModes: ['human', 'json'],
+ writes: true,
+ needsProject: true,
+ needsTarget: false,
+ load: async () =>
+ (
+ await import('@/commands/app/translations/extract/run-app-translations-extract-command')
+ ).runAppTranslationsExtractCommand,
+ };
diff --git a/packages/twenty-cli/src/commands/app/translations/extract/run-app-translations-extract-command.ts b/packages/twenty-cli/src/commands/app/translations/extract/run-app-translations-extract-command.ts
new file mode 100644
index 00000000000..9a3843940a9
--- /dev/null
+++ b/packages/twenty-cli/src/commands/app/translations/extract/run-app-translations-extract-command.ts
@@ -0,0 +1,76 @@
+import { isArray, isNumber, isString } from '@sniptt/guards';
+import { isPlainObject } from 'twenty-shared/utils';
+
+import { createToolingFailure } from '@/app/create-tooling-failure';
+import { formatToolingDiagnostic } from '@/app/format-tooling-diagnostic';
+import { parseToolingResult } from '@/app/parse-tooling-result';
+import { resolveAppProject } from '@/app/project/resolve-app-project';
+import { resolveSourceSdk } from '@/app/project/resolve-source-sdk';
+import { runAppWorker } from '@/app/run-app-worker';
+import { toWorkerOutputDiagnostics } from '@/app/to-worker-output-diagnostics';
+import { parseExtractionLocale } from '@/app/translations/parse-extraction-locale';
+import { readStringOption } from '@/catalog/read-command-values';
+import { type CommandRun } from '@/catalog/types/command-run.type';
+import { formatSuccessLine } from '@/output/style';
+
+export const runAppTranslationsExtractCommand: CommandRun = async (context) => {
+ const { options, output, outputMode, signal } = context;
+ const locale = parseExtractionLocale(readStringOption(options, 'locale'));
+ const project = await resolveAppProject({
+ explicitPath: readStringOption(options, 'path'),
+ workingDirectory: process.cwd(),
+ });
+ const sdk = await resolveSourceSdk({ appPath: project.path });
+
+ output.progress(`Extracting translatable strings from ${project.name}…`);
+ const worker = await runAppWorker({
+ request: { type: 'extractTranslations', appPath: project.path, locale },
+ signal,
+ });
+ const result = parseToolingResult({
+ value: worker.result,
+ parseData: (value) => {
+ if (
+ !isPlainObject(value) ||
+ !isNumber(value.sourceCount) ||
+ !isArray(value.updatedLocaleFiles) ||
+ !value.updatedLocaleFiles.every(isString)
+ ) {
+ return;
+ }
+ return {
+ data: {
+ sourceCount: value.sourceCount,
+ updatedLocaleFiles: value.updatedLocaleFiles,
+ },
+ };
+ },
+ });
+ const diagnostics = [
+ ...result.diagnostics,
+ ...toWorkerOutputDiagnostics(worker.output),
+ ];
+
+ if (outputMode === 'human') {
+ for (const diagnostic of diagnostics) {
+ output.progress(formatToolingDiagnostic(diagnostic));
+ }
+ }
+ if (!result.success) {
+ throw createToolingFailure({
+ error: result.error,
+ diagnostics,
+ sdkVersion: sdk.version,
+ });
+ }
+
+ return {
+ data: { app: project, ...result.data, diagnostics },
+ human: [
+ formatSuccessLine(
+ `Extracted ${result.data.sourceCount} ${result.data.sourceCount === 1 ? 'string' : 'strings'} to locales/`,
+ ),
+ `Updated: ${result.data.updatedLocaleFiles.join(', ')}`,
+ ].join('\n'),
+ };
+};