The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
feat(sdk): translate front-component strings with t()/Trans/useTranslate (#22301)
Félix Malfait55ed4b7adb3c
diff --git a/packages/twenty-docs/developers/extend/apps/translations/overview.mdx b/packages/twenty-docs/developers/extend/apps/translations/overview.mdxnew file mode 100644index 00000000000..0981690c147--- /dev/null+++ b/packages/twenty-docs/developers/extend/apps/translations/overview.mdx@@ -0,0 +1,125 @@+---+title: Translations+description: Ship your app in multiple languages — translate manifest labels and UI strings through one locales catalog.+icon: "language"+---++Twenty apps are authored in **English**: the strings in your source and manifest+are the English source text, `en` is the source locale you translate *from*, and+any locale left untranslated falls back to it.++Your app has two kinds of translatable text, and both flow through the same+`locales/` catalog:++- **Manifest labels** — object and field names, view titles, menu items, and+ other strings declared in your app's metadata.+- **Front-component strings** — the UI text your React front components render.++You mark the translatable strings, extract them into per-locale catalogs,+translate those catalogs, and the build serves the right language for the+current user — no extra wiring.++## Marking front-component strings++Import the translation helpers from `twenty-sdk/front-component`:++```tsx+import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';++const STATUSES = [+ { id: 'draft', label: msg('Draft') },+ { id: 'sent', label: msg('Sent') },+];++const Card = ({ count, name }: { count: number; name: string }) => {+ const { t } = useTranslate();++ return (+ <section>+ {/* Static text — reactive to the user's locale */}+ <Trans>Loading postcard…</Trans>++ {/* Disambiguate identical sources with a context */}+ <Trans context="card-title">Untitled</Trans>++ {/* Interpolation: pass values explicitly */}+ <p>{t('Hi {name}', { name })}</p>+ <p>{t('Saved {count} cards', { count })}</p>++ {/* Resolve a lazily-declared descriptor */}+ <ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>+ </section>+ );+};+```++### When to use which++- **`<Trans>…</Trans>`** — static text in JSX. Use the `message` and `values`+ props for interpolation (`<Trans message="Hi {name}" values={{ name }} />`);+ interpolating directly in the children is not statically extractable.+- **`useTranslate().t`** — dynamic strings inside a component. Re-renders when the+ user switches language. Prefer this inside render.+- **`t(...)`** (imported directly) — eager translation usable **anywhere**,+ including event handlers, helpers, and module scope — not only inside render.+- **`msg(...)`** — a lazy descriptor for strings declared as data (constants,+ config). Resolve it later with `t(descriptor)`.++### Context++Pass `context` to disambiguate identical source strings that translate+differently:++```tsx+t({ message: 'Open', context: 'door' });+t({ message: 'Open', context: 'window' });+<Trans context="card-title">Untitled</Trans>+```++## Extracting and translating++Run the extract command from your app directory:++```bash+twenty dev:translations-extract # collect strings into locales/en.json+twenty dev:translations-extract --locale fr-FR # also scaffold a target locale+```++Extraction collects both your manifest labels and the `t()`/`msg()`/`<Trans>`+strings from your front-component source into `locales/<locale>.json`, keyed by+source string. Fill in the translations:++```json+// locales/fr-FR.json+{+ "Loading postcard…": "Chargement de la carte…",+ "Hi {name}": "Bonjour {name}",+ "Saved {count} cards": "{count} cartes enregistrées"+}+```++Placeholders like `{name}` are substituted at runtime — keep them in the+translation. Any string left empty falls back to the source text.++## How it runs++`twenty dev:build` compiles the catalogs and serves the right language for the+current user: manifest labels are resolved server-side, and front-component+catalogs are baked into each component bundle. At runtime a component reads the+locale from its execution context (the host's current language) and resolves+each string against its catalog, falling back to the source when a translation+is missing. Switching language in the host re-renders `<Trans>` and+`useTranslate().t` strings live.++Because catalogs are compiled at build time, updating a translation means+re-running `twenty dev:build` (and redeploying), the same as any other change.++<Note>+Translations are compiled by `twenty dev:build` (and `twenty apply`). The+continuous `twenty dev` watch shows source strings, so test localized output+with a one-off build.+</Note>++`<Trans>` text children may span multiple lines — whitespace is collapsed the+same way JSX collapses it, so `<Trans>Welcome\n back</Trans>` and the extracted+key both become `Welcome back`.diff --git a/packages/twenty-docs/docs.json b/packages/twenty-docs/docs.jsonindex 729cd974ba7..21351e52e66 100644--- a/packages/twenty-docs/docs.json+++ b/packages/twenty-docs/docs.json@@ -434,6 +434,12 @@"developers/extend/apps/operations/testing","developers/extend/apps/operations/publishing"]+ },+ {+ "group": "Translations",+ "pages": [+ "developers/extend/apps/translations/overview"+ ]}]},diff --git a/packages/twenty-docs/navigation/base-structure.json b/packages/twenty-docs/navigation/base-structure.jsonindex b22261b39ab..0da72673160 100644--- a/packages/twenty-docs/navigation/base-structure.json+++ b/packages/twenty-docs/navigation/base-structure.json@@ -436,6 +436,13 @@"developers/extend/apps/operations/testing","developers/extend/apps/operations/publishing"]+ },+ {+ "key": "appsTranslations",+ "label": "Translations",+ "pages": [+ "developers/extend/apps/translations/overview"+ ]}]},diff --git a/packages/twenty-docs/navigation/navigation.template.json b/packages/twenty-docs/navigation/navigation.template.jsonindex 9ac96e330fc..99f5ef4df9e 100644--- a/packages/twenty-docs/navigation/navigation.template.json+++ b/packages/twenty-docs/navigation/navigation.template.json@@ -174,6 +174,9 @@},"appsOperations": {"label": "Operations"+ },+ "appsTranslations": {+ "label": "Translations"}}},diff --git a/packages/twenty-front-component-renderer/src/types/FrontComponentExecutionContext.ts b/packages/twenty-front-component-renderer/src/types/FrontComponentExecutionContext.tsindex 67771ad1e54..660956c839c 100644--- a/packages/twenty-front-component-renderer/src/types/FrontComponentExecutionContext.ts+++ b/packages/twenty-front-component-renderer/src/types/FrontComponentExecutionContext.ts@@ -1,3 +1,5 @@+import { type AppLocale } from 'twenty-shared/translations';+export type FrontComponentExecutionContext = {frontComponentId: string;userId: string | null;@@ -9,5 +11,5 @@ export type FrontComponentExecutionContext = {selectedRecordIds: string[];/** Resolved color scheme of the host UI ('System' is already resolved) */colorScheme: 'light' | 'dark';- locale?: string;+ locale?: AppLocale;};diff --git a/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx b/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsxindex cc072aacdb1..f0fceeb8238 100644--- a/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx+++ b/packages/twenty-front/src/modules/front-components/hooks/__tests__/useFrontComponentExecutionContext.test.tsx@@ -3,6 +3,7 @@ import { I18nProvider } from '@lingui/react';import { act, renderHook } from '@testing-library/react';import { getDefaultStore } from 'jotai';import { AppPath, SidePanelPages } from 'twenty-shared/types';+import { type AppLocale } from 'twenty-shared/translations';import { MAIN_CONTEXT_STORE_INSTANCE_ID } from '@/context-store/constants/MainContextStoreInstanceId';import { contextStoreRecordShowParentViewComponentState } from '@/context-store/states/contextStoreRecordShowParentViewComponentState';@@ -180,7 +181,7 @@ describe('useFrontComponentExecutionContext', () => {recordId: 'record-456',selectedRecordIds: ['record-456'],colorScheme: 'light',- locale: i18n.locale,+ locale: i18n.locale as AppLocale,});});@@ -196,7 +197,7 @@ describe('useFrontComponentExecutionContext', () => {recordId: null,selectedRecordIds: ['record-1', 'record-2', 'record-3'],colorScheme: 'light',- locale: i18n.locale,+ locale: i18n.locale as AppLocale,});});diff --git a/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts b/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.tsindex 79dfddba1cf..24151d2b6c1 100644--- a/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts+++ b/packages/twenty-front/src/modules/front-components/hooks/useFrontComponentExecutionContext.ts@@ -11,6 +11,7 @@ import {SidePanelPages,type EnqueueSnackbarParams,} from 'twenty-shared/types';+import { type AppLocale } from 'twenty-shared/translations';import { currentUserState } from '@/auth/states/currentUserState';import { useCommandMenuConfirmationModal } from '@/command-menu-item/confirmation-modal/hooks/useCommandMenuConfirmationModal';@@ -252,7 +253,9 @@ export const useFrontComponentExecutionContext = ({recordId: selectedRecordIds?.length === 1 ? selectedRecordIds[0] : null,selectedRecordIds: selectedRecordIds ?? [],colorScheme,- locale: i18n.locale,+ // i18n.locale is a Lingui string; the host is always configured with the+ // APP_LOCALES set, so it is a valid AppLocale.+ locale: i18n.locale as AppLocale,};const unmountFrontComponent: FrontComponentHostCommunicationApi['unmountFrontComponent'] =diff --git a/packages/twenty-sdk/src/cli/commands/dev/index.ts b/packages/twenty-sdk/src/cli/commands/dev/index.tsindex 4067b618639..1813640144c 100644--- a/packages/twenty-sdk/src/cli/commands/dev/index.ts+++ b/packages/twenty-sdk/src/cli/commands/dev/index.ts@@ -8,7 +8,7 @@ import { AppDevCommand } from './dev';import { AppDevOnceCommand } from './dev-once';import { registerDevFunctionCommands } from './function';import { AppGenerateClientCommand } from './generate-client';-import { AppI18nExtractCommand } from './i18n-extract';+import { AppTranslationsExtractCommand } from './translations-extract';import { AppTypecheckCommand } from './typecheck';export const registerDevCommands = (program: Command): void => {@@ -18,7 +18,7 @@ export const registerDevCommands = (program: Command): void => {const typecheckCommand = new AppTypecheckCommand();const addCommand = new EntityAddCommand();const generateClientCommand = new AppGenerateClientCommand();- const i18nExtractCommand = new AppI18nExtractCommand();+ const translationsExtractCommand = new AppTranslationsExtractCommand();const devAction = async (appPath: string | undefined,@@ -178,14 +178,14 @@ export const registerDevCommands = (program: Command): void => {});program- .command('dev:i18n-extract [appPath]')+ .command('dev:translations-extract [appPath]').description('Extract translatable strings into locales/ catalogs').option('--locale <locale>','Scaffold an empty catalog for a target locale (e.g. fr-FR)',).action(async (appPath, options) => {- await i18nExtractCommand.execute({+ await translationsExtractCommand.execute({appPath: formatPath(appPath),locale: options.locale,});diff --git a/packages/twenty-sdk/src/cli/commands/dev/i18n-extract.ts b/packages/twenty-sdk/src/cli/commands/dev/translations-extract.tssimilarity index 82%rename from packages/twenty-sdk/src/cli/commands/dev/i18n-extract.tsrename to packages/twenty-sdk/src/cli/commands/dev/translations-extract.tsindex 4ce066e7d76..3bf5e9f1d71 100644--- a/packages/twenty-sdk/src/cli/commands/dev/i18n-extract.ts+++ b/packages/twenty-sdk/src/cli/commands/dev/translations-extract.ts@@ -1,14 +1,17 @@+import path from 'path';++import chalk from 'chalk';+import { buildAndValidateManifest } from '@/cli/utilities/build/manifest/build-and-validate-manifest';import { CURRENT_EXECUTION_DIRECTORY } from '@/cli/utilities/config/current-execution-directory';-import { extractApplicationTranslations } from '@/cli/utilities/i18n/extract-application-translations';-import chalk from 'chalk';+import { extractApplicationTranslations } from '@/cli/utilities/translations/extract-application-translations';import {APP_LOCALES,SOURCE_LOCALE,type AppLocale,} from 'twenty-shared/translations';-export type AppI18nExtractOptions = {+type AppTranslationsExtractOptions = {appPath?: string;locale?: string;};@@ -16,8 +19,8 @@ export type AppI18nExtractOptions = {const isSupportedLocale = (locale: string): locale is AppLocale =>Object.prototype.hasOwnProperty.call(APP_LOCALES, locale);-export class AppI18nExtractCommand {- async execute(options: AppI18nExtractOptions): Promise<void> {+export class AppTranslationsExtractCommand {+ async execute(options: AppTranslationsExtractOptions): Promise<void> {const appPath = options.appPath ?? CURRENT_EXECUTION_DIRECTORY;let scaffoldLocale: AppLocale | undefined;@@ -55,10 +58,16 @@ export class AppI18nExtractCommand {console.warn(chalk.yellow(manifestResult.warnings.join('\n')));}+ const frontComponentSourcePaths =+ manifestResult.filePaths.frontComponents.map((relativePath) =>+ path.join(appPath, relativePath),+ );+const { sourceCount, updatedLocaleFiles } =await extractApplicationTranslations({appPath,manifest: manifestResult.manifest,+ frontComponentSourcePaths,scaffoldLocale,});diff --git a/packages/twenty-sdk/src/cli/operations/build.ts b/packages/twenty-sdk/src/cli/operations/build.tsindex 3691d836605..cbab2227b45 100644--- a/packages/twenty-sdk/src/cli/operations/build.ts+++ b/packages/twenty-sdk/src/cli/operations/build.ts@@ -7,7 +7,7 @@ import { runTypecheck } from '@/cli/utilities/build/common/typecheck-plugin';import { buildAndValidateManifest } from '@/cli/utilities/build/manifest/build-and-validate-manifest';import { manifestUpdateChecksums } from '@/cli/utilities/build/manifest/manifest-update-checksums';import { writeManifestToOutput } from '@/cli/utilities/build/manifest/manifest-writer';-import { compileApplicationTranslations } from '@/cli/utilities/i18n/compile-application-translations';+import { compileApplicationTranslations } from '@/cli/utilities/translations/compile-application-translations';import { runSafe } from '@/cli/utilities/run-safe';import { APP_ERROR_CODES, type CommandResult } from '@/cli/types';diff --git a/packages/twenty-sdk/src/cli/utilities/build/common/build-application.ts b/packages/twenty-sdk/src/cli/utilities/build/common/build-application.tsindex 4ae37d6b83a..e30b972e82c 100644--- a/packages/twenty-sdk/src/cli/utilities/build/common/build-application.ts+++ b/packages/twenty-sdk/src/cli/utilities/build/common/build-application.ts@@ -16,6 +16,7 @@ import { getFrontComponentBuildPlugins } from '@/cli/utilities/build/common/fronimport { createStubTwentySdkDefinePlugin } from '@/cli/utilities/build/common/plugins/stub-twenty-sdk-define.plugin';import { type OnFileBuiltCallback } from '@/cli/utilities/build/common/restartable-watcher-interface';import { type EntityFilePaths } from '@/cli/utilities/build/manifest/manifest-extract-config';+import { loadFrontComponentTranslationCatalogs } from '@/cli/utilities/translations/load-front-component-translation-catalogs';import {copy,emptyDir,@@ -23,6 +24,7 @@ import {pathExists,pathExistsSync,} from '@/cli/utilities/file/fs-utils';+import { FRONT_COMPONENT_TRANSLATIONS_KEY } from '@/sdk/front-component/constants/front-component-translations-key';export type AppBuildOptions = {appPath: string;@@ -65,6 +67,23 @@ export const buildApplication = async (const { logicFunctions, frontComponents } = options.filePaths;+ // Bake the app's compiled translation catalogs into every front-component+ // bundle so the runtime t()/<Trans> resolves them in the sandboxed worker+ // without a server round-trip. Omitted entirely when the app has no+ // translations, leaving the runtime to fall back to source strings.+ const frontComponentTranslationCatalogs =+ await loadFrontComponentTranslationCatalogs(options.appPath);++ const frontComponentTranslationsBanner = Object.keys(+ frontComponentTranslationCatalogs,+ ).length+ ? {+ js: `globalThis[${JSON.stringify(FRONT_COMPONENT_TRANSLATIONS_KEY)}]=${JSON.stringify(+ frontComponentTranslationCatalogs,+ )};`,+ }+ : undefined;+await esbuildOneShotBuild({appPath: options.appPath,sourcePaths: logicFunctions,@@ -99,6 +118,9 @@ export const buildApplication = async (sourcemap: true,metafile: true,logLevel: 'silent',+ ...(frontComponentTranslationsBanner !== undefined+ ? { banner: frontComponentTranslationsBanner }+ : {}),plugins: [...getFrontComponentBuildPlugins(),createStubTwentySdkDefinePlugin(),diff --git a/packages/twenty-sdk/src/cli/utilities/i18n/extract-application-translations.ts b/packages/twenty-sdk/src/cli/utilities/i18n/extract-application-translations.tsdeleted file mode 100644index 66a0091d9e1..00000000000--- a/packages/twenty-sdk/src/cli/utilities/i18n/extract-application-translations.ts+++ /dev/null@@ -1,75 +0,0 @@-import { readdir } from 'node:fs/promises';-import path from 'path';--import {- ensureDir,- pathExists,- readJson,- writeJson,-} from '@/cli/utilities/file/fs-utils';-import { collectTranslatableStrings } from '@/cli/utilities/i18n/collect-translatable-strings';-import { LOCALES_DIR } from '@/cli/utilities/i18n/constants';-import { type Manifest } from 'twenty-shared/application';-import { SOURCE_LOCALE, type AppLocale } from 'twenty-shared/translations';--export type ExtractApplicationTranslationsResult = {- sourceCount: number;- updatedLocaleFiles: string[];-};--export const extractApplicationTranslations = async ({- appPath,- manifest,- scaffoldLocale,-}: {- appPath: string;- manifest: Manifest;- scaffoldLocale?: AppLocale;-}): Promise<ExtractApplicationTranslationsResult> => {- const sources = collectTranslatableStrings(manifest);- const localesDir = path.join(appPath, LOCALES_DIR);-- await ensureDir(localesDir);-- const sourceCatalog: Record<string, string> = {};-- for (const source of sources) {- sourceCatalog[source] = source;- }-- await writeJson(- path.join(localesDir, `${SOURCE_LOCALE}.json`),- sourceCatalog,- );-- // Create an empty catalog for a brand-new locale so the merge step below- // populates it with the current source keys.- if (scaffoldLocale !== undefined && scaffoldLocale !== SOURCE_LOCALE) {- const scaffoldPath = path.join(localesDir, `${scaffoldLocale}.json`);-- if (!(await pathExists(scaffoldPath))) {- await writeJson(scaffoldPath, {});- }- }-- const existingLocaleFiles = (await readdir(localesDir)).filter(- (entry) => entry.endsWith('.json') && entry !== `${SOURCE_LOCALE}.json`,- );-- for (const localeFile of existingLocaleFiles) {- const filePath = path.join(localesDir, localeFile);- const existing = (await readJson<Record<string, string>>(filePath)) ?? {};- const merged: Record<string, string> = {};-- for (const source of sources) {- merged[source] = existing[source] ?? '';- }-- await writeJson(filePath, merged);- }-- return {- sourceCount: sources.length,- updatedLocaleFiles: existingLocaleFiles,- };-};diff --git a/packages/twenty-sdk/src/cli/utilities/i18n/__tests__/application-translations.spec.ts b/packages/twenty-sdk/src/cli/utilities/translations/__tests__/application-translations.spec.tssimilarity index 69%rename from packages/twenty-sdk/src/cli/utilities/i18n/__tests__/application-translations.spec.tsrename to packages/twenty-sdk/src/cli/utilities/translations/__tests__/application-translations.spec.tsindex 5cca0975744..9c609e38b4d 100644--- a/packages/twenty-sdk/src/cli/utilities/i18n/__tests__/application-translations.spec.ts+++ b/packages/twenty-sdk/src/cli/utilities/translations/__tests__/application-translations.spec.ts@@ -4,9 +4,10 @@ import { join } from 'node:path';import { describe, expect, it } from 'vitest';-import { collectTranslatableStrings } from '@/cli/utilities/i18n/collect-translatable-strings';-import { compileApplicationTranslations } from '@/cli/utilities/i18n/compile-application-translations';-import { generateMessageId } from '@/cli/utilities/i18n/generate-message-id';+import { getTranslationCatalogKey } from '@/sdk/front-component/translations/message';+import { collectTranslatableStrings } from '@/cli/utilities/translations/collect-translatable-strings';+import { compileApplicationTranslations } from '@/cli/utilities/translations/compile-application-translations';+import { generateMessageId } from '@/cli/utilities/translations/generate-message-id';import { type Manifest } from 'twenty-shared/application';const buildManifest = (overrides: Record<string, unknown>): Manifest =>@@ -64,7 +65,7 @@ describe('collectTranslatableStrings', () => {describe('compileApplicationTranslations', () => {it('compiles catalogs keyed by message id, skipping source locale and empty values', async () => {- const appPath = await mkdtemp(join(tmpdir(), 'twenty-i18n-'));+ const appPath = await mkdtemp(join(tmpdir(), 'twenty-translations-'));const localesDir = join(appPath, 'locales');await mkdir(localesDir, { recursive: true });@@ -84,8 +85,29 @@ describe('compileApplicationTranslations', () => {});});+ it('hashes a context-qualified key with its context so it matches the server lookup', async () => {+ const appPath = await mkdtemp(+ join(tmpdir(), 'twenty-translations-context-'),+ );+ const localesDir = join(appPath, 'locales');++ await mkdir(localesDir, { recursive: true });+ await writeFile(+ join(localesDir, 'fr-FR.json'),+ JSON.stringify({+ [getTranslationCatalogKey('Open', 'door')]: 'Ouvrir',+ }),+ );++ const result = await compileApplicationTranslations(appPath);++ expect(result).toEqual({+ 'fr-FR': { [generateMessageId('Open', 'door')]: 'Ouvrir' },+ });+ });+it('returns undefined when there is no locales directory', async () => {- const appPath = await mkdtemp(join(tmpdir(), 'twenty-i18n-empty-'));+ const appPath = await mkdtemp(join(tmpdir(), 'twenty-translations-empty-'));expect(await compileApplicationTranslations(appPath)).toBeUndefined();});diff --git a/packages/twenty-sdk/src/cli/utilities/translations/__tests__/collect-front-component-strings.spec.ts b/packages/twenty-sdk/src/cli/utilities/translations/__tests__/collect-front-component-strings.spec.tsnew file mode 100644index 00000000000..0f9df59f4e8--- /dev/null+++ b/packages/twenty-sdk/src/cli/utilities/translations/__tests__/collect-front-component-strings.spec.ts@@ -0,0 +1,118 @@+import { mkdtemp, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { join } from 'node:path';++import { describe, expect, it } from 'vitest';++import { collectFrontComponentStrings } from '@/cli/utilities/translations/collect-front-component-strings';++const writeFrontComponent = async (source: string): Promise<string> => {+ const dir = await mkdtemp(join(tmpdir(), 'twenty-fc-translations-'));+ const filePath = join(dir, 'my.front-component.tsx');++ await writeFile(filePath, source);++ return filePath;+};++describe('collectFrontComponentStrings', () => {+ it('returns nothing when there are no source files', async () => {+ expect(await collectFrontComponentStrings([])).toEqual([]);+ });++ it('extracts t(), msg() and <Trans> static strings with context', async () => {+ const filePath = await writeFrontComponent(`+ import { t, msg, Trans, useTranslate } from 'twenty-sdk/front-component';++ const STATUS = msg('Draft');++ const Component = () => {+ const { t: translate } = useTranslate();++ const label = t('No content yet');+ const verb = t({ message: 'Open', context: 'door' });++ return (+ <div title={label}>+ <Trans>Welcome back</Trans>+ <Trans context="card">Untitled</Trans>+ <Trans message="Hi {name}" values={{ name: 'Ada' }} />+ <span>{translate(STATUS)}</span>+ </div>+ );+ };++ export default defineFrontComponent({ component: Component });+ `);++ const result = await collectFrontComponentStrings([filePath]);++ expect(result).toEqual(+ expect.arrayContaining([+ { message: 'Draft' },+ { message: 'No content yet' },+ { message: 'Open', context: 'door' },+ { message: 'Welcome back' },+ { message: 'Untitled', context: 'card' },+ { message: 'Hi {name}' },+ ]),+ );+ expect(result).toHaveLength(6);+ });++ it('collapses whitespace in multi-line <Trans> static text', async () => {+ const filePath = await writeFrontComponent(`+ import { Trans } from 'twenty-sdk/front-component';++ const Component = () => (+ <p>+ <Trans>+ Welcome+ back+ </Trans>+ </p>+ );++ export default defineFrontComponent({ component: Component });+ `);++ expect(await collectFrontComponentStrings([filePath])).toEqual([+ { message: 'Welcome back' },+ ]);+ });++ it('skips dynamic arguments and interpolated children that cannot be statically extracted', async () => {+ const filePath = await writeFrontComponent(`+ import { t, Trans } from 'twenty-sdk/front-component';++ const Component = ({ name }: { name: string }) => {+ const dynamic = t(name);++ return (+ <div title={dynamic}>+ <Trans>Hello {name}</Trans>+ </div>+ );+ };++ export default defineFrontComponent({ component: Component });+ `);++ expect(await collectFrontComponentStrings([filePath])).toEqual([]);+ });++ it('dedupes identical message/context pairs across files', async () => {+ const first = await writeFrontComponent(`+ import { t } from 'twenty-sdk/front-component';+ export const a = () => t('Save');+ `);+ const second = await writeFrontComponent(`+ import { t } from 'twenty-sdk/front-component';+ export const b = () => t('Save');+ `);++ expect(await collectFrontComponentStrings([first, second])).toEqual([+ { message: 'Save' },+ ]);+ });+});diff --git a/packages/twenty-sdk/src/cli/utilities/translations/collect-front-component-strings.ts b/packages/twenty-sdk/src/cli/utilities/translations/collect-front-component-strings.tsnew file mode 100644index 00000000000..5b502823e74--- /dev/null+++ b/packages/twenty-sdk/src/cli/utilities/translations/collect-front-component-strings.ts@@ -0,0 +1,233 @@+import { readFile } from 'node:fs/promises';++import {+ Node,+ Project,+ type JsxElement,+ type JsxOpeningElement,+ type JsxSelfClosingElement,+} from 'ts-morph';++import {+ getTranslationCatalogKey,+ normalizeMessageWhitespace,+ type MessageDescriptor,+} from '@/sdk/front-component/translations/message';++const TRANSLATION_FUNCTION_NAMES = new Set(['t', 'msg']);+const TRANS_COMPONENT_NAME = 'Trans';++const getStringLiteralValue = (node: Node | undefined): string | undefined => {+ if (node === undefined) {+ return undefined;+ }++ if (+ Node.isStringLiteral(node) ||+ Node.isNoSubstitutionTemplateLiteral(node)+ ) {+ return node.getLiteralText();+ }++ return undefined;+};++// Only static string literals are extractable; dynamic arguments are skipped.+const extractFromCallArgument = (+ argument: Node | undefined,+): MessageDescriptor | undefined => {+ if (argument === undefined) {+ return undefined;+ }++ const literalMessage = getStringLiteralValue(argument);++ if (literalMessage !== undefined) {+ return { message: literalMessage };+ }++ if (!Node.isObjectLiteralExpression(argument)) {+ return undefined;+ }++ const messageProperty = argument.getProperty('message');++ if (+ messageProperty === undefined ||+ !Node.isPropertyAssignment(messageProperty)+ ) {+ return undefined;+ }++ const message = getStringLiteralValue(messageProperty.getInitializer());++ if (message === undefined) {+ return undefined;+ }++ const contextProperty = argument.getProperty('context');+ const context =+ contextProperty !== undefined && Node.isPropertyAssignment(contextProperty)+ ? getStringLiteralValue(contextProperty.getInitializer())+ : undefined;++ return context !== undefined ? { message, context } : { message };+};++const getJsxAttributeStringValue = (+ element: JsxOpeningElement | JsxSelfClosingElement,+ name: string,+): string | undefined => {+ const attribute = element.getAttribute(name);++ if (attribute === undefined || !Node.isJsxAttribute(attribute)) {+ return undefined;+ }++ const initializer = attribute.getInitializer();++ if (initializer === undefined) {+ return undefined;+ }++ if (Node.isStringLiteral(initializer)) {+ return initializer.getLiteralText();+ }++ if (Node.isJsxExpression(initializer)) {+ return getStringLiteralValue(initializer.getExpression());+ }++ return undefined;+};++const getTransChildrenText = (element: JsxElement): string | undefined => {+ const children = element.getJsxChildren();++ const hasDynamicChild = children.some(+ (child) =>+ Node.isJsxExpression(child) ||+ Node.isJsxElement(child) ||+ Node.isJsxSelfClosingElement(child),+ );++ if (hasDynamicChild) {+ return undefined;+ }++ const text = normalizeMessageWhitespace(+ children+ .filter((child) => Node.isJsxText(child))+ .map((child) => child.getText())+ .join(''),+ );++ return text.length > 0 ? text : undefined;+};++const dedupeByCatalogKey = (+ descriptors: MessageDescriptor[],+): MessageDescriptor[] => {+ const descriptorByKey = new Map<string, MessageDescriptor>();++ for (const descriptor of descriptors) {+ descriptorByKey.set(+ getTranslationCatalogKey(descriptor.message, descriptor.context),+ descriptor,+ );+ }++ return [...descriptorByKey.values()];+};++export const collectFrontComponentStrings = async (+ sourceFilePaths: string[],+): Promise<MessageDescriptor[]> => {+ if (sourceFilePaths.length === 0) {+ return [];+ }++ const project = new Project({+ useInMemoryFileSystem: true,+ skipFileDependencyResolution: true,+ });++ const descriptors: MessageDescriptor[] = [];++ for (let index = 0; index < sourceFilePaths.length; index++) {+ let content: string;++ try {+ content = await readFile(sourceFilePaths[index], 'utf8');+ } catch {+ continue;+ }++ const sourceFile = project.createSourceFile(+ `front-component-${index}.tsx`,+ content,+ { overwrite: true },+ );++ sourceFile.forEachDescendant((node) => {+ if (Node.isCallExpression(node)) {+ const expression = node.getExpression();++ if (+ Node.isIdentifier(expression) &&+ TRANSLATION_FUNCTION_NAMES.has(expression.getText())+ ) {+ const descriptor = extractFromCallArgument(node.getArguments()[0]);++ if (descriptor !== undefined) {+ descriptors.push(descriptor);+ }+ }++ return;+ }++ if (Node.isJsxSelfClosingElement(node)) {+ if (node.getTagNameNode().getText() !== TRANS_COMPONENT_NAME) {+ return;+ }++ const message = getJsxAttributeStringValue(node, 'message');++ if (message !== undefined && message.length > 0) {+ const context = getJsxAttributeStringValue(node, 'context');++ descriptors.push(+ context !== undefined ? { message, context } : { message },+ );+ }++ return;+ }++ if (Node.isJsxElement(node)) {+ const openingElement = node.getOpeningElement();++ if (+ openingElement.getTagNameNode().getText() !== TRANS_COMPONENT_NAME+ ) {+ return;+ }++ const message =+ getJsxAttributeStringValue(openingElement, 'message') ??+ getTransChildrenText(node);++ if (message !== undefined && message.length > 0) {+ const context = getJsxAttributeStringValue(openingElement, 'context');++ descriptors.push(+ context !== undefined ? { message, context } : { message },+ );+ }+ }+ });+ }++ return dedupeByCatalogKey(descriptors);+};diff --git a/packages/twenty-sdk/src/cli/utilities/i18n/collect-translatable-strings.ts b/packages/twenty-sdk/src/cli/utilities/translations/collect-translatable-strings.tssimilarity index 60%rename from packages/twenty-sdk/src/cli/utilities/i18n/collect-translatable-strings.tsrename to packages/twenty-sdk/src/cli/utilities/translations/collect-translatable-strings.tsindex d5a49608b4d..8476cfdad4c 100644--- a/packages/twenty-sdk/src/cli/utilities/i18n/collect-translatable-strings.ts+++ b/packages/twenty-sdk/src/cli/utilities/translations/collect-translatable-strings.ts@@ -6,12 +6,18 @@ const TRANSLATABLE_KEYS_BY_MANIFEST_KEY: Record<string, readonly string[]> = {views: ['name'],pageLayoutTabs: ['title'],commandMenuItems: ['label', 'shortLabel'],- navigationMenuItems: ['label'],+ navigationMenuItems: ['name'],};export const collectTranslatableStrings = (manifest: Manifest): string[] => {const strings = new Set<string>();+ const addString = (value: unknown) => {+ if (typeof value === 'string' && value.length > 0) {+ strings.add(value);+ }+ };+for (const [manifestKey, fieldKeys] of Object.entries(TRANSLATABLE_KEYS_BY_MANIFEST_KEY,)) {@@ -29,11 +35,19 @@ export const collectTranslatableStrings = (manifest: Manifest): string[] => {}for (const fieldKey of fieldKeys) {- const value = (entity as Record<string, unknown>)[fieldKey];+ addString((entity as Record<string, unknown>)[fieldKey]);+ }+ }+ }++ // Tab and widget titles live nested under pageLayouts[].tabs[], not in the+ // flat pageLayoutTabs array, so walk the tree to reach them.+ for (const pageLayout of manifest.pageLayouts ?? []) {+ for (const tab of pageLayout.tabs ?? []) {+ addString(tab.title);- if (typeof value === 'string' && value.length > 0) {- strings.add(value);- }+ for (const widget of tab.widgets ?? []) {+ addString(widget.title);}}}diff --git a/packages/twenty-sdk/src/cli/utilities/i18n/compile-application-translations.ts b/packages/twenty-sdk/src/cli/utilities/translations/compile-application-translations.tssimilarity index 68%rename from packages/twenty-sdk/src/cli/utilities/i18n/compile-application-translations.tsrename to packages/twenty-sdk/src/cli/utilities/translations/compile-application-translations.tsindex 5f26b8399dd..52b7f144a15 100644--- a/packages/twenty-sdk/src/cli/utilities/i18n/compile-application-translations.ts+++ b/packages/twenty-sdk/src/cli/utilities/translations/compile-application-translations.ts@@ -1,9 +1,10 @@import { readdir } from 'node:fs/promises';import path from 'path';+import { parseTranslationCatalogKey } from '@/sdk/front-component/translations/message';import { pathExists, readJson } from '@/cli/utilities/file/fs-utils';-import { LOCALES_DIR } from '@/cli/utilities/i18n/constants';-import { generateMessageId } from '@/cli/utilities/i18n/generate-message-id';+import { LOCALES_DIR } from '@/cli/utilities/translations/constants';+import { generateMessageId } from '@/cli/utilities/translations/generate-message-id';import { type TranslationsManifest } from 'twenty-shared/application';import {APP_LOCALES,@@ -49,25 +50,24 @@ export const compileApplicationTranslations = async ()) ?? {};const compiled: Record<string, string> = {};- // Detect when two distinct source strings hash to the same message id so the- // collision is reported instead of silently overwriting the earlier value.- const sourceByMessageId = new Map<string, string>();+ const keyByMessageId = new Map<string, string>();- for (const [source, translation] of Object.entries(sourceToTranslation)) {+ for (const [key, translation] of Object.entries(sourceToTranslation)) {if (typeof translation !== 'string' || translation.length === 0) {continue;}- const messageId = generateMessageId(source);- const collidingSource = sourceByMessageId.get(messageId);+ const { message, context } = parseTranslationCatalogKey(key);+ const messageId = generateMessageId(message, context);+ const collidingKey = keyByMessageId.get(messageId);- if (collidingSource !== undefined && collidingSource !== source) {+ if (collidingKey !== undefined && collidingKey !== key) {console.warn(- `Message id collision in "${localeFile}": "${source}" and "${collidingSource}" share id "${messageId}". Keeping "${source}".`,+ `Message id collision in "${localeFile}": "${key}" and "${collidingKey}" share id "${messageId}". Keeping "${key}".`,);}- sourceByMessageId.set(messageId, source);+ keyByMessageId.set(messageId, key);compiled[messageId] = translation;}diff --git a/packages/twenty-sdk/src/cli/utilities/i18n/constants.ts b/packages/twenty-sdk/src/cli/utilities/translations/constants.tssimilarity index 100%rename from packages/twenty-sdk/src/cli/utilities/i18n/constants.tsrename to packages/twenty-sdk/src/cli/utilities/translations/constants.tsdiff --git a/packages/twenty-sdk/src/cli/utilities/translations/extract-application-translations.ts b/packages/twenty-sdk/src/cli/utilities/translations/extract-application-translations.tsnew file mode 100644index 00000000000..09de61d1ca8--- /dev/null+++ b/packages/twenty-sdk/src/cli/utilities/translations/extract-application-translations.ts@@ -0,0 +1,123 @@+import { readdir } from 'node:fs/promises';+import path from 'path';++import { type Manifest } from 'twenty-shared/application';+import { SOURCE_LOCALE, type AppLocale } from 'twenty-shared/translations';+import { isDefined } from 'twenty-shared/utils';++import {+ getTranslationCatalogKey,+ type MessageDescriptor,+} from '@/sdk/front-component/translations/message';+import {+ ensureDir,+ pathExists,+ readJson,+ writeJson,+} from '@/cli/utilities/file/fs-utils';+import { collectFrontComponentStrings } from '@/cli/utilities/translations/collect-front-component-strings';+import { collectTranslatableStrings } from '@/cli/utilities/translations/collect-translatable-strings';+import { LOCALES_DIR } from '@/cli/utilities/translations/constants';++type ExtractApplicationTranslationsResult = {+ sourceCount: number;+ updatedLocaleFiles: string[];+};++const collectSourceEntries = async ({+ manifest,+ frontComponentSourcePaths,+}: {+ manifest: Manifest;+ frontComponentSourcePaths: string[];+}): Promise<Map<string, MessageDescriptor>> => {+ const manifestDescriptors: MessageDescriptor[] = collectTranslatableStrings(+ manifest,+ ).map((message) => ({ message }));++ const frontComponentDescriptors = await collectFrontComponentStrings(+ frontComponentSourcePaths,+ );++ const descriptorByKey = new Map<string, MessageDescriptor>();++ for (const descriptor of [+ ...manifestDescriptors,+ ...frontComponentDescriptors,+ ]) {+ descriptorByKey.set(+ getTranslationCatalogKey(descriptor.message, descriptor.context),+ descriptor,+ );+ }++ return descriptorByKey;+};++export const extractApplicationTranslations = async ({+ appPath,+ manifest,+ frontComponentSourcePaths = [],+ scaffoldLocale,+}: {+ appPath: string;+ manifest: Manifest;+ frontComponentSourcePaths?: string[];+ scaffoldLocale?: AppLocale;+}): Promise<ExtractApplicationTranslationsResult> => {+ const descriptorByKey = await collectSourceEntries({+ manifest,+ frontComponentSourcePaths,+ });++ const sortedKeys = [...descriptorByKey.keys()].sort();+ const localesDir = path.join(appPath, LOCALES_DIR);++ await ensureDir(localesDir);++ const sourceCatalog: Record<string, string> = {};++ for (const key of sortedKeys) {+ const descriptor = descriptorByKey.get(key);++ if (isDefined(descriptor)) {+ sourceCatalog[key] = descriptor.message;+ }+ }++ await writeJson(+ path.join(localesDir, `${SOURCE_LOCALE}.json`),+ sourceCatalog,+ );++ if (scaffoldLocale !== undefined && scaffoldLocale !== SOURCE_LOCALE) {+ const scaffoldPath = path.join(localesDir, `${scaffoldLocale}.json`);++ if (!(await pathExists(scaffoldPath))) {+ await writeJson(scaffoldPath, {});+ }+ }++ const existingLocaleFiles = (await readdir(localesDir)).filter(+ (entry) => entry.endsWith('.json') && entry !== `${SOURCE_LOCALE}.json`,+ );++ for (const localeFile of existingLocaleFiles) {+ const filePath = path.join(localesDir, localeFile);+ const existing = (await readJson<Record<string, unknown>>(filePath)) ?? {};+ const merged: Record<string, string> = {};++ for (const key of sortedKeys) {+ const existingValue = existing[key];++ merged[key] = typeof existingValue === 'string' ? existingValue : '';+ }++ await writeJson(filePath, merged);+ }++ return {+ sourceCount: sortedKeys.length,+ updatedLocaleFiles: existingLocaleFiles,+ };+};diff --git a/packages/twenty-sdk/src/cli/utilities/i18n/generate-message-id.ts b/packages/twenty-sdk/src/cli/utilities/translations/generate-message-id.tssimilarity index 100%rename from packages/twenty-sdk/src/cli/utilities/i18n/generate-message-id.tsrename to packages/twenty-sdk/src/cli/utilities/translations/generate-message-id.tsdiff --git a/packages/twenty-sdk/src/cli/utilities/translations/load-front-component-translation-catalogs.ts b/packages/twenty-sdk/src/cli/utilities/translations/load-front-component-translation-catalogs.tsnew file mode 100644index 00000000000..3fdefb8ca2a--- /dev/null+++ b/packages/twenty-sdk/src/cli/utilities/translations/load-front-component-translation-catalogs.ts@@ -0,0 +1,58 @@+import { readdir } from 'node:fs/promises';+import path from 'path';++import {+ APP_LOCALES,+ SOURCE_LOCALE,+ type AppLocale,+} from 'twenty-shared/translations';++import { type TranslationCatalogsByLocale } from '@/sdk/front-component/translations/message';+import { pathExists, readJson } from '@/cli/utilities/file/fs-utils';+import { LOCALES_DIR } from '@/cli/utilities/translations/constants';++const isSupportedLocale = (locale: string): locale is AppLocale =>+ Object.prototype.hasOwnProperty.call(APP_LOCALES, locale);++export const loadFrontComponentTranslationCatalogs = async (+ appPath: string,+): Promise<TranslationCatalogsByLocale> => {+ const localesDir = path.join(appPath, LOCALES_DIR);++ if (!(await pathExists(localesDir))) {+ return {};+ }++ const localeFiles = (await readdir(localesDir)).filter((entry) =>+ entry.endsWith('.json'),+ );++ const catalogs: TranslationCatalogsByLocale = {};++ for (const localeFile of localeFiles) {+ const locale = path.basename(localeFile, '.json');++ if (locale === SOURCE_LOCALE || !isSupportedLocale(locale)) {+ continue;+ }++ const catalog =+ (await readJson<Record<string, string>>(+ path.join(localesDir, localeFile),+ )) ?? {};++ const nonEmptyEntries: Record<string, string> = {};++ for (const [key, value] of Object.entries(catalog)) {+ if (typeof value === 'string' && value.length > 0) {+ nonEmptyEntries[key] = value;+ }+ }++ if (Object.keys(nonEmptyEntries).length > 0) {+ catalogs[locale] = nonEmptyEntries;+ }+ }++ return catalogs;+};diff --git a/packages/twenty-sdk/src/sdk/front-component/components/Trans.tsx b/packages/twenty-sdk/src/sdk/front-component/components/Trans.tsxnew file mode 100644index 00000000000..c894ab4fab9--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/components/Trans.tsx@@ -0,0 +1,53 @@+import { type ReactNode } from 'react';++import { useLocale } from '../hooks/useLocale';+import {+ normalizeMessageWhitespace,+ type TranslationValues,+} from '../translations/message';+import { resolveTranslation } from '../translations/resolveTranslation';++export type TransProps = {+ children?: ReactNode;+ // Use this (with `values`) for interpolation; inlined child expressions+ // cannot be statically extracted.+ message?: string;+ context?: string;+ values?: TranslationValues;+};++const getSourceMessage = (+ message: string | undefined,+ children: ReactNode,+): string | undefined => {+ if (message !== undefined) {+ return message;+ }++ if (typeof children === 'string') {+ return normalizeMessageWhitespace(children);+ }++ return undefined;+};++export const Trans = ({+ children,+ message,+ context,+ values,+}: TransProps): ReactNode => {+ const locale = useLocale();++ const sourceMessage = getSourceMessage(message, children);++ if (sourceMessage === undefined) {+ return children;+ }++ return resolveTranslation(+ { message: sourceMessage, context },+ values,+ locale,+ );+};diff --git a/packages/twenty-sdk/src/sdk/front-component/constants/front-component-translations-key.ts b/packages/twenty-sdk/src/sdk/front-component/constants/front-component-translations-key.tsnew file mode 100644index 00000000000..6cef3bf8e54--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/constants/front-component-translations-key.ts@@ -0,0 +1,4 @@+// globalThis key under which the build bakes the app's compiled translation+// catalogs so the runtime resolver can read them inside the sandboxed worker.+export const FRONT_COMPONENT_TRANSLATIONS_KEY =+ '__twentySdkFrontComponentTranslations__';diff --git a/packages/twenty-sdk/src/sdk/front-component/hooks/useLocale.ts b/packages/twenty-sdk/src/sdk/front-component/hooks/useLocale.tsnew file mode 100644index 00000000000..af3c51ab2be--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/hooks/useLocale.ts@@ -0,0 +1,13 @@+import { SOURCE_LOCALE, type AppLocale } from 'twenty-shared/translations';++import { type FrontComponentExecutionContext } from '../types/FrontComponentExecutionContext';+import { useFrontComponentExecutionContext } from './useFrontComponentExecutionContext';++const selectLocale = (context: FrontComponentExecutionContext): AppLocale =>+ context.locale ?? SOURCE_LOCALE;++// Reactive locale of the host UI. Re-renders the component when the user+// switches language, mirroring useColorScheme.+export const useLocale = (): AppLocale => {+ return useFrontComponentExecutionContext(selectLocale);+};diff --git a/packages/twenty-sdk/src/sdk/front-component/hooks/useTranslate.ts b/packages/twenty-sdk/src/sdk/front-component/hooks/useTranslate.tsnew file mode 100644index 00000000000..d209e407c01--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/hooks/useTranslate.ts@@ -0,0 +1,29 @@+import { useCallback } from 'react';+import { type AppLocale } from 'twenty-shared/translations';++import {+ type MessageDescriptor,+ type TranslationValues,+} from '../translations/message';+import { resolveTranslation } from '../translations/resolveTranslation';+import { useLocale } from './useLocale';++export type UseTranslateResult = {+ locale: AppLocale;+ t: (+ descriptor: string | MessageDescriptor,+ values?: TranslationValues,+ ) => string;+};++export const useTranslate = (): UseTranslateResult => {+ const locale = useLocale();++ const t = useCallback(+ (descriptor: string | MessageDescriptor, values?: TranslationValues) =>+ resolveTranslation(descriptor, values, locale),+ [locale],+ );++ return { locale, t };+};diff --git a/packages/twenty-sdk/src/sdk/front-component/index.ts b/packages/twenty-sdk/src/sdk/front-component/index.tsindex 3e708f18872..7ba51702a0a 100644--- a/packages/twenty-sdk/src/sdk/front-component/index.ts+++ b/packages/twenty-sdk/src/sdk/front-component/index.ts@@ -1,3 +1,5 @@+export { Trans } from './components/Trans';+export type { TransProps } from './components/Trans';export { closeSidePanel } from './functions/closeSidePanel';export { copyToClipboard } from './functions/copyToClipboard';export { getApplicationVariable } from './functions/getApplicationVariable';@@ -10,9 +12,18 @@ export { updateProgress } from './functions/updateProgress';export { useColorScheme } from './hooks/useColorScheme';export { useFrontComponentExecutionContext } from './hooks/useFrontComponentExecutionContext';export { useFrontComponentId } from './hooks/useFrontComponentId';+export { useTranslate } from './hooks/useTranslate';+export type { UseTranslateResult } from './hooks/useTranslate';+export { useLocale } from './hooks/useLocale';export { useRecordId } from './hooks/useRecordId';export { useSelectedRecordIds } from './hooks/useSelectedRecordIds';export { useUserId } from './hooks/useUserId';+export { msg } from './translations/msg';+export { t } from './translations/t';+export type {+ MessageDescriptor,+ TranslationValues,+} from './translations/message';export type { FrontComponentExecutionContext } from './types/FrontComponentExecutionContext';export { getFrontComponentCommandErrorDedupeKey } from './utils/getFrontComponentCommandErrorDedupeKey';export type {diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/__tests__/message.spec.ts b/packages/twenty-sdk/src/sdk/front-component/translations/__tests__/message.spec.tsnew file mode 100644index 00000000000..fd6f35dd1cd--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/__tests__/message.spec.ts@@ -0,0 +1,60 @@+import { describe, expect, it } from 'vitest';++import {+ getTranslationCatalogKey,+ interpolateMessage,+ normalizeMessageDescriptor,+ parseTranslationCatalogKey,+} from '@/sdk/front-component/translations/message';++describe('normalizeMessageDescriptor', () => {+ it('wraps a bare string into a descriptor', () => {+ expect(normalizeMessageDescriptor('Save')).toEqual({ message: 'Save' });+ });++ it('passes a descriptor through unchanged', () => {+ expect(+ normalizeMessageDescriptor({ message: 'Open', context: 'door' }),+ ).toEqual({ message: 'Open', context: 'door' });+ });+});++describe('translation catalog key', () => {+ it('uses the raw message when there is no context', () => {+ expect(getTranslationCatalogKey('Save')).toBe('Save');+ expect(getTranslationCatalogKey('Save', '')).toBe('Save');+ });++ it('disambiguates identical messages with different contexts', () => {+ expect(getTranslationCatalogKey('Open', 'door')).not.toBe(+ getTranslationCatalogKey('Open', 'window'),+ );+ });++ it('round-trips through parseTranslationCatalogKey', () => {+ expect(+ parseTranslationCatalogKey(getTranslationCatalogKey('Save')),+ ).toEqual({ message: 'Save' });+ expect(+ parseTranslationCatalogKey(getTranslationCatalogKey('Open', 'door')),+ ).toEqual({ message: 'Open', context: 'door' });+ });+});++describe('interpolateMessage', () => {+ it('returns the template unchanged when no values are given', () => {+ expect(interpolateMessage('Hello {name}')).toBe('Hello {name}');+ });++ it('substitutes named placeholders', () => {+ expect(interpolateMessage('Saved {count} cards', { count: 3 })).toBe(+ 'Saved 3 cards',+ );+ });++ it('leaves unknown placeholders intact', () => {+ expect(interpolateMessage('Hi {name} from {city}', { name: 'Ada' })).toBe(+ 'Hi Ada from {city}',+ );+ });+});diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/__tests__/resolveTranslation.spec.ts b/packages/twenty-sdk/src/sdk/front-component/translations/__tests__/resolveTranslation.spec.tsnew file mode 100644index 00000000000..bc3a3ec9029--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/__tests__/resolveTranslation.spec.ts@@ -0,0 +1,63 @@+import { afterEach, describe, expect, it } from 'vitest';++import { setFrontComponentTranslations } from '@/sdk/front-component/translations/front-component-translations';+import { getTranslationCatalogKey } from '@/sdk/front-component/translations/message';+import { resolveTranslation } from '@/sdk/front-component/translations/resolveTranslation';++afterEach(() => {+ setFrontComponentTranslations({});+});++describe('resolveTranslation', () => {+ it('returns the translation for the active locale', () => {+ setFrontComponentTranslations({ 'fr-FR': { Save: 'Enregistrer' } });++ expect(resolveTranslation('Save', undefined, 'fr-FR')).toBe('Enregistrer');+ });++ it('falls back to the source message when the locale is missing', () => {+ setFrontComponentTranslations({ 'fr-FR': { Save: 'Enregistrer' } });++ expect(resolveTranslation('Save', undefined, 'de-DE')).toBe('Save');+ });++ it('falls back to the source message when the key is untranslated', () => {+ setFrontComponentTranslations({ 'fr-FR': {} });++ expect(resolveTranslation('Cancel', undefined, 'fr-FR')).toBe('Cancel');+ });++ it('resolves context-disambiguated messages independently', () => {+ setFrontComponentTranslations({+ 'fr-FR': {+ [getTranslationCatalogKey('Open', 'door')]: 'Ouvrir',+ [getTranslationCatalogKey('Open', 'window')]: 'Lever',+ },+ });++ expect(+ resolveTranslation(+ { message: 'Open', context: 'door' },+ undefined,+ 'fr-FR',+ ),+ ).toBe('Ouvrir');+ expect(+ resolveTranslation(+ { message: 'Open', context: 'window' },+ undefined,+ 'fr-FR',+ ),+ ).toBe('Lever');+ });++ it('interpolates values into the resolved translation', () => {+ setFrontComponentTranslations({+ 'fr-FR': { 'Saved {count} cards': 'Cartes enregistrées : {count}' },+ });++ expect(+ resolveTranslation('Saved {count} cards', { count: 5 }, 'fr-FR'),+ ).toBe('Cartes enregistrées : 5');+ });+});diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/front-component-translations.ts b/packages/twenty-sdk/src/sdk/front-component/translations/front-component-translations.tsnew file mode 100644index 00000000000..fc4e729ee42--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/front-component-translations.ts@@ -0,0 +1,14 @@+import { FRONT_COMPONENT_TRANSLATIONS_KEY } from '../constants/front-component-translations-key';+import { type TranslationCatalogsByLocale } from './message';++export const getFrontComponentTranslations = (): TranslationCatalogsByLocale =>+ ((globalThis as Record<string, unknown>)[FRONT_COMPONENT_TRANSLATIONS_KEY] as+ | TranslationCatalogsByLocale+ | undefined) ?? {};++export const setFrontComponentTranslations = (+ catalogs: TranslationCatalogsByLocale,+): void => {+ (globalThis as Record<string, unknown>)[FRONT_COMPONENT_TRANSLATIONS_KEY] =+ catalogs;+};diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/context-separator.constant.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/context-separator.constant.tsnew file mode 100644index 00000000000..bfad59ad98d--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/context-separator.constant.ts@@ -0,0 +1,2 @@+// A control char, so context-less keys stay equal to the raw source message.+export const CONTEXT_SEPARATOR = String.fromCharCode(0x04);diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/get-translation-catalog-key.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/get-translation-catalog-key.tsnew file mode 100644index 00000000000..ca6db005ff0--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/get-translation-catalog-key.ts@@ -0,0 +1,9 @@+import { CONTEXT_SEPARATOR } from './context-separator.constant';++export const getTranslationCatalogKey = (+ message: string,+ context?: string,+): string =>+ context !== undefined && context.length > 0+ ? `${context}${CONTEXT_SEPARATOR}${message}`+ : message;diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/index.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/index.tsnew file mode 100644index 00000000000..4391f260399--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/index.ts@@ -0,0 +1,8 @@+export { getTranslationCatalogKey } from './get-translation-catalog-key';+export { interpolateMessage } from './interpolate-message';+export { normalizeMessageDescriptor } from './normalize-message-descriptor';+export { normalizeMessageWhitespace } from './normalize-message-whitespace';+export { parseTranslationCatalogKey } from './parse-translation-catalog-key';+export type { MessageDescriptor } from './message-descriptor.type';+export type { TranslationCatalogsByLocale } from './translation-catalogs-by-locale.type';+export type { TranslationValues } from './translation-values.type';diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/interpolate-message.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/interpolate-message.tsnew file mode 100644index 00000000000..2bfaeed6c4d--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/interpolate-message.ts@@ -0,0 +1,16 @@+import { type TranslationValues } from './translation-values.type';++export const interpolateMessage = (+ template: string,+ values?: TranslationValues,+): string => {+ if (values === undefined) {+ return template;+ }++ return template.replace(/\{(\w+)\}/g, (placeholder, name: string) =>+ Object.prototype.hasOwnProperty.call(values, name)+ ? String(values[name])+ : placeholder,+ );+};diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/message-descriptor.type.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/message-descriptor.type.tsnew file mode 100644index 00000000000..b0767ed2728--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/message-descriptor.type.ts@@ -0,0 +1,4 @@+export type MessageDescriptor = {+ message: string;+ context?: string;+};diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/normalize-message-descriptor.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/normalize-message-descriptor.tsnew file mode 100644index 00000000000..3a313da8ef5--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/normalize-message-descriptor.ts@@ -0,0 +1,6 @@+import { type MessageDescriptor } from './message-descriptor.type';++export const normalizeMessageDescriptor = (+ descriptor: string | MessageDescriptor,+): MessageDescriptor =>+ typeof descriptor === 'string' ? { message: descriptor } : descriptor;diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/normalize-message-whitespace.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/normalize-message-whitespace.tsnew file mode 100644index 00000000000..77b861b502f--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/normalize-message-whitespace.ts@@ -0,0 +1,3 @@+// Must match how JSX collapses <Trans> whitespace, so build and runtime agree.+export const normalizeMessageWhitespace = (text: string): string =>+ text.replace(/\s+/g, ' ').trim();diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/parse-translation-catalog-key.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/parse-translation-catalog-key.tsnew file mode 100644index 00000000000..9e68ad38a4b--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/parse-translation-catalog-key.ts@@ -0,0 +1,15 @@+import { CONTEXT_SEPARATOR } from './context-separator.constant';+import { type MessageDescriptor } from './message-descriptor.type';++export const parseTranslationCatalogKey = (key: string): MessageDescriptor => {+ const separatorIndex = key.indexOf(CONTEXT_SEPARATOR);++ if (separatorIndex === -1) {+ return { message: key };+ }++ return {+ context: key.slice(0, separatorIndex),+ message: key.slice(separatorIndex + 1),+ };+};diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/translation-catalogs-by-locale.type.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/translation-catalogs-by-locale.type.tsnew file mode 100644index 00000000000..89213b8d30c--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/translation-catalogs-by-locale.type.ts@@ -0,0 +1,5 @@+import { type AppLocale } from 'twenty-shared/translations';++export type TranslationCatalogsByLocale = Partial<+ Record<AppLocale, Record<string, string>>+>;diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/message/translation-values.type.ts b/packages/twenty-sdk/src/sdk/front-component/translations/message/translation-values.type.tsnew file mode 100644index 00000000000..3cc7edbd0aa--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/message/translation-values.type.ts@@ -0,0 +1 @@+export type TranslationValues = Record<string, string | number>;diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/msg.ts b/packages/twenty-sdk/src/sdk/front-component/translations/msg.tsnew file mode 100644index 00000000000..864e305cca6--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/msg.ts@@ -0,0 +1,5 @@+import { normalizeMessageDescriptor, type MessageDescriptor } from './message';++export const msg = (+ descriptor: string | MessageDescriptor,+): MessageDescriptor => normalizeMessageDescriptor(descriptor);diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/resolveTranslation.ts b/packages/twenty-sdk/src/sdk/front-component/translations/resolveTranslation.tsnew file mode 100644index 00000000000..f5b979adaba--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/resolveTranslation.ts@@ -0,0 +1,23 @@+import { type AppLocale } from 'twenty-shared/translations';++import { getFrontComponentTranslations } from './front-component-translations';+import {+ getTranslationCatalogKey,+ interpolateMessage,+ normalizeMessageDescriptor,+ type MessageDescriptor,+ type TranslationValues,+} from './message';++export const resolveTranslation = (+ descriptor: string | MessageDescriptor,+ values: TranslationValues | undefined,+ locale: AppLocale,+): string => {+ const { message, context } = normalizeMessageDescriptor(descriptor);++ const catalog = getFrontComponentTranslations()[locale];+ const translation = catalog?.[getTranslationCatalogKey(message, context)];++ return interpolateMessage(translation ?? message, values);+};diff --git a/packages/twenty-sdk/src/sdk/front-component/translations/t.ts b/packages/twenty-sdk/src/sdk/front-component/translations/t.tsnew file mode 100644index 00000000000..fa494da1875--- /dev/null+++ b/packages/twenty-sdk/src/sdk/front-component/translations/t.ts@@ -0,0 +1,19 @@+import { SOURCE_LOCALE, type AppLocale } from 'twenty-shared/translations';++import { getFrontComponentExecutionContext } from '../context/frontComponentContext';+import { type FrontComponentExecutionContext } from '../types/FrontComponentExecutionContext';+import { type MessageDescriptor, type TranslationValues } from './message';+import { resolveTranslation } from './resolveTranslation';++const getCurrentLocale = (): AppLocale => {+ // Unset at module scope before the host pushes it.+ const context: FrontComponentExecutionContext | undefined =+ getFrontComponentExecutionContext();++ return context?.locale ?? SOURCE_LOCALE;+};++export const t = (+ descriptor: string | MessageDescriptor,+ values?: TranslationValues,+): string => resolveTranslation(descriptor, values, getCurrentLocale());diff --git a/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts b/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.tsindex 67771ad1e54..660956c839c 100644--- a/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts+++ b/packages/twenty-sdk/src/sdk/front-component/types/FrontComponentExecutionContext.ts@@ -1,3 +1,5 @@+import { type AppLocale } from 'twenty-shared/translations';+export type FrontComponentExecutionContext = {frontComponentId: string;userId: string | null;@@ -9,5 +11,5 @@ export type FrontComponentExecutionContext = {selectedRecordIds: string[];/** Resolved color scheme of the host UI ('System' is already resolved) */colorScheme: 'light' | 'dark';- locale?: string;+ locale?: AppLocale;};diff --git a/packages/twenty-shared/src/constants/DocumentationPaths.ts b/packages/twenty-shared/src/constants/DocumentationPaths.tsindex a0d46fbc751..4104068ce25 100644--- a/packages/twenty-shared/src/constants/DocumentationPaths.ts+++ b/packages/twenty-shared/src/constants/DocumentationPaths.ts@@ -75,6 +75,8 @@ export const DOCUMENTATION_PATHS = {'/developers/extend/apps/operations/sync-and-recovery',DEVELOPERS_EXTEND_APPS_OPERATIONS_TESTING:'/developers/extend/apps/operations/testing',+ DEVELOPERS_EXTEND_APPS_TRANSLATIONS_OVERVIEW:+ '/developers/extend/apps/translations/overview',DEVELOPERS_EXTEND_OAUTH: '/developers/extend/oauth',DEVELOPERS_EXTEND_WEBHOOKS: '/developers/extend/webhooks',DEVELOPERS_INTRODUCTION: '/developers/introduction',