refactor(server): unify the two metadata override mechanisms into one (#22417)

## Unify the two metadata override mechanisms into one

Twenty had **two** override mechanisms:

- **`standardOverrides`** — a bespoke JSONB column on
`objectMetadata`/`fieldMetadata` with typed DTOs and a per-locale
`translations` map, resolved by two i18n-aware resolvers.
- **`OverridableEntity.overrides`** — a flat, registry-driven JSONB blob
on view / view-field / view-field-group / command-menu-item /
page-layout-tab / page-layout-widget, resolved by a plain spread.

This PR collapses them into **one** concept: a single `overrides` blob,
one registry-driven overridable set, one i18n-aware read path, and one
write path (`computeMetadataOverridesBlob`, extracted in #22404).

Object/field **stay on `SyncableEntity`** (not reparented to
`OverridableEntity`) so their `isActive` default stays **FALSE** — this
sidesteps the `isActive` default conflict entirely.

### GraphQL breaking change (accepted)

The `standardOverrides` field is **removed** with no deprecation alias —
`overrides` (a `JSON` scalar) is exposed instead on `Object` and
`Field`. Product confirmed negligible external usage; the front-end has
no hand-written consumer (only generated types), which are regenerated
here.

### Commit structure (reviewable commit-by-commit)

1. **Unified resolver + parity harness** —
`resolveEffectiveEntityProperty` is a strict superset of the three
legacy resolvers; a corpus parity spec compares it against a *frozen
reference* of the old logic across every locale, `isStandardApp` branch
and override shape.
2. **Registry-driven** — object/field presentation props tagged
`isOverridable` + `translatable`; the overridable/translatable sets are
derived from the registry (a test asserts they equal the legacy
hardcoded lists).
3. **Rename + swap + delete** — `standardOverrides` → `overrides` across
entities, DTOs, flat/universal types, producers, the ~12
resolve/write/create/sync call sites, mocks and specs; the reconciler's
two compare entries collapse to one; the three legacy resolvers, both
DTOs and the hardcoded constants/types are deleted.
4. **Migration (zero-downtime, two-phase)** — split across two releases
so a rolling deploy never drops a column a previous-release pod still
`SELECT`s:
   - **2.19 fast** — add the `overrides` column (schema only).
- **2.19 slow** — backfill `overrides` from `standardOverrides` in
`runDataMigration` (kept out of the schema transaction so the bulk write
doesn't hold the ACCESS EXCLUSIVE lock; skipped on fresh installs, which
have no data to copy).
- **2.20 fast** — drop the legacy `standardOverrides` column (gated by
`TWENTY_NEXT_VERSIONS`, so it stays dormant until the instance reaches
2.20).
5. **Front/client-SDK regen** — regenerated metadata GraphQL types.
6. **Integration specs + i18n** — updated the standard object/field
update integration specs + snapshots, and the reworded validator message
catalog entry.

### Rolling-deploy safety

`standardOverrides` is retained through 2.19 and only dropped in 2.20,
mirroring the codebase's deferred-drop convention
(`isUIReadOnly`/`isCustom`). During the 2.19 rollout both columns exist,
so old and new pods coexist without "column does not exist" errors. The
backfill lives in a slow `runDataMigration` (per the
`no-data-mutation-in-fast-instance-command` rule) so it doesn't stall
reads.

### `isActive` guard

The migration never reads or writes `isActive`; the backfill asserts the
active-row count is unchanged and aborts otherwise. Verified on a real
DB: apply + revert preserves the blob **and** the nested `translations`
map, with `isActive` counts identical before/after.

### Verification (local)

- `nx typecheck twenty-server` + `nx typecheck twenty-front` — green
- `nx lint:diff-with-main twenty-server` (oxlint `--type-aware` + oxfmt)
— green
- `nx test twenty-server` — green (unit + parity + registry + migration
tests)
- `nx run twenty-server:test:integration:with-db-reset` — green
- `database:reset` applies the 2.19 phases and leaves **both** columns
present (2.20 drop stays dormant); backfill + revert round-trip verified
on a real DB
- Metadata integration suites (standard object/field update, application
sync) pass end-to-end against the two-column schema
- Metadata GraphQL types regenerated against a booted server; zero
`standardOverrides` references remain in application code (only the
migration commands + the legacy schema baseline)

---------

Co-authored-by: prastoin <paul@twenty.com>
This commit is contained in:
Félix Malfait
2026-07-02 12:01:15 +02:00
committed by GitHub
parent 63d092a31b
commit 5a4ebca226
121 changed files with 2394 additions and 3109 deletions
@@ -1,9 +0,0 @@
import { type MetadataUniversalFlatEntityPropertiesToCompare } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/metadata-universal-flat-entity-properties-to-compare.type';
export const OBJECT_METADATA_STANDARD_OVERRIDES_PROPERTIES = [
'color',
'labelSingular',
'labelPlural',
'description',
'icon',
] as const satisfies MetadataUniversalFlatEntityPropertiesToCompare<'objectMetadata'>[];
@@ -28,7 +28,7 @@ const PARTIAL_ID_FIELD = {
isLabelSyncedWithName: false,
defaultValue: 'uuid',
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -58,7 +58,7 @@ const PARTIAL_CREATED_AT_FIELD = {
isLabelSyncedWithName: false,
defaultValue: 'now',
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -88,7 +88,7 @@ const PARTIAL_UPDATED_AT_FIELD = {
isLabelSyncedWithName: false,
defaultValue: 'now',
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -118,7 +118,7 @@ const PARTIAL_DELETED_AT_FIELD = {
isLabelSyncedWithName: false,
defaultValue: null,
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -148,7 +148,7 @@ const PARTIAL_CREATED_BY_FIELD = {
isLabelSyncedWithName: false,
defaultValue: { name: "''", source: "'MANUAL'" },
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -178,7 +178,7 @@ const PARTIAL_UPDATED_BY_FIELD = {
isLabelSyncedWithName: false,
defaultValue: { name: "''", source: "'MANUAL'" },
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -208,7 +208,7 @@ const PARTIAL_POSITION_FIELD = {
isLabelSyncedWithName: false,
defaultValue: 0,
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
universalSettings: null,
relationTargetObjectMetadataUniversalIdentifier: null,
@@ -238,7 +238,7 @@ const PARTIAL_SEARCH_VECTOR_FIELD = {
isLabelSyncedWithName: false,
defaultValue: null,
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
// universalSettings for searchVector is computed at runtime
// based on the name field (getTsVectorColumnExpressionFromFields)
@@ -12,7 +12,7 @@ import { type WorkspaceEntityDuplicateCriteria } from 'src/engine/api/graphql/wo
import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
import { FieldMetadataDTO } from 'src/engine/metadata-modules/field-metadata/dtos/field-metadata.dto';
import { IndexMetadataDTO } from 'src/engine/metadata-modules/index-metadata/dtos/index-metadata.dto';
import { ObjectStandardOverridesDTO } from 'src/engine/metadata-modules/object-metadata/dtos/object-standard-overrides.dto';
import { type ObjectMetadataOverrides } from 'src/engine/metadata-modules/object-metadata/types/object-metadata-overrides.type';
@ObjectType('Object')
@Authorize({
@@ -53,8 +53,8 @@ export class ObjectMetadataDTO {
@Field({ nullable: true })
icon?: string;
@Field(() => ObjectStandardOverridesDTO, { nullable: true })
standardOverrides?: ObjectStandardOverridesDTO;
@HideField()
overrides?: ObjectMetadataOverrides | null;
@Field({ nullable: true })
shortcut?: string;
@@ -1,49 +0,0 @@
import { Field, ObjectType } from '@nestjs/graphql';
import { IsJSON, IsOptional, IsString } from 'class-validator';
import { GraphQLJSON } from 'graphql-type-json';
import { type APP_LOCALES } from 'twenty-shared/translations';
@ObjectType('ObjectStandardOverrides')
export class ObjectStandardOverridesDTO {
@IsString()
@IsOptional()
@Field(() => String, { nullable: true })
labelSingular?: string | null;
@IsString()
@IsOptional()
@Field(() => String, { nullable: true })
labelPlural?: string | null;
@IsString()
@IsOptional()
@Field(() => String, { nullable: true })
description?: string | null;
@IsString()
@IsOptional()
@Field(() => String, { nullable: true })
icon?: string | null;
@IsString()
@IsOptional()
@Field(() => String, { nullable: true })
color?: string | null;
@IsJSON()
@IsOptional()
@Field(() => GraphQLJSON, {
nullable: true,
})
translations?: Partial<
Record<
keyof typeof APP_LOCALES,
{
labelSingular?: string | null;
labelPlural?: string | null;
description?: string | null;
}
>
> | null;
}
@@ -13,12 +13,13 @@ import { type WorkspaceEntityDuplicateCriteria } from 'src/engine/api/graphql/wo
import { FieldMetadataEntity } from 'src/engine/metadata-modules/field-metadata/field-metadata.entity';
import { IndexMetadataEntity } from 'src/engine/metadata-modules/index-metadata/index-metadata.entity';
import { SearchFieldMetadataEntity } from 'src/engine/metadata-modules/search-field-metadata/search-field-metadata.entity';
import { type ObjectStandardOverridesDTO } from 'src/engine/metadata-modules/object-metadata/dtos/object-standard-overrides.dto';
import { type ObjectMetadataOverrides } from 'src/engine/metadata-modules/object-metadata/types/object-metadata-overrides.type';
import { FieldPermissionEntity } from 'src/engine/metadata-modules/object-permission/field-permission/field-permission.entity';
import { ObjectPermissionEntity } from 'src/engine/metadata-modules/object-permission/object-permission.entity';
import { ViewEntity } from 'src/engine/metadata-modules/view/entities/view.entity';
import { WasIntroducedInUpgrade } from 'src/engine/core-modules/upgrade/decorators/was-introduced-in-upgrade.decorator';
import { WasRemovedInUpgrade } from 'src/engine/core-modules/upgrade/decorators/was-removed-in-upgrade.decorator';
import { ADD_METADATA_OVERRIDES_COLUMN_UPGRADE_COMMAND_NAME } from 'src/database/commands/upgrade-version-command/2-19/add-metadata-overrides-column-upgrade-command-name.constant';
import { RENAME_IS_UI_READ_ONLY_TO_IS_UI_EDITABLE_UPGRADE_COMMAND_NAME } from 'src/engine/metadata-modules/object-metadata/constants/rename-is-ui-read-only-to-is-ui-editable-upgrade-command-name.constant';
import { SyncableEntity } from 'src/engine/workspace-manager/types/syncable-entity.interface';
import { type JsonbProperty } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/jsonb-property.type';
@@ -64,8 +65,18 @@ export class ObjectMetadataEntity
@Column({ nullable: true, type: 'text' })
color: string | null;
@WasIntroducedInUpgrade({
upgradeCommandName: ADD_METADATA_OVERRIDES_COLUMN_UPGRADE_COMMAND_NAME,
})
@Column({ type: 'jsonb', nullable: true })
standardOverrides: JsonbProperty<ObjectStandardOverridesDTO> | null;
overrides: JsonbProperty<ObjectMetadataOverrides> | null;
/**
* @deprecated Superseded by `overrides`; kept readable for pods on the
* previous release during a rolling deploy. Drop deferred to 2-20/README.md.
*/
@Column({ type: 'jsonb', nullable: true })
standardOverrides: WasRemovedInUpgrade<JsonbProperty<ObjectMetadataOverrides> | null>;
/**
* @deprecated
@@ -32,7 +32,7 @@ import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metada
import { ObjectRecordCountService } from 'src/engine/metadata-modules/object-metadata/object-record-count.service';
import { SearchFieldMetadataDTO } from 'src/engine/metadata-modules/search-field-metadata/dtos/search-field-metadata.dto';
import { objectMetadataGraphqlApiExceptionHandler } from 'src/engine/metadata-modules/object-metadata/utils/object-metadata-graphql-api-exception-handler.util';
import { resolveObjectMetadataStandardOverride } from 'src/engine/metadata-modules/object-metadata/utils/resolve-object-metadata-standard-override.util';
import { resolveEffectiveEntityProperty } from 'src/engine/metadata-modules/utils/resolve-effective-entity-property.util';
import { PermissionsGraphqlApiExceptionFilter } from 'src/engine/metadata-modules/permissions/utils/permissions-graphql-api-exception.filter';
@UseGuards(WorkspaceAuthGuard)
@@ -92,14 +92,18 @@ export class ObjectMetadataResolver {
locale: context.req.locale,
});
return resolveObjectMetadataStandardOverride(
objectMetadata,
labelKey,
context.req.locale,
i18n,
isStandardApp,
applicationCatalog,
);
return resolveEffectiveEntityProperty({
metadataName: 'objectMetadata',
baseValue: objectMetadata[labelKey],
overrides: objectMetadata.overrides,
property: labelKey,
i18nContext: {
locale: context.req.locale,
i18nInstance: i18n,
isStandardApp,
applicationCatalog,
},
});
}
@ResolveField(() => String, { nullable: true })
@@ -10,7 +10,7 @@ import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metada
import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
const OBJECT_STRIP_WHEN_NULLISH = [
'standardOverrides',
'overrides',
'color',
'duplicateCriteria',
'shortcut',
@@ -0,0 +1,19 @@
import { type APP_LOCALES } from 'twenty-shared/translations';
export type ObjectMetadataOverrides = {
labelSingular?: string | null;
labelPlural?: string | null;
description?: string | null;
icon?: string | null;
color?: string | null;
translations?: Partial<
Record<
keyof typeof APP_LOCALES,
{
labelSingular?: string | null;
labelPlural?: string | null;
description?: string | null;
}
>
> | null;
};
@@ -1,4 +0,0 @@
import { type OBJECT_METADATA_STANDARD_OVERRIDES_PROPERTIES } from 'src/engine/metadata-modules/object-metadata/constants/object-metadata-standard-overrides-properties.constant';
export type ObjectMetadataStandardOverridesProperties =
(typeof OBJECT_METADATA_STANDARD_OVERRIDES_PROPERTIES)[number];
@@ -31,7 +31,7 @@ const makeFieldMetadata = (
icon: null,
options: null,
settings: null,
standardOverrides: null,
overrides: null,
relationTargetObjectMetadataUniversalIdentifier: null,
createdAt: '2026-01-01T00:00:00.000Z',
updatedAt: '2026-01-01T00:00:00.000Z',
@@ -1,737 +0,0 @@
import { type I18n } from '@lingui/core';
import { SOURCE_LOCALE } from 'twenty-shared/translations';
import { generateMessageId } from 'src/engine/core-modules/i18n/utils/generateMessageId';
import { resolveObjectMetadataStandardOverride } from 'src/engine/metadata-modules/object-metadata/utils/resolve-object-metadata-standard-override.util';
jest.mock('src/engine/core-modules/i18n/utils/generateMessageId');
const mockGenerateMessageId = generateMessageId as jest.MockedFunction<
typeof generateMessageId
>;
describe('resolveObjectMetadataStandardOverride', () => {
let mockI18n: jest.Mocked<I18n>;
beforeEach(() => {
jest.clearAllMocks();
mockI18n = {
_: jest.fn(),
} as unknown as jest.Mocked<I18n>;
});
describe('Custom objects', () => {
it('should return the object value for custom labelSingular object', () => {
const objectMetadata = {
labelSingular: 'My Custom',
labelPlural: 'My Customs',
description: 'Custom Description',
icon: 'custom-icon',
color: 'blue',
isCustom: true,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('My Custom');
});
it('should never translate a custom label even when it matches a standard catalog entry', () => {
const objectMetadata = {
labelSingular: 'Company',
labelPlural: 'Companies',
description: 'Custom Description',
icon: 'custom-icon',
color: 'blue',
isCustom: true,
standardOverrides: undefined,
};
mockGenerateMessageId.mockReturnValue('company.message.id');
mockI18n._.mockReturnValue('Entreprise');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Company');
expect(mockGenerateMessageId).not.toHaveBeenCalled();
expect(mockI18n._).not.toHaveBeenCalled();
});
it('should return the object value for custom description object', () => {
const objectMetadata = {
labelSingular: 'My Custom',
labelPlural: 'My Customs',
description: 'Custom Description',
icon: 'custom-icon',
color: 'blue',
isCustom: true,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'description',
undefined,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Custom Description');
});
it('should return the object value for custom icon object', () => {
const objectMetadata = {
labelSingular: 'My Custom',
labelPlural: 'My Customs',
description: 'Custom Description',
icon: 'custom-icon',
color: 'blue',
isCustom: true,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'icon',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('custom-icon');
});
it('should return the object value for custom color object', () => {
const objectMetadata = {
labelSingular: 'My Custom',
labelPlural: 'My Customs',
description: 'Custom Description',
icon: 'custom-icon',
color: 'green',
isCustom: true,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'color',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('green');
});
});
describe('Standard objects - Icon overrides', () => {
it('should return override icon when available for standard object', () => {
const objectMetadata = {
labelSingular: 'My Custom',
labelPlural: 'My Customs',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
icon: 'override-icon',
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'icon',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('override-icon');
});
});
describe('Standard objects - Color overrides', () => {
it('should return override color when available for standard object', () => {
const objectMetadata = {
labelSingular: 'Company',
labelPlural: 'Companies',
description: 'Standard Description',
icon: 'default-icon',
color: 'blue',
isCustom: false,
standardOverrides: {
color: 'red',
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'color',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('red');
});
it('should return base color when no override exists for standard object', () => {
const objectMetadata = {
labelSingular: 'Company',
labelPlural: 'Companies',
description: 'Standard Description',
icon: 'default-icon',
color: 'blue',
isCustom: false,
standardOverrides: undefined,
};
mockGenerateMessageId.mockReturnValue('generated-message-id');
mockI18n._.mockReturnValue('generated-message-id');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'color',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('blue');
});
});
describe('Standard objects - Translation overrides', () => {
it('should return translation override when available for non-icon objects', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
translations: {
'fr-FR': {
labelSingular: 'Libellé traduit',
labelPlural: 'Libellés traduits',
description: 'Description traduite',
},
},
},
};
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
),
).toBe('Libellé traduit');
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'labelPlural',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
),
).toBe('Libellés traduits');
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'description',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
),
).toBe('Description traduite');
});
it('should fallback when translation override is not available for the locale', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
translations: {
'es-ES': {
labelSingular: 'Etiqueta en español',
labelPlural: 'Etiquetas en español',
description: 'Descripción en español',
},
},
},
};
mockGenerateMessageId.mockReturnValue('generated-message-id');
mockI18n._.mockReturnValue('generated-message-id');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Standard Label');
});
it('should fallback when translation override is not available for the labelKey', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
translations: {
'fr-FR': {
labelPlural: 'Libellés traduits',
labelSingular: 'Libellé traduit',
},
},
},
};
mockGenerateMessageId.mockReturnValue('generated-message-id');
mockI18n._.mockReturnValue('generated-message-id');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'description',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Standard Description');
});
it('should not use translation overrides when locale is undefined', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
translations: {
'fr-FR': {
labelSingular: 'Libellé traduit',
labelPlural: 'Libellés traduits',
description: 'Description traduite',
},
},
},
};
mockGenerateMessageId.mockReturnValue('generated-message-id');
mockI18n._.mockReturnValue('generated-message-id');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
undefined,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Standard Label');
});
});
describe('Standard objects - SOURCE_LOCALE overrides', () => {
it('should return direct override for SOURCE_LOCALE when available', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
labelSingular: 'Overridden Label',
labelPlural: 'Overridden Labels',
description: 'Overridden Description',
icon: 'overridden-icon',
},
};
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
),
).toBe('Overridden Label');
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'labelPlural',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
),
).toBe('Overridden Labels');
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'description',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
),
).toBe('Overridden Description');
expect(
resolveObjectMetadataStandardOverride(
objectMetadata,
'icon',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
),
).toBe('overridden-icon');
});
it('should use direct override for non-SOURCE_LOCALE', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
labelSingular: 'Overridden Label',
labelPlural: 'Overridden Labels',
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Overridden Label');
});
it('should not use undefined override for SOURCE_LOCALE', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
labelSingular: undefined,
},
};
mockGenerateMessageId.mockReturnValue('generated-message-id');
mockI18n._.mockReturnValue('generated-message-id');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Standard Label');
});
});
describe('Standard objects - Auto translation fallback', () => {
it('should return translated message when translation is available', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: undefined,
};
mockGenerateMessageId.mockReturnValue('standard.label.message.id');
mockI18n._.mockReturnValue('Libellé traduit automatiquement');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(mockGenerateMessageId).toHaveBeenCalledWith('Standard Label');
expect(mockI18n._).toHaveBeenCalledWith('standard.label.message.id');
expect(result).toBe('Libellé traduit automatiquement');
});
it('should return original object value when no translation is found', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: undefined,
};
const messageId = 'standard.label.message.id';
mockGenerateMessageId.mockReturnValue(messageId);
mockI18n._.mockReturnValue(messageId);
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Standard Label');
});
});
describe('Priority order - Standard objects', () => {
it('should prioritize translation override over SOURCE_LOCALE override for non-SOURCE_LOCALE', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
labelSingular: 'Source Override',
labelPlural: 'Source Overrides',
translations: {
'fr-FR': {
labelSingular: 'Translation Override',
labelPlural: 'Translation Overrides',
},
},
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Translation Override');
expect(mockGenerateMessageId).not.toHaveBeenCalled();
expect(mockI18n._).not.toHaveBeenCalled();
});
it('should prioritize SOURCE_LOCALE override over auto translation for SOURCE_LOCALE', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
labelSingular: 'Source Override',
labelPlural: 'Source Overrides',
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
SOURCE_LOCALE,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Source Override');
expect(mockGenerateMessageId).not.toHaveBeenCalled();
expect(mockI18n._).not.toHaveBeenCalled();
});
it('should use auto translation when no overrides are available', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {},
};
mockGenerateMessageId.mockReturnValue('auto.translation.id');
mockI18n._.mockReturnValue('Auto Translated Label');
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'de-DE',
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Auto Translated Label');
expect(mockGenerateMessageId).toHaveBeenCalledWith('Standard Label');
expect(mockI18n._).toHaveBeenCalledWith('auto.translation.id');
});
});
describe('Undefined locale handling', () => {
it('should use SOURCE_LOCALE fallback when locale is undefined for standard object', () => {
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: {
labelSingular: 'Source Override',
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
undefined,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Source Override');
expect(mockGenerateMessageId).not.toHaveBeenCalled();
expect(mockI18n._).not.toHaveBeenCalled();
});
it('should fall back to auto translation when locale is undefined and no SOURCE_LOCALE override exists', () => {
mockI18n._.mockReturnValue('Auto Translated Label');
mockGenerateMessageId.mockReturnValue('auto.translation.id');
const objectMetadata = {
labelSingular: 'Standard Label',
labelPlural: 'Standard Labels',
description: 'Standard Description',
icon: 'default-icon',
isCustom: false,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
undefined,
mockI18n,
!objectMetadata.isCustom,
);
expect(result).toBe('Auto Translated Label');
expect(mockGenerateMessageId).toHaveBeenCalledWith('Standard Label');
expect(mockI18n._).toHaveBeenCalledWith('auto.translation.id');
});
});
describe('Application objects - catalog translations', () => {
it('should translate an application object label from its catalog', () => {
mockGenerateMessageId.mockReturnValue('app.label.id');
const objectMetadata = {
labelSingular: 'Property',
labelPlural: 'Properties',
description: 'A property',
icon: 'IconBuilding',
isCustom: false,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
false,
{ 'app.label.id': 'Bien' },
);
expect(result).toBe('Bien');
expect(mockI18n._).not.toHaveBeenCalled();
});
it('should fall back to the source value when the catalog has no entry', () => {
mockGenerateMessageId.mockReturnValue('missing.id');
const objectMetadata = {
labelSingular: 'Property',
labelPlural: 'Properties',
description: 'A property',
icon: 'IconBuilding',
isCustom: false,
standardOverrides: undefined,
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
false,
{},
);
expect(result).toBe('Property');
});
it('should prioritize a workspace translation override over the catalog', () => {
const objectMetadata = {
labelSingular: 'Property',
labelPlural: 'Properties',
description: 'A property',
icon: 'IconBuilding',
isCustom: false,
standardOverrides: {
translations: {
'fr-FR': {
labelSingular: 'Bien immobilier',
},
},
},
};
const result = resolveObjectMetadataStandardOverride(
objectMetadata,
'labelSingular',
'fr-FR',
mockI18n,
false,
{ 'app.label.id': 'Bien' },
);
expect(result).toBe('Bien immobilier');
expect(mockGenerateMessageId).not.toHaveBeenCalled();
});
});
});
@@ -139,7 +139,7 @@ export const buildDefaultFlatFieldMetadatasForCustomObject = ({
createdAt: now,
updatedAt: now,
options: null,
standardOverrides: null,
overrides: null,
morphId: null,
applicationUniversalIdentifier,
objectMetadataUniversalIdentifier,
@@ -15,7 +15,7 @@ export const fromObjectMetadataEntityToObjectMetadataDto = (
icon: entity.icon ?? undefined,
color: entity.color ?? undefined,
shortcut: entity.shortcut ?? undefined,
standardOverrides: entity.standardOverrides ?? undefined,
overrides: entity.overrides ?? undefined,
isRemote: entity.isRemote,
isActive: entity.isActive,
isSystem: entity.isSystem,
@@ -1,61 +0,0 @@
import { type I18n } from '@lingui/core';
import { isNonEmptyString } from '@sniptt/guards';
import { type APP_LOCALES, SOURCE_LOCALE } from 'twenty-shared/translations';
import { isDefined } from 'twenty-shared/utils';
import { translateStandardLabel } from 'src/engine/core-modules/i18n/utils/translate-standard-label.util';
import { type ObjectMetadataDTO } from 'src/engine/metadata-modules/object-metadata/dtos/object-metadata.dto';
export const resolveObjectMetadataStandardOverride = (
objectMetadata: Pick<
ObjectMetadataDTO,
| 'color'
| 'labelPlural'
| 'labelSingular'
| 'description'
| 'icon'
| 'standardOverrides'
>,
labelKey: 'color' | 'labelPlural' | 'labelSingular' | 'description' | 'icon',
locale: keyof typeof APP_LOCALES | undefined,
i18nInstance: I18n,
isStandardApp: boolean,
applicationCatalog?: Record<string, string>,
): string => {
const safeLocale = locale ?? SOURCE_LOCALE;
if (!isStandardApp && !isDefined(applicationCatalog)) {
return objectMetadata[labelKey] ?? '';
}
if (
(labelKey === 'icon' || labelKey === 'color') &&
isDefined(objectMetadata.standardOverrides?.[labelKey])
) {
return objectMetadata.standardOverrides[labelKey];
}
if (
isDefined(objectMetadata.standardOverrides?.translations) &&
labelKey !== 'icon' &&
labelKey !== 'color'
) {
const translationValue =
objectMetadata.standardOverrides.translations[safeLocale]?.[labelKey];
if (isDefined(translationValue)) {
return translationValue;
}
}
if (isNonEmptyString(objectMetadata.standardOverrides?.[labelKey])) {
return objectMetadata.standardOverrides[labelKey] ?? '';
}
return translateStandardLabel({
sourceValue: objectMetadata[labelKey] ?? '',
isStandardApp,
applicationCatalog,
i18nInstance,
});
};