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

# Sovrascrittura e aggiornamento delle traduzioni di un pacchetto

> Analizza il loader delle traduzioni di Laravel 13 e spiega la sovrascrittura parziale delle traduzioni PHP, le chiavi condivise delle traduzioni JSON e come aggiornare senza rompere le traduzioni già pubblicate.

## Obiettivo di questa pagina

Distribuire i messaggi di un pacchetto in più lingue, permettendo all'applicazione che lo utilizza di modificare solo i testi necessari. Vedremo anche come trattare chiavi di traduzione e placeholder come API pubblica e come preservare le personalizzazioni quando il pacchetto viene aggiornato.

[Localizzazione](/it/localization) tratta le operazioni di base nell'applicazione, mentre [Sviluppo di pacchetti Laravel](/it/advanced/package-development) tratta le basi della registrazione e della pubblicazione. Questa pagina entra nell'implementazione di `ServiceProvider`, `FileLoader` e `Translator` di Laravel 13.

<Info>
  `loadTranslationsFrom()` registra il percorso da cui caricare le traduzioni, mentre `publishes()` registra la destinazione in cui copiare i file. Per usare le traduzioni, l'utente non deve necessariamente eseguire `vendor:publish`.
</Info>

## Distribuire traduzioni PHP con un namespace

Se vuoi chiavi dedicate al pacchetto, usa il formato ad array PHP con un namespace. Di seguito l'esempio di un pacchetto chiamato `Acme\Courier`.

```text theme={null}
courier/
├── src/
│   └── CourierServiceProvider.php
└── lang/
    ├── en/
    │   └── messages.php
    └── ja/
        └── messages.php
```

Prepara i valori predefiniti in giapponese in `lang/ja/messages.php`.

```php theme={null}
<?php

return [
    'delivery' => [
        'queued' => ':nameさんへの配送を受け付けました。',
        'failed' => '配送できませんでした。',
    ],
];
```

Prepara anche l'inglese di fallback in `lang/en/messages.php`.

```php theme={null}
<?php

return [
    'delivery' => [
        'queued' => 'Delivery to :name has been queued.',
        'failed' => 'Delivery failed.',
    ],
];
```

Registra il caricamento e la pubblicazione facoltativa nel metodo `boot()` del service provider.

```php theme={null}
<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

        $this->publishes([
            __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
        ], 'courier-translations');
    }
}
```

Chi utilizza il pacchetto specifica namespace, nome del file e chiave dell'array. Il codice della lingua segue la configurazione di Laravel e usa `ja`, che è diverso da `jp` usato negli URL di questo sito di documentazione.

```php theme={null}
echo __('courier::messages.delivery.queued', ['name' => '山田'], 'ja');
```

Il namespace `courier` è il secondo argomento di `loadTranslationsFrom()`. Non viene determinato automaticamente dal nome del pacchetto Composer.

## Le traduzioni PHP non sostituiscono l'intero file

Nell'applicazione che utilizza il pacchetto, con la directory delle lingue standard, puoi scrivere in `lang/vendor/courier/ja/messages.php` solo le chiavi da modificare. Anche se hai cambiato la directory delle lingue, usa il percorso sotto `$this->app->langPath('vendor/courier')`.

```php theme={null}
<?php

return [
    'delivery' => [
        'queued' => ':name様への配送予約が完了しました。',
    ],
];
```

In questo esempio cambia solo `queued`, mentre `failed` usa la traduzione giapponese del pacchetto.

### Ordine di caricamento di FileLoader

`ServiceProvider::loadTranslationsFrom()` registra il namespace dopo la risoluzione del Translator. Il recupero effettivo dei file avviene quando viene richiesta una traduzione.

`FileLoader::loadNamespaced()` legge i file di lingua del pacchetto registrato e passa l'array a `loadNamespaceOverrides()`. Qui vengono letti i file `vendor/{namespace}/{locale}/{group}.php` presenti in ciascun percorso delle lingue del loader e i valori vengono sostituiti con `array_replace_recursive()`.

```mermaid theme={null}
flowchart TD
    A["courier::messages.delivery.queued<br>locale: ja"] --> B["lang/ja/messages.php<br>del pacchetto"]
    B --> C["lang/vendor/courier/ja/messages.php<br>dell'applicazione"]
    C --> D["Sostituzione delle chiavi indicate<br>con array_replace_recursive"]
    D --> E["Recupero della stringa tradotta e<br>sostituzione dei placeholder"]
```

Il `TranslationServiceProvider` standard passa al loader il percorso delle lingue del framework e quello dell'applicazione, in quest'ordine. Anche se un'estensione registra percorsi aggiuntivi, per la stessa chiave prevale l'array di sovrascrittura caricato per ultimo.

| Stato | Risultato |
| - | - |
| La chiave esiste nell'applicazione | Il suo valore sovrascrive quello del pacchetto |
| Il file esiste ma la chiave no | Viene mantenuto il valore del pacchetto nella stessa lingua |
| La chiave non esiste nella lingua richiesta | Di norma si cerca la traduzione PHP di `fallback_locale` |
| La chiave non esiste nemmeno nel fallback | Con il comportamento standard viene restituita la chiave richiesta |

<Warning>
  Se il namespace non è registrato, `FileLoader::loadNamespaced()` restituisce un array vuoto. Mettere semplicemente i file in `lang/vendor/courier` non compensa la mancata registrazione nel service provider. Inoltre, se un altro pacchetto registra lo stesso namespace, la destinazione registrata viene sostituita: scegli quindi un nome che non generi conflitti.
</Warning>

## Le traduzioni JSON non hanno un namespace dedicato al pacchetto

Per le traduzioni JSON, che usano il testo come chiave, registra la directory come segue. Si tratta di un'alternativa rispetto alle traduzioni PHP viste sopra.

```php theme={null}
public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}
```

Esempio di `lang/ja.json` del pacchetto.

```json theme={null}
{
  "Courier delivery queued": "配送を受け付けました。"
}
```

```php theme={null}
echo __('Courier delivery queued', [], 'ja');
```

`loadJsonTranslationsFrom()` non ha un argomento per il namespace. Le traduzioni JSON registrate condividono lo stesso spazio delle chiavi con gli altri pacchetti e con l'applicazione.

### La destinazione della sovrascrittura JSON è il ja.json dell'applicazione

`FileLoader::loadJsonPaths()` legge prima i percorsi JSON registrati, poi i normali percorsi delle lingue, e li unisce con `array_merge()`. Nella configurazione standard, la stessa chiave stringa nel file `lang/ja.json` dell'applicazione sovrascrive il valore del pacchetto.

```json theme={null}
{
  "Courier delivery queued": "配送予約が完了しました。"
}
```

* Se più pacchetti usano la stessa chiave stringa, prevale il valore del JSON caricato per ultimo. Evita progettazioni che dipendono dall'ordine dei provider.
* `lang/vendor/courier/ja.json` non è una destinazione di sovrascrittura del loader JSON standard. Anche riutilizzando per il JSON la configurazione di pubblicazione pensata per il PHP, questo percorso non viene letto automaticamente.
* Pubblicare con `publishes()` il JSON del pacchetto nel `lang/ja.json` dell'applicazione non unisce il contenuto dei file. Per non rompere le traduzioni esistenti, indica una procedura in cui l'utente aggiunge solo le chiavi necessarie.

<Warning>
  `Translator::get()` controlla prima il JSON della lingua richiesta e, se non trova nulla, cerca la chiave come chiave in formato PHP. Non esiste un processo che, come per le traduzioni PHP, cerchi in sequenza fino al JSON della lingua di fallback. Se usi frasi in inglese come chiavi JSON, distingui questo caso dal comportamento standard per cui, in assenza di traduzione, viene mostrata la chiave originale.
</Warning>

Il namespace delle traduzioni PHP isola le chiavi PHP dagli altri pacchetti. Tuttavia, poiché `Translator::get()` cerca prima una corrispondenza esatta nel JSON, se nel JSON definisci una chiave come `courier::messages.delivery.queued`, questa avrà la precedenza sul lato PHP. Di norma conviene non mescolare chiavi testuali e chiavi in formato PHP.

## Aggiornare senza rompere le traduzioni pubblicate

Agli utenti che vogliono pubblicare in blocco le traduzioni PHP puoi indicare un comando con un ambito ristretto.

```bash theme={null}
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider" --tag=courier-translations
```

Tuttavia, se copi tutti i valori predefiniti, da quel momento anche la copia diventa un insieme di valori di sovrascrittura. Anche se correggi un refuso nel pacchetto, il nuovo valore non sarà visibile finché la stessa chiave resta nel file pubblicato. Le nuove chiavi assenti dalla copia, invece, vengono integrate dal pacchetto.

<Tip>
  Se devi modificare solo pochi testi, è più facile recepire gli aggiornamenti mettendo nel file di sovrascrittura solo le chiavi necessarie, invece di pubblicare tutti i file. È un approccio che sfrutta la sovrascrittura parziale delle traduzioni PHP.
</Tip>

Per la manutenzione a lungo termine, progetta gli aggiornamenti nel seguente ordine.

1. **Mantieni chiavi e namespace** — Eliminare o spostare una chiave influisce sulle chiamate `__()` degli utenti e sulle destinazioni di sovrascrittura. Valuta di aggiungere nuove chiavi mantenendo le vecchie per un periodo di transizione.
2. **Mantieni i placeholder** — Se cambi `:name` in `:recipient`, deve cambiare anche l'array di sostituzione del chiamante. Non considerarla una modifica che riguarda solo i file di traduzione.
3. **Confronta le differenze con i file pubblicati** — Confronta le sovrascritture dell'utente con i nuovi valori predefiniti. Eliminando le chiavi di sovrascrittura non più necessarie si torna ai valori del pacchetto.
4. **Evita le ripubblicazioni incondizionate** — La ripubblicazione con `--force` sovrascrive le personalizzazioni dell'utente. Con una progettazione che copia il JSON nel file dell'applicazione, potresti perdere anche altre traduzioni.
5. **Verifica nei processi persistenti** — `Translator::load()` mantiene nell'istanza gli array per namespace, gruppo e lingua. Nei processi in cui resta un Translator che ha già caricato le traduzioni, la sola modifica dei file non garantisce che vengano ricaricate. Riavvia i worker o processi simili in base al tuo ambiente.

La scelta dell'ambito di pubblicazione e le opzioni di sovrascrittura sono approfondite in [Asset pubblici e aggiornamento di un pacchetto](/it/advanced/package-assets), mentre la valutazione della compatibilità durante gli aggiornamenti di versione è trattata in [Gestire la compatibilità tra versioni dei pacchetti](/it/advanced/package-versioning).

## Cosa verificare nell'applicazione che utilizza il pacchetto

In un'applicazione di verifica in cui è registrato il service provider, controlla le seguenti combinazioni. Per configurare l'ambiente di test all'interno del pacchetto, consulta [Testare pacchetti Laravel con Orchestra Testbench](/it/advanced/package-testing).

| Caso | Cosa verificare |
| - | - |
| Traduzioni PHP non pubblicate | Si ottengono il giapponese e l'inglese del pacchetto |
| Sovrascritto solo `queued` in giapponese | `queued` cambia e `failed` resta il valore predefinito |
| Chiave aggiunta con un aggiornamento del pacchetto | Si ottengono anche le chiavi assenti dal file di sovrascrittura esistente |
| La chiave non esiste nella lingua richiesta | Le traduzioni PHP si ottengono dalla lingua di fallback configurata |
| Stessa chiave definita nel JSON | Nella configurazione standard prevale il JSON dell'applicazione |
| JSON presente solo in `lang/vendor/courier` | Nella configurazione standard non funziona come sovrascrittura JSON |
| Traduzione contenente `:name` | Corrisponde all'array di sostituzione del chiamante e non restano stringhe non sostituite |

Nei test che creano file di sovrascrittura dopo il caricamento, fai in modo che i risultati già caricati dal Translator non influiscano. Prepara prima i file e poi recupera le traduzioni, oppure usa una nuova istanza dell'applicazione per ogni caso.

## Fonti primarie consultate

Per la documentazione ufficiale è stato verificato l'ultimo branch predefinito `13.x`, mentre per l'implementazione interna l'ultima release disponibile al momento della consultazione, `v13.35.0`.

* [Documentazione ufficiale di Laravel: file di lingua dei pacchetti](https://github.com/laravel/docs/blob/13.x/packages.md#language-files)
* [Documentazione ufficiale di Laravel: sovrascrittura delle traduzioni dei pacchetti](https://github.com/laravel/docs/blob/13.x/localization.md#overriding-package-language-files)
* [ServiceProvider: registrazione delle traduzioni](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Support/ServiceProvider.php)
* [TranslationServiceProvider: percorsi delle lingue standard](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Translation/TranslationServiceProvider.php)
* [FileLoader: sostituzione ricorsiva PHP e ordine di caricamento JSON](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Translation/FileLoader.php)
* [Translator: recupero con priorità al JSON e array già caricati](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Translation/Translator.php)
* [Test ufficiali: loader delle traduzioni](https://github.com/laravel/framework/blob/v13.35.0/tests/Translation/TranslationFileLoaderTest.php)


## Related topics

- [Sviluppo di pacchetti Laravel](/it/advanced/package-development.md)
- [Argomenti avanzati](/it/advanced/index.md)
- [Asset pubblici e aggiornamento di un pacchetto](/it/advanced/package-assets.md)
- [Pubblicazione e aggiornamento delle migrazioni di un pacchetto](/it/advanced/package-migrations.md)
- [Registrazione e cache delle route di un pacchetto](/it/advanced/package-routes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.