القائمة
Add, rename, or remove i18n translation keys in fundamental-ngx (updates FdLanguage interface, .properties files, and generated types)
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/SAP/fundamental-ngx --skill i18n-manageيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
استنادا إلى تصنيف SOC المهني
If $ARGUMENTS is empty, ask the user what operation they need (add, rename, or remove) and for which key.
The i18n system has one translation file that developers edit:
libs/i18n/src/lib/translations/translations.properties — the base English translation strings.
The CLI reads this file and generates all localized TypeScript files:
translations.ts — base English translationstranslations_*.ts — localized translations (de, es, fr, etc.)Additionally, the FdLanguage interface must be manually maintained:
libs/i18n/src/lib/models/fd-language.ts — the FdLanguage interface.
Translation teams edit: Language-specific .properties files (translations_de.properties, translations_es.properties, etc.)
The language-specific .properties files are read by the i18n-manage --command=sync script when generating TypeScript files. When translation teams update these files, running i18n-manage --command=sync will pick up those translations automatically.
Every other file is auto-generated:
fd-language-key-identifier.ts — generated by i18n-manage --command=synctranslations_*.properties - delivered by external translation team after translating changes to translations.propertiestranslations_*.ts — generated by i18n-manage operations from translations.properties and translations_*.propertiesIf you skip updating fd-language.ts, the build will fail with a misleading error (see Troubleshooting below). This is the single most common mistake when working with i18n keys.
fd-language.ts (MANUAL — required)Open libs/i18n/src/lib/models/fd-language.ts and add the property to the interface.
FdLanguageFind the correct section (e.g., coreCalendar, coreButton). If the section doesn't exist, create it.
coreCalendar: {
// ... existing keys ...
/** ARIA label for the calendar legend */
calendarLegendLabel: FdLanguageKey;
}
For keys with parameters:
/** Message showing count of selected items */
itemsSelected: FdLanguageKey<{ count: number }>;
nx run i18n:i18n-manage --command=add --key=coreCalendar.calendarLegendLabel --value="Calendar Legend" --commentType=XACT --comment="ARIA label for the calendar legend"
This single command:
calendarLegendLabel to translations.properties with the comment described in the argumentsts file (e.g., translations.ts, translations_es.ts, translations_de.ts)Comment types (auto-detected from key name if --commentType is omitted):
| Type | Usage | Auto-detected from |
|---|---|---|
| XACT | ARIA labels, screen reader text | key contains aria |
| XBUT | Button labels | key contains button |
| XFLD | Form input labels | key contains label |
| XTIT | Titles and headings | key contains title |
| XMSG | Messages, descriptions | default fallback |
| XTOL | Tooltips | — |
| XCKL | Checkbox text | — |
| XRBL | Radio button text | — |
| XSEL | Dropdown/select values | — |
| XLNK | Link text | — |
| YINS | User instructions | — |
| NOTR | No translation needed | — |
nx run i18n:i18n-manage --command=validate
nx run i18n:build --skip-nx-cache
fd-language.ts (MANUAL)Rename the property in the FdLanguage interface.
nx run i18n:i18n-manage --command=rename --key=coreButton.oldName --newKey=coreButton.newName
Search for usages of the old key string in component files:
grep -rn "coreButton.oldName" libs/core/ libs/platform/ --include="*.ts" --include="*.html"
Update all occurrences to the new key.
nx run i18n:i18n-manage --command=validate
nx run i18n:build --skip-nx-cache
grep -rn "theKey.toRemove" libs/core/ libs/platform/ libs/btp/ libs/cx/ --include="*.ts" --include="*.html"
Do NOT remove a key that is still referenced in components.
fd-language.ts (MANUAL)Remove the property from the FdLanguage interface. If it was the last key in a section, remove the entire section.
nx run i18n:i18n-manage --command=remove --key=theKey.toRemove
nx run i18n:i18n-manage --command=validate
nx run i18n:build --skip-nx-cache
@Component({
imports: [FdTranslatePipe],
template: `<span>{{ ('coreCalendar.calendarLegendLabel' | fdTranslate)() }}</span>`
})
The pipe returns Signal<string> — the () invocation is required.
protected readonly _label = resolveTranslationSignal('coreCalendar.calendarLegendLabel');
private readonly _translate = resolveTranslationSignalFn();
private readonly _label = this._translate('coreCalendar.closeCalendarLabel');
private readonly _description = this._translate('coreCalendar.calendarDayViewDescription');
Inline resolveTranslationSignalFn() to avoid ESLint member-ordering violations:
@Component({
host: { '[attr.aria-label]': '_ariaLabel()' }
})
export class CalendarLegendComponent {
protected readonly _ariaLabel = resolveTranslationSignalFn()('coreCalendar.calendarLegendLabel');
}
Do NOT split into two fields — protected must come before private per ESLint:
// BAD — ESLint member-ordering violation
private readonly _resolve = resolveTranslationSignalFn();
protected readonly _ariaLabel = this._resolve('coreCalendar.calendarLegendLabel');
TS2554: Expected 2 arguments, but got 1On a call like resolveTranslationSignalFn()('coreCalendar.calendarLegendLabel').
Cause: The key exists in fd-language-key-identifier.ts (auto-generated) but NOT in fd-language.ts (manual). You forgot Step 1.
Why: The type resolver walks ObjectPathType<FdLanguage, Key>. When the property is missing from the interface, it resolves to never, making FdLanguageKeyCtx<Key> non-undefined, which forces the type system to demand a second argument.
Fix: Add the missing property to fd-language.ts.
Key "x" already existsThe key is already in translations.properties. Use rename or update instead of add.
nx run i18n:i18n-manage --command=search --searchTerm=keyName
nx run i18n:i18n-manage --command=update --key=coreButton.save --value="New Value"
nx run i18n:i18n-manage --command=sync --skip-nx-cache
| File | Manual/Generated | Purpose |
|---|---|---|
libs/i18n/src/lib/translations/translations.properties | Generated by i18n-manage --command=add | Base English translation strings (developer edits this) |
libs/i18n/src/lib/models/fd-language.ts | MANUAL | FdLanguage interface — runtime type shape |
libs/i18n/src/lib/models/fd-language-key-identifier.ts | Generated | Union type of all valid key strings |
libs/i18n/src/lib/translations/translations_*.ts | Generated | TypeScript translation modules (37 locales) — consumed by the application |
libs/i18n/src/lib/translations/translations_*.properties | Delivered from external translation team | Localized translation strings — read by scripts to generate translations_*.ts |