Packagevertalingen overschrijven en bijwerken

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 behandelt de basisbewerkingen in een applicatie en Laravel-packages ontwikkelen de basis van registreren en publiceren. Deze pagina duikt in de implementatie van ServiceProvider, FileLoader en Translator in Laravel 13.

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.

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.

courier/
├── src/
│   └── CourierServiceProvider.php
└── lang/
    ├── en/
    │   └── messages.php
    └── ja/
        └── messages.php

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

<?php

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

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

<?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

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.

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

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. 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

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.

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.

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

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

{
  "Courier delivery queued": "配送を受け付けました。"
}

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.

{
  "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.

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.

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.

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.

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.

Voor langetermijnonderhoud ontwerp je updates in de volgende volgorde.

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.
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.
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.
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.
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, en de compatibiliteitsafwegingen bij versie-updates in Versiecompatibiliteit van packages beheren.

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.

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.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Packagevertalingen overschrijven en bijwerken

Wat je op deze pagina bereikt

PHP-vertalingen met een namespace distribueren

PHP-vertalingen vervangen niet het hele bestand

Laadvolgorde van FileLoader

JSON-vertalingen hebben geen eigen namespace per package

JSON wordt overschreven in de ja.json van de applicatie

Gepubliceerde vertalingen bijwerken zonder ze te breken

Wat je in de gebruikende applicatie controleert

Geraadpleegde primaire bronnen

​Wat je op deze pagina bereikt

​PHP-vertalingen met een namespace distribueren

​PHP-vertalingen vervangen niet het hele bestand

​Laadvolgorde van FileLoader

​JSON-vertalingen hebben geen eigen namespace per package

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

​Gepubliceerde vertalingen bijwerken zonder ze te breken

​Wat je in de gebruikende applicatie controleert

​Geraadpleegde primaire bronnen

Wat je op deze pagina bereikt

PHP-vertalingen met een namespace distribueren

PHP-vertalingen vervangen niet het hele bestand

Laadvolgorde van FileLoader

JSON-vertalingen hebben geen eigen namespace per package

JSON wordt overschreven in de ja.json van de applicatie

Gepubliceerde vertalingen bijwerken zonder ze te breken

Wat je in de gebruikende applicatie controleert

Geraadpleegde primaire bronnen