Popisy z prekladových súborov

K dispozícii od verzie 1.1.0. Pridajte atribút #[TranslatedLabels] na enum s traitom Helpers a každý popis sa namiesto výsledku Str::headline() načíta z prekladovej skupiny — v štruktúre, akú má väčšina aplikácií už v lang/<locale>/enums.php:

use RoundlyConsulting\Enums\Attributes\TranslatedLabels;
use RoundlyConsulting\Enums\Helpers;

#[TranslatedLabels]                 // keys: enums.order_status.<value>
enum OrderStatus: string
{
    use Helpers;

    case Pending = 'pending';
    case Shipped = 'shipped';
}

// lang/sk/enums.php
return [
    'order_status' => [
        'pending' => 'Čaká na platbu',
        'shipped' => 'Na ceste',
    ],
];

app()->setLocale('sk');

OrderStatus::Pending->label();      // 'Čaká na platbu'
OrderStatus::toArray();             // ['pending' => 'Čaká na platbu', 'shipped' => 'Na ceste']
OrderStatus::options();             // EnumOption DTOs with the same labels, shape unchanged
OrderStatus::fromLabel('Na ceste'); // OrderStatus::Shipped

Preklad sa prejaví vo všetkých zoznamoch postavených na popisoch — labels(), toOptions(), toArray(), options(), presentations(), fromLabel() aj tryFromLabel() — a options() si zachová svoj tvar. Enumy bez atribútu sa správajú presne ako doteraz.

Skupina

#[TranslatedLabels]                                // enums.order_status.<value>
#[TranslatedLabels('enums.checkout_status')]       // an explicit group
#[TranslatedLabels('enums.http_method')]           // HTTPMethod would snake to enums.h_t_t_p_method
#[TranslatedLabels('billing::enums.order_status')] // a package's own translation files

• Bez argumentu je skupinou enums. a názov triedy v snake_case: OrderStatus → enums.order_status, ToolAuth → enums.tool_auth.
• Názov triedy so skratkou sa prevedie písmeno po písmene (HTTPMethod → enums.h_t_t_p_method), preto takú skupinu zadajte explicitne.
• Balík popíše vlastné enumy z vlastných súborov cez skupinu s menným priestorom: 'billing::enums.order_status' číta resources/lang/<locale>/enums.php zaregistrovaný pod prekladovým menným priestorom billing.
• Prázdna skupina alebo skupina, ktorá začína či končí medzerou, . alebo :, by nikdy nič nenašla, preto pri prvom použití vyhodí EnumException::invalidLabelGroup() namiesto tichého návratu k Str::headline().
• Atribút patrí priamo na enum a na enume bez traitu Helpers nemá žiadny účinok.

Kľúče a poradie vyhľadávania

Kľúčom je <group>.<value>: hodnota pri reťazcových a celočíselných enumoch (enums.priority.5, enums.priority.-1) a názov prípadu pri čistých enumoch (enums.visibility.Public). Pri každom popise readable() skúša:

• Najprv kľúč v skupine pre aktuálny jazyk, potom pre fallback_locale — oboje zariadi prekladač Laravelu. Ak riadok existuje, použije sa.
• Inak doterajšie správanie bez zmeny: výsledok Str::headline() (Pending), vyhľadaný ako JSON alebo skupinový riadok, a napokon samotný výsledok Str::headline().

Pridanie atribútu teda nikdy nerozbije enum, ktorý ešte nemá vyplnené kľúče: chýbajúce prípady si ponechajú popisy zo Str::headline(), kým riadky doplníte. Kľúč, ktorý namiesto riadku vedie na vnorené pole, sa počíta ako nenájdený. Handler chýbajúcich kľúčov zaregistrovaný cez Lang::handleMissingKeysUsing() sa pri nenájdenom kľúči v skupine zavolá rovnako ako pri __() a jeho návratová hodnota sa stane popisom.

Hodnoty s bodkou sa nikdy nenájdu: prekladač číta bodku ako vnorenie, takže kľúč enums.release.v1.0 hľadá ['release']['v1']['0'], nikdy nie riadok s kľúčom 'v1.0'. Takým enumom prepíšte readable(); untranslated() ich nahlási.

Kontrola, že je preložené všetko

untranslated(?string $locale = null) vráti v poradí deklarácie prípady, ktorých kľúč v skupine nemá riadok presne v danom jazyku (predvolene v aktuálnom) — ideálne pre test, ktorý zlyhá, len čo by sa nasadil nepreložený prípad:

it('translates every order status', function (string $locale) {
    expect(OrderStatus::untranslated($locale))->toBeEmpty();
})->with(['en', 'sk']);

• Kontrola je striktná pre každý jazyk: riadok len vo fallback_locale sa aj tak nahlási, pretože používatelia daného jazyka by videli záložný text.
• S iným prekladačom než od Laravelu (bez hasForLocale()) sa použije get(), takže sa započíta aj riadok v záložnom jazyku daného prekladača.
• Kľúč, ktorý vedie na vnorené pole, aj hodnota s bodkou sa nahlásia, pretože ich nevie použiť ani readable().
• Na enume bez atribútu vyhodí EnumException::labelsNotTranslated().

Atribút sa pre každú triedu enumu načíta raz a zostane v cache po celý život procesu. Atribút sa za behu zmeniť nemôže, takže je to bezpečné aj pod Octane.