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

# Packagevertalingen overschrijven en bijwerken

> Een analyse van de vertaalloader van Laravel 13: gedeeltelijk overschrijven van PHP-vertalingen, gedeelde sleutels in JSON-vertalingen en het bijwerken zonder gepubliceerde vertalingen te breken.

## Wat je op deze pagina bereikt

Je distribueert de berichten van een package in meerdere talen, zodat de gebruikende applicatie alleen de teksten kan wijzigen die nodig zijn. We behandelen vertaalsleutels en placeholders als publieke API en zetten op een rij hoe je aanpassingen behoudt wanneer het package wordt bijgewerkt.

[Lokalisatie](/nl/localization) behandelt de basisbewerkingen in een applicatie en [Laravel-packages ontwikkelen](/nl/advanced/package-development) de basis van registreren en publiceren. Deze pagina duikt in de implementatie van `ServiceProvider`, `FileLoader` en `Translator` in Laravel 13.

<Info>
  `loadTranslationsFrom()` registreert waar vertalingen worden geladen, `publishes()` registreert waarheen bestanden worden gekopieerd. Gebruikers hoeven niet per se `vendor:publish` uit te voeren om de vertalingen te kunnen gebruiken.
</Info>

## PHP-vertalingen met een namespace distribueren

Wil je sleutels die specifiek bij het package horen, gebruik dan het PHP-arrayformaat met een namespace. Hieronder een voorbeeld van een package genaamd `Acme\Courier`.

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

Zet de Japanse standaardwaarden in `lang/ja/messages.php`.

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

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

Zorg in `lang/en/messages.php` ook voor Engels als fallback.

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

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

Registreer in de `boot()` van de service provider het laden en het optionele publiceren.

```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');
    }
}
```

Bij gebruik geef je de namespace, de bestandsnaam en de arraysleutel op. Als taalcode gebruik je `ja`, in overeenstemming met de Laravel-configuratie. Dit staat los van `jp`, dat in de URL's van deze documentatiesite wordt gebruikt.

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

De namespace `courier` is het tweede argument van `loadTranslationsFrom()`. Deze wordt niet automatisch afgeleid van de Composer-packagenaam.

## PHP-vertalingen vervangen niet het hele bestand

In de gebruikende applicatie kun je, bij de standaard taalmap, alleen de te wijzigen sleutels in `lang/vendor/courier/ja/messages.php` zetten. Ook als je de taalmap hebt gewijzigd, gebruik je de locatie onder `$this->app->langPath('vendor/courier')`.

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

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

In dit voorbeeld verandert alleen `queued`; voor `failed` wordt de Japanse vertaling van het package gebruikt.

### Laadvolgorde van FileLoader

`ServiceProvider::loadTranslationsFrom()` registreert de namespace nadat de Translator is opgelost. Het daadwerkelijk ophalen van bestanden gebeurt pas wanneer een vertaling wordt opgevraagd.

`FileLoader::loadNamespaced()` laadt de taalbestanden van het geregistreerde package en geeft die array door aan `loadNamespaceOverrides()`. Daar wordt in elk taalpad van de loader `vendor/{namespace}/{locale}/{group}.php` gelezen en met `array_replace_recursive()` vervangen.

```mermaid theme={null}
flowchart TD
    A["courier::messages.delivery.queued<br>locale: ja"] --> B["lang/ja/messages.php<br>van het package"]
    B --> C["lang/vendor/courier/ja/messages.php<br>van de applicatie"]
    C --> D["Opgegeven sleutels vervangen<br>met array_replace_recursive"]
    D --> E["Vertaalstring ophalen en<br>placeholders vervangen"]
```

De standaard `TranslationServiceProvider` geeft het taalpad van het framework en dat van de applicatie in deze volgorde door aan de loader. Ook als een extensie extra paden registreert, krijgt de later geladen overschrijvingsarray voorrang voor dezelfde sleutel.

| Situatie | Resultaat |
| - | - |
| De sleutel staat in de applicatie | Die waarde overschrijft de waarde van het package |
| Hetzelfde bestand bestaat, maar zonder de sleutel | De waarde van het package in dezelfde taal blijft behouden |
| De sleutel wordt niet gevonden in de gevraagde taal | Normaal wordt de PHP-vertaling van `fallback_locale` doorzocht |
| De sleutel ontbreekt ook in de fallback | Standaard wordt de gevraagde sleutel teruggegeven |

<Warning>
  Als de namespace niet is geregistreerd, geeft `FileLoader::loadNamespaced()` een lege array terug. Alleen bestanden in `lang/vendor/courier` plaatsen compenseert geen ontbrekende registratie in de service provider. Registreert een ander package dezelfde namespace, dan wordt de registratielocatie vervangen; kies daarom een naam die niet botst.
</Warning>

## JSON-vertalingen hebben geen eigen namespace per package

Voor JSON-vertalingen met zinnen als sleutel registreer je de map als volgt. Dit is een alternatief voor de eerder getoonde PHP-vertalingen.

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

Een voorbeeld van `lang/ja.json` in het package:

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

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

`loadJsonTranslationsFrom()` heeft geen namespace-argument. Geregistreerde JSON-vertalingen delen dezelfde sleutelruimte met andere packages en de applicatie.

### JSON wordt overschreven in de ja.json van de applicatie

`FileLoader::loadJsonPaths()` leest eerst de geregistreerde JSON-paden, daarna de gewone taalpaden, en voegt ze samen met `array_merge()`. In de standaardconfiguratie overschrijft dezelfde stringsleutel in `lang/ja.json` van de applicatie de waarde van het package.

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

* Gebruiken packages dezelfde stringsleutel, dan krijgt de waarde uit de later geladen JSON voorrang. Vermijd een ontwerp dat afhankelijk is van de volgorde van providers.
* `lang/vendor/courier/ja.json` is geen overschrijvingslocatie voor de standaard JSON-loader. Ook als je de publicatieconfiguratie voor PHP ongewijzigd voor JSON hergebruikt, wordt deze locatie niet automatisch gelezen.
* Ook als je de JSON van het package met `publishes()` naar `lang/ja.json` van de applicatie publiceert, wordt de inhoud van het bestand niet samengevoegd. Beschrijf een procedure waarbij gebruikers alleen de benodigde sleutels toevoegen, zodat bestaande vertalingen niet kapotgaan.

<Warning>
  `Translator::get()` controleert eerst de JSON van de gevraagde taal en zoekt, als daar niets wordt gevonden, verder als sleutel in PHP-formaat. Er wordt niet, zoals bij PHP-vertalingen, ook de JSON van de fallbacktaal doorzocht. Gebruik je Engelse zinnen als JSON-sleutels, onderscheid dit dan van het standaardgedrag waarbij de originele sleutel wordt getoond als er geen vertaling is.
</Warning>

De namespace van PHP-vertalingen scheidt de PHP-sleutels van andere packages. Omdat `Translator::get()` echter eerst exact overeenkomende JSON-sleutels controleert, krijgt een JSON-sleutel als `courier::messages.delivery.queued` voorrang op de PHP-kant. Hanteer normaal gesproken het beleid om zinnen als sleutel en sleutels in PHP-formaat niet te mengen.

## Gepubliceerde vertalingen bijwerken zonder ze te breken

Gebruikers die de PHP-vertalingen in één keer willen publiceren, kun je een gericht commando aanraden.

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

Let wel: als je alle standaardwaarden kopieert, is die kopie voortaan ook een overschrijvingswaarde. Corrigeert het package een typfout, dan zie je de nieuwe waarde niet zolang dezelfde sleutel in het gepubliceerde bestand staat. Nieuwe sleutels die niet in de kopie staan, worden daarentegen aangevuld vanuit het package.

<Tip>
  Wil je maar een paar teksten wijzigen, publiceer dan niet alle bestanden, maar zet alleen de benodigde sleutels in het overschrijvingsbestand. Zo neem je updates makkelijker over. Deze werkwijze maakt gebruik van het gedeeltelijk overschrijven van PHP-vertalingen.
</Tip>

Voor langetermijnonderhoud ontwerp je updates in de volgende volgorde.

1. **Behoud sleutels en namespace** — Het verwijderen of verplaatsen van sleutels raakt de `__()`-aanroepen van gebruikers en hun overschrijvingen. Overweeg een overgangsperiode waarin je nieuwe sleutels toevoegt en de oude laat staan.
2. **Behoud placeholders** — Wijzig je `:name` in `:recipient`, dan moet ook de vervangingsarray aan de aanroepende kant worden aangepast. Zie het niet als een wijziging die alleen het vertaalbestand betreft.
3. **Controleer gepubliceerde bestanden op verschillen** — Vergelijk de overschrijvingen van gebruikers met de nieuwe standaardwaarden. Door overbodige overschrijvingssleutels te verwijderen, val je terug op de waarden van het package.
4. **Vermijd onvoorwaardelijk opnieuw publiceren** — Opnieuw publiceren met `--force` overschrijft de aanpassingen van gebruikers. Bij een ontwerp dat JSON naar het bestand van de applicatie kopieert, kun je zelfs andere vertalingen kwijtraken.
5. **Controleer in langlopende processen** — `Translator::load()` bewaart arrays per namespace, groep en taal in de instantie. In processen waarin een Translator met al geladen vertalingen blijft bestaan, wordt niet per se opnieuw geladen alleen doordat een bestand wijzigt. Herstart workers en dergelijke afhankelijk van je werkwijze.

Het kiezen van het bereik bij publiceren en de overschrijfopties worden aangevuld in [Publieke assets van packages publiceren en bijwerken](/nl/advanced/package-assets), en de compatibiliteitsafwegingen bij versie-updates in [Versiecompatibiliteit van packages beheren](/nl/advanced/package-versioning).

## Wat je in de gebruikende applicatie controleert

Controleer in een testapplicatie waarin de service provider is geregistreerd de volgende combinaties. Voor het opzetten van de testomgeving binnen het package zie je [Laravel-packages testen met Orchestra Testbench](/nl/advanced/package-testing).

| Geval | Wat je controleert |
| - | - |
| PHP-vertalingen niet gepubliceerd | Het Japans en Engels van het package kunnen worden opgehaald |
| Alleen het Japanse `queued` overschreven | `queued` verandert, `failed` blijft de standaardwaarde |
| Sleutel toegevoegd bij een package-update | Ook sleutels die niet in het bestaande overschrijvingsbestand staan, kunnen worden opgehaald |
| Sleutel ontbreekt in de gevraagde taal | PHP-vertalingen worden opgehaald uit de ingestelde fallbacktaal |
| Dezelfde sleutel gedefinieerd in JSON | In de standaardconfiguratie krijgt de JSON van de applicatie voorrang |
| JSON alleen in `lang/vendor/courier` geplaatst | In de standaardconfiguratie overschrijft dit de JSON niet |
| Vertaling met `:name` | Komt overeen met de vervangingsarray van de aanroeper; er blijven geen onvervangen strings over |

Zorg er in tests die na het laden een overschrijvingsbestand aanmaken voor dat de al geladen resultaten van de Translator geen invloed hebben. Maak de bestanden aan voordat je ophaalt, of gebruik per geval een nieuwe applicatie-instantie.

## Geraadpleegde primaire bronnen

De officiële documentatie is gecontroleerd op de nieuwste standaardbranch `13.x`, de interne implementatie op de op het moment van raadplegen nieuwste release `v13.35.0`.

* [Officiële Laravel-documentatie: Taalbestanden van packages](https://github.com/laravel/docs/blob/13.x/packages.md#language-files)
* [Officiële Laravel-documentatie: Packagevertalingen overschrijven](https://github.com/laravel/docs/blob/13.x/localization.md#overriding-package-language-files)
* [ServiceProvider: vertalingen registreren](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Support/ServiceProvider.php)
* [TranslationServiceProvider: standaard taalpaden](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Translation/TranslationServiceProvider.php)
* [FileLoader: recursief vervangen voor PHP en laadvolgorde van JSON](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Translation/FileLoader.php)
* [Translator: ophalen met JSON-voorrang en al geladen arrays](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Translation/Translator.php)
* [Officiële tests: vertaalloader](https://github.com/laravel/framework/blob/v13.35.0/tests/Translation/TranslationFileLoaderTest.php)


## Related topics

- [Laravel-packages ontwikkelen](/nl/advanced/package-development.md)
- [Geavanceerde onderwerpen](/nl/advanced/index.md)
- [Views van packages overschrijven en bijwerken](/nl/advanced/package-views.md)
- [Publieke assets van packages publiceren en bijwerken](/nl/advanced/package-assets.md)
- [Migrations van packages publiceren en bijwerken](/nl/advanced/package-migrations.md)


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