Declarative translated_text localization is not supported for SDK-managed records

[toshikiO]

Description

The Fluent API has no supported way to declaratively define translated labels for translated_text-type fields (e.g., sys_properties.description). The SDK-generated translation records are created in the app scope and are silently rejected by the ServiceNow instance at install time — meaning translations simply do not appear after now-sdk install.

This affects any field backed by sys_translated_text, not just sys_properties.description. The impact is significant for global/multi-language deployments where property descriptions and other translatable text need to be localized.

Root Cause Analysis

The root cause is a cross-scope conflict between how the SDK generates records and how the ServiceNow platform enforces scope ownership on sys_translated_text.

1. The description field type is translated_text

sys_properties.description is of type translated_text. The platform stores translations as separate rows in sys_translated_text, distinguished by (tablename, fieldname, sys_id, language).

The Property Fluent API exposes description as a plain string:

export type PropertyDefinition = {
    description?: string   // ← single string, no localization array
    // ...
}

There is no array-based localization option analogous to the label array used for sys_documentation. Attempting to pass an array causes a compile-time error:

TS2322: Type '{ text: string; language: string; }[]' is not assignable to type 'string'.

2. Record API workaround is silently rejected at install

A workaround via the Record API — directly creating sys_translated_text rows — appears correct in the generated dist/ XML but is silently dropped during now-sdk install:

// Attempted workaround — record is NOT created on the instance
export const myTranslation = Record('sys_translated_text', 'my_prop_ja', {
    tablename: 'sys_properties',
    fieldname: 'description',
    value: 'プロパティの説明',
    language: 'ja',
})

After install, no corresponding sys_translated_text row exists on the instance. There is no error message or warning in the install output.

3. GUI translation works correctly

Translations created via the platform UI under Global scope (System Properties > [open record] > Translated Text tab) work normally. The platform's own scope check passes because the record is authored in Global scope.

This confirms the problem is not in the sys_translated_text table itself, but in the SDK always generating records under the app scope.

Steps to Reproduce

Verified on @servicenow/sdk@4.7 with a real instance deployment.

Attempt A: Array syntax in description

export const myProperty = Property('my_prop', {
    description: [
        { text: 'My property description', language: 'en' },
        { text: 'プロパティの説明', language: 'ja' },
    ],
    // ...
})

Result: TS2322 compile error. description is typed as string; array syntax is rejected.

Attempt B: Record API for sys_translated_text

export const myPropertyDescJa = Record('sys_translated_text', 'my_prop_description_ja', {
    tablename: 'sys_properties',
    fieldname: 'description',
    value: 'プロパティの説明',
    language: 'ja',
})

Result: Build succeeds and the record appears in dist/ XML. However, after now-sdk install, the record does not exist on the instance. No error is reported.

Attempt C: GUI-created translation (Global scope)

Navigate to the property record on the instance → open the Translated Text related list → add a row with language = ja.

Result: Works correctly. The Japanese description displays when the browser locale is set to Japanese.

Conclusion

There is no SDK-supported way to declaratively define translated_text translations. All three paths either fail at compile time, are silently dropped at install time, or require manual GUI intervention — which defeats the purpose of source-controlled declarative configuration.

Impact

• Declarative configuration is broken for translatable text: Properties, and any other field backed by sys_translated_text, cannot have translations managed in source control. This forces manual GUI steps after every deployment.
• Global/multi-language deployments are significantly burdened: Translating property descriptions requires navigating each record individually in the platform UI after every install.
• API inconsistency: Column labels already support multi-language arrays via sys_documentation. Translatable text fields (sys_translated_text) being the exception makes the i18n story incomplete and confusing.
• Silent failure degrades developer experience: The install-time rejection of app-scope sys_translated_text records produces no warning, making this extremely difficult to diagnose without deep knowledge of ServiceNow's scope model.

Environment

• @servicenow/sdk: 4.7.0
• Node.js: v22.14.0

[toshikiO]

Hi everyone,
Just wanted to gently bump this discussion to see if anyone has had a chance to look into it. I’d appreciate any thoughts or guidance when you have a moment. Thanks!