====== Internazionalizzazione (i18n) ======

Linee guida per il multilinguismo della suite WvdS FPC RAD.

===== Principio fondamentale =====

**Nessuna stringa letterale nel codice Pascal** (eccetto nei blocchi asm e nelle costanti tecniche).

===== Lingue supportate =====

^ Codice ^ Lingua ^ Stato ^
| EN | Inglese | Base (obbligatoria) |
| DE | Tedesco | Completa |
| SL | Sloveno | Completa |
| HR | Croato | Completa |

===== Resourcestrings =====

==== Struttura ====

<code>
sources/common/core/
├── WvdS.VSCode.Strings.pas      # Inglese (default)
├── WvdS.VSCode.Strings.DE.pas   # Tedesco
├── WvdS.VSCode.Strings.SL.pas   # Sloveno
└── WvdS.VSCode.Strings.HR.pas   # Croato
</code>

==== Unit base (inglese) ====

<code pascal>
unit WvdS.VSCode.Strings;

{$mode objfpc}{$H+}

interface

resourcestring
  // === CORE ===
  rsCoreActivated = 'WvdS Core extension activated';
  rsCoreDeactivated = 'WvdS Core extension deactivated';
  rsCoreError = 'Error: %s';

  // === BUILD ===
  rsBuildStarting = 'Build starting...';
  rsBuildCompleted = 'Build completed successfully';
  rsBuildFailed = 'Build failed: %s';
  rsBuildCompilerNotFound = 'Compiler not found: %s';

  // === PROJECTS ===
  rsProjectCreating = 'Creating project...';
  rsProjectCreated = 'Project ''%s'' created successfully';
  rsProjectNameEmpty = 'Project name cannot be empty';
  rsProjectNameTooLong = 'Project name cannot exceed %d characters';
  rsProjectNameInvalidChar = 'Invalid character in project name: ''%s''';

  // === TOOLCHAIN ===
  rsToolNotFound = 'Tool not found: %s';
  rsToolDetected = '%s detected at %s';
  rsToolVersionMismatch = '%s version %s found, expected %s';

  // === VALIDATION ===
  rsValidationFailed = 'Validation failed: %s';
  rsFileNotFound = 'File not found: %s';
  rsAccessDenied = 'Access denied: %s';
  rsUnexpectedError = 'Unexpected error (%s): %s';

implementation

end.
</code>

==== Traduzione tedesca ====

<code pascal>
unit WvdS.VSCode.Strings.DE;

{$mode objfpc}{$H+}

interface

resourcestring
  // === CORE ===
  rsCoreActivated = 'WvdS Core Extension aktiviert';
  rsCoreDeactivated = 'WvdS Core Extension deaktiviert';
  rsCoreError = 'Fehler: %s';

  // === BUILD ===
  rsBuildStarting = 'Build wird gestartet...';
  rsBuildCompleted = 'Build erfolgreich abgeschlossen';
  rsBuildFailed = 'Build fehlgeschlagen: %s';
  rsBuildCompilerNotFound = 'Compiler nicht gefunden: %s';

  // === PROJECTS ===
  rsProjectCreating = 'Projekt wird erstellt...';
  rsProjectCreated = 'Projekt ''%s'' erfolgreich erstellt';
  rsProjectNameEmpty = 'Projektname darf nicht leer sein';
  rsProjectNameTooLong = 'Projektname darf maximal %d Zeichen haben';
  rsProjectNameInvalidChar = 'Ungultiges Zeichen im Projektnamen: ''%s''';

  // === TOOLCHAIN ===
  rsToolNotFound = 'Werkzeug nicht gefunden: %s';
  rsToolDetected = '%s erkannt unter %s';
  rsToolVersionMismatch = '%s Version %s gefunden, erwartet %s';

  // === VALIDATION ===
  rsValidationFailed = 'Validierung fehlgeschlagen: %s';
  rsFileNotFound = 'Datei nicht gefunden: %s';
  rsAccessDenied = 'Zugriff verweigert: %s';
  rsUnexpectedError = 'Unerwarteter Fehler (%s): %s';

implementation

end.
</code>

===== Utilizzo nel codice =====

==== Stringhe semplici ====

<code pascal>
uses
  WvdS.VSCode.Strings;

// CORRETTO
ShowInfoMessage(rsBuildStarting);

// VIETATO
ShowInfoMessage('Build starting...');
</code>

==== Stringhe con parametri ====

<code pascal>
// CORRETTO - Usare Format
ShowInfoMessage(Format(rsProjectCreated, [ProjectName]));
ShowErrorMessage(Format(rsBuildFailed, [ErrorMessage]));

// VIETATO
ShowInfoMessage('Project ''' + ProjectName + ''' created');
</code>

==== Pluralizzazione ====

<code pascal>
resourcestring
  rsFilesFound_One = '%d file found';
  rsFilesFound_Many = '%d files found';

function GetFilesFoundMessage(ACount: Integer): string;
begin
  if ACount = 1 then
    Result := Format(rsFilesFound_One, [ACount])
  else
    Result := Format(rsFilesFound_Many, [ACount]);
end;
</code>

===== Eccezioni consentite =====

==== Costanti tecniche ====

<code pascal>
const
  // ID tecnici - non tradurre
  COMMAND_ID = 'wvds.build.run';
  FILE_EXTENSION = '.pas';
  CONFIG_KEY = 'wvds.toolchain.fpcPath';
</code>

==== Stringhe di formato ====

<code pascal>
const
  // Template JSON/XML - non tradurre
  JSON_TEMPLATE = '{"name": "%s", "version": "%s"}';
  XML_TEMPLATE = '<%s>%s</%s>';
</code>

==== Blocchi asm ====

<code pascal>
// Il codice JavaScript puo contenere stringhe
asm
  console.log('Debug message');
  vscode.window.showInformationMessage('Hello');
end;
</code>

===== Workflow: Aggiungere una nuova stringa =====

==== Passaggio 1: Definire stringa inglese ====

<code pascal>
// WvdS.VSCode.Strings.pas
resourcestring
  rsNewFeatureMessage = 'New feature activated';
</code>

==== Passaggio 2: Traduzione tedesca ====

<code pascal>
// WvdS.VSCode.Strings.DE.pas
resourcestring
  rsNewFeatureMessage = 'Neue Funktion aktiviert';
</code>

==== Passaggio 3: Traduzione slovena ====

<code pascal>
// WvdS.VSCode.Strings.SL.pas
resourcestring
  rsNewFeatureMessage = 'Nova funkcija aktivirana';
</code>

==== Passaggio 4: Traduzione croata ====

<code pascal>
// WvdS.VSCode.Strings.HR.pas
resourcestring
  rsNewFeatureMessage = 'Nova funkcija aktivirana';
</code>

==== Passaggio 5: Usare nel codice ====

<code pascal>
ShowInfoMessage(rsNewFeatureMessage);
</code>

===== Selezione lingua a runtime =====

La lingua viene letta dalle impostazioni VS Code:

<code pascal>
function GetCurrentLanguage: string;
begin
  Result := GetVSCodeLanguage;  // es. 'de', 'en', 'sl', 'hr'
end;

procedure LoadLanguageStrings;
var
  Lang: string;
begin
  Lang := GetCurrentLanguage;
  case Lang of
    'de': LoadGermanStrings;
    'sl': LoadSlovenianStrings;
    'hr': LoadCroatianStrings;
  else
    // Inglese come fallback
    LoadEnglishStrings;
  end;
end;
</code>

===== Validazione =====

==== Controllo i18n wvds-lint ====

<code bash>
wvds-lint i18n --path sources/
</code>

Viene verificato:
  * Stringhe hardcoded nel codice
  * Traduzioni mancanti
  * Resourcestrings non utilizzate
  * Coerenza format-string (stesso numero di %s, %d)

==== Checklist ====

<code>
[ ] Stringa inglese definita
[ ] Traduzione tedesca aggiunta
[ ] Traduzione slovena aggiunta
[ ] Traduzione croata aggiunta
[ ] Parametri formato corrispondono
[ ] Usata nel codice (non hardcoded)
[ ] wvds-lint i18n superato
</code>

===== Best practice =====

==== Stringhe chiare e senza contesto ====

<code pascal>
// BUONO - Autoesplicativo
rsFileNotFound = 'File not found: %s';

// CATTIVO - Manca contesto
rsNotFound = 'Not found: %s';  // Cosa non e stato trovato?
</code>

==== Preferire frasi complete ====

<code pascal>
// BUONO
rsProjectCreatedSuccessfully = 'Project ''%s'' was created successfully.';

// CATTIVO - Frammenti
rsProject = 'Project';
rsCreated = 'created';
rsSuccessfully = 'successfully';
// UI: rsProject + ' ' + Name + ' ' + rsCreated + ' ' + rsSuccessfully
// Problema: L'ordine delle parole varia tra le lingue!
</code>

==== Terminologia consistente ====

| Termine | Inglese | Tedesco |
| Build | Build | Build (non "Erstellung") |
| Compile | Compile | Kompilieren |
| Path | Path | Pfad |
| Settings | Settings | Einstellungen |

===== Vedi anche =====

  * [[.:code-konventionen|Convenzioni del codice]]
  * [[.:extension-entwicklung|Sviluppo estensioni]]