> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Modalità nativa - Dizionario utente - VOICEVOX for Laravel

> Come usare il dizionario utente nella modalità nativa di VOICEVOX for Laravel per registrare, aggiornare e importare la lettura di nomi propri e termini specialistici.

## Cos'è il dizionario utente

Con il dizionario utente puoi far memorizzare a VOICEVOX la lettura di nomi propri e termini specialistici. Le parole registrate vengono pronunciate correttamente durante la sintesi vocale.

## Panoramica

La funzionalità di dizionario utente di Laravel VOICEVOX è un'implementazione nativa che usa lo UserDict di VOICEVOX Core. I dati del dizionario vengono persistiti in formato JSON in `storage/voicevox/user_dict.json`.

<Info>
  Poiché utilizza uno storage indipendente dal VOICEVOX Engine ufficiale, le parole registrate lato Laravel non si riflettono lato engine ufficiale (e viceversa).
</Info>

## Configurazione

Per impostazione predefinita vengono salvate in `storage/voicevox/user_dict.json`. Se vuoi usare un percorso diverso, puoi cambiarlo in `config/voicevox.php`.

```php theme={null}
// config/voicevox.php

return [
    'core' => [
        'user_dict' => storage_path('voicevox/user_dict.json'),
    ],
];
```

## Uso di base

### Aggiungere una parola

Registra una parola con `add()` dell'helper `dict()`.

```php theme={null}
use function Revolution\Voicevox\dict;

$uuid = dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// Viene restituito un UUID senza "-"
// Esempio: "550e8400e29b41d4a716446655440000"
```

#### Parametri

* `surface` (obbligatorio): forma scritta
* `pronunciation` (obbligatorio): lettura (solo katakana)
* `accentType` (obbligatorio): tipo di accento (`0` = piatto, `1` o più = posizione dell'accento)
* `wordType` (opzionale): categoria grammaticale (`COMMON_NOUN`, `PROPER_NOUN`, `VERB`, `ADJECTIVE`, `SUFFIX`)
* `priority` (opzionale): priorità (predefinito `5`)

#### Tipo di accento

* `0`: accento piatto
* `1`: prima mora
* `2`: seconda mora
* `3`: terza mora

### Aggiornare una parola

```php theme={null}
use function Revolution\Voicevox\dict;

dict()->update(
    wordUuid: '550e8400-e29b-41d4-a716-446655440000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);
```

### Eliminare una parola

```php theme={null}
use function Revolution\Voicevox\dict;

dict()->delete('550e8400-e29b-41d4-a716-446655440000');
```

### Recuperare tutte le parole

```php theme={null}
use function Revolution\Voicevox\dict;

$words = dict()->all();
// oppure
$words = dict()->toArray();
```

### Importare un dizionario

```php theme={null}
use function Revolution\Voicevox\dict;

$json = file_get_contents('other_user_dict.json');
dict()->import($json, override: false);

// Con override: true sovrascrive
dict()->import($json, override: true);
```

### Esportare il dizionario

```php theme={null}
use function Revolution\Voicevox\dict;

$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);
```

## Accesso tramite API Engine

Quando è avviata l'API Engine di Laravel VOICEVOX, puoi gestire il dizionario utente anche via HTTP. Non c'è fallback verso l'engine ufficiale: viene usato il dizionario nativo.

### Recuperare tutte le parole

```bash theme={null}
curl http://localhost:50513/user_dict
```

### Aggiungere una parola

```bash theme={null}
curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"
```

### Aggiornare una parola

```bash theme={null}
curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"
```

### Eliminare una parola

```bash theme={null}
curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"
```

### Importare un dizionario

```bash theme={null}
curl -X POST "http://localhost:50513/import_user_dict?override=false" \
  -H "Content-Type: application/json" \
  -d @other_dict.json
```

<Tip>
  Se specifichi `override=true`, tutte le parole del dizionario esistente vengono eliminate prima dell'importazione.
</Tip>

## Sintesi vocale dopo la registrazione nel dizionario

Le parole registrate nel dizionario utente vengono consultate automaticamente durante la sintesi vocale.

```php theme={null}
use function Revolution\Voicevox\{dict, talk};

dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

$response = talk('Laravelで開発するのは楽しいです', id: 1)->generate(id: 1);
$response->storeAs('native', 'laravel.wav');
```

## Note

<Warning>
  In `pronunciation` specifica solo katakana. Hiragana e kanji non sono ammessi.
</Warning>

* Il dizionario utente della versione Laravel e quello del VOICEVOX Engine ufficiale sono gestiti separatamente.
* Le operazioni di aggiunta, aggiornamento ed eliminazione delle parole vengono salvate immediatamente nel file JSON.
* Se non conosci il tipo di accento, prova prima `0` (piatto).

## Risoluzione dei problemi

### La parola non viene applicata

1. Controlla i permessi di scrittura sulla directory di storage
2. Verifica che `storage/voicevox/user_dict.json` sia stato creato correttamente
3. Controlla che la scrittura in katakana sia corretta

### Non trovi il percorso del file del dizionario

```php theme={null}
$path = config('voicevox.core.user_dict');
echo $path;
```

### Reimpostare il dizionario

```bash theme={null}
rm storage/voicevox/user_dict.json
```

```php theme={null}
$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
    unlink($path);
}
```


## Related topics

- [Modalità client - Dizionario utente - VOICEVOX for Laravel](/it/packages/laravel-voicevox/client-user-dict.md)
- [Modalità nativa - Preset - VOICEVOX for Laravel](/it/packages/laravel-voicevox/native-presets.md)
- [Modalità nativa: Song (sintesi vocale canora) - VOICEVOX for Laravel](/it/packages/laravel-voicevox/native-song.md)
- [Modalità nativa: Talk (sintesi vocale da testo) - VOICEVOX for Laravel](/it/packages/laravel-voicevox/native-talk.md)
- [Introduzione - VOICEVOX for Laravel](/it/packages/laravel-voicevox/getting-started.md)