review both i18n READMEs

[droshev]

Problem 1:

We currently have two README-s about i18n:

https://github.com/SAP/fundamental-ngx/blob/main/libs/i18n/README.md?plain=1#L201
https://github.com/SAP/fundamental-ngx/blob/main/libs/nx-plugin/src/executors/i18n-manage/README.md

This step in the first readme is misleading:

Step 2: Add to ALL .properties Files

Add to all files in libs/i18n/src/lib/translations/ (use English text everywhere):

TODO: Figure out if we still need both README-s. Make sure the one that stays contains the correct information.

Problem 2:

As part of adding a new translation key with the command nx run i18n:i18n-manage --command=add --key=coreButton.submit --value="Submit" --commentType=XBUT --comment="Submit button" it seems like the FdLanguage interface located in libs/i18n/src/lib/models/fd-language.ts is not updated and needs to be updated manually. The script should update that as well.
Rename and remove scripts should update that interface as well.

[droshev]

Problem 1 — Resolved

The libs/i18n/README.md "Adding New Translation Keys" section has been rewritten. It now:

• Leads with fd-language.ts as the only manual step
• Uses the i18n-manage CLI for everything else (instead of telling people to manually edit 37 .properties files)
• Links to the executor README (libs/nx-plugin/src/executors/i18n-manage/README.md) for rename, remove, update, search, sort, and validation commands

Both READMEs are still needed — they serve different purposes:

• libs/i18n/README.md — public-facing README (npm/GitHub), covers app-developer setup + key addition overview
• libs/nx-plugin/src/executors/i18n-manage/README.md — CLI reference with all commands, parameters, SAP text types, and .properties format rules

---

Problem 2 — Implementation Guide

The add, rename, and remove commands in i18n-manage need to also update libs/i18n/src/lib/models/fd-language.ts (the FdLanguage interface). Currently this is the only manual step.

What needs to change

Three files to modify:

File	Operation
libs/nx-plugin/src/executors/i18n-manage/operations/add-key.ts	Add property to FdLanguage interface
libs/nx-plugin/src/executors/i18n-manage/operations/rename-key.ts	Rename property in FdLanguage interface
libs/nx-plugin/src/executors/i18n-manage/operations/remove-key.ts	Remove property from FdLanguage interface

fd-language.ts structure

The file is at libs/i18n/src/lib/models/fd-language.ts. It exports a single interface:

import { FdLanguageKey } from './fd-language-key';

export interface FdLanguage {
    locale?: string;
    name?: string;

    coreBusyIndicator: {
        defaultAriaValueText: FdLanguageKey;
        defaultTitle: FdLanguageKey;
    };
    coreCalendar: {
        yearSelectionLabel: FdLanguageKey;
        // ... more keys
    };
    // ... more sections
}

Each section name matches the component prefix from the key (e.g., key coreCalendar.yearSelectionLabel → section coreCalendar, property yearSelectionLabel).

The type is FdLanguageKey for simple strings, or FdLanguageKey<{ paramName: type }> for parameterized translations (see libs/i18n/src/lib/models/fd-language-key.ts).

For add-key.ts

After Step 5 (adding to .properties files) and before Step 6 (running transform-translations):

1. Read fd-language.ts
2. Parse the key (e.g., coreCalendar.calendarLegendLabel → section coreCalendar, property calendarLegendLabel)
3. If the section exists: add the property inside it with a JSDoc comment derived from the --comment parameter
4. If the section doesn't exist: create it with the property
5. Write the file
6. The --comment parameter maps to the JSDoc: /** Submit button */ submit: FdLanguageKey;

Determining FdLanguageKey vs FdLanguageKey<T>: If the --value contains ICU parameters (e.g., {count}), the type should be FdLanguageKey<{ count: string | number }>. If no parameters, use plain FdLanguageKey. Parse {paramName} patterns from the value string to extract parameter names.

For rename-key.ts

After Step 4 (renaming in .properties files):

1. Read fd-language.ts
2. Parse old and new keys
3. If section changes (e.g., coreButton.save → coreForm.save): remove from old section, add to new
4. If only property name changes: rename the property in place, keeping JSDoc
5. Write the file

For remove-key.ts

After Step 4 (removing from .properties files):

1. Read fd-language.ts
2. Parse the key to find section and property
3. Remove the property (and its JSDoc comment)
4. If the section becomes empty after removal: remove the entire section
5. Write the file

Testing

Each operation already has a .spec.ts file alongside it. Add test cases for the fd-language.ts updates:

• Add: new key in existing section, new key in new section, key with ICU parameters
• Rename: same section, cross-section
• Remove: remove property, remove last property in section (should remove section)

Edge cases

• Sections might have different numbers of keys — find the closing }; correctly
• JSDoc comments are single-line (/** text */) in existing code
• Properties are separated by blank lines in some sections, not in others — follow the pattern of the target section
• The validate and sort commands don't need changes (they don't add/remove keys)