type-bridge-enum-translators

name	type-bridge-enum-translators
description	Generates TypeScript/JavaScript translator composables that map PHP enums to their i18n translation keys. Use when user says "generate enum translators", "enum translations for frontend", or needs to display translated enum labels in Vue components.

Laravel Type Bridge - Enum Translators

When to use this skill

Use this skill when you need to:

• Get translated labels for enum values in your frontend
• Create dropdown/select options from translated enums
• Display human-readable enum values with i18n support

Overview

This package generates per-enum translator composables that map enum values to translated labels using your configured i18n library. Check config/type-bridge.php for output paths and discovery settings.

Available Commands

# Generate enum translators using default format
php artisan type-bridge:enum-translators

# Force TypeScript format
php artisan type-bridge:enum-translators --format=ts

# Force JavaScript format
php artisan type-bridge:enum-translators --format=js

# Dry-run: discover candidates without writing files
php artisan type-bridge:enum-translators --dry

Setup Prerequisites

1. Publish Translator Utilities

Run once to publish required helper files:

php artisan type-bridge:publish-translator-utils [--force]

This publishes:

• composables/useTranslator.(ts|js)
• lib/createEnumTranslationMap.(ts|js)
• lib/translators.(ts|js)

2. Configure Translation Engine

In your app entry point (app.ts/main.ts):

TypeScript (i18next/react-i18next)

import i18n from '@/i18n';
import { configureTranslationEngine } from '@/composables/useTranslator';

configureTranslationEngine({
  t: (key: string) => i18n.t(key),
});

TypeScript (vue-i18n)

import { createI18n } from 'vue-i18n';
import { configureTranslationEngine } from '@/composables/useTranslator';

const i18nVue = createI18n({ /* ... */ });

configureTranslationEngine({
  t: (key: string) => i18nVue.global.t(key) as string,
});

Using Generated Translators

After generating translators and configuring the engine:

import { Status } from '@/enums/generated/Status';
import { createEnumTranslationMap } from '@/lib/createEnumTranslationMap';
import { useTranslator } from '@/composables/useTranslator';

const statusMap = createEnumTranslationMap(Status, 'Status');
const tStatus = useTranslator(statusMap);

// Translate an enum value
tStatus(Status.Active); // → "Active"

// Build select options for dropdowns
const options = tStatus.options();
// → [{ value: 'active', label: 'Active' }, ...]

// Filter to specific values only
const activeOptions = tStatus.options([Status.Active, Status.Pending]);
// → [{ value: 'active', label: 'Active' }, { value: 'pending', label: 'Pending' }]

// Override labels with a record
const customOptions = tStatus.options({ active: 'Enabled', pending: 'Awaiting' });
// → [{ value: 'active', label: 'Enabled' }, { value: 'pending', label: 'Awaiting' }]

// Check if a value has a translation mapping
const hasPending = tStatus.has(Status.Pending); // true/false

Opt-in Enum Translators

Use the #[GenerateTranslator] attribute on enums:

<?php

namespace App\Enums;

use GaiaTools\TypeBridge\Attributes\GenerateEnum;
use GaiaTools\TypeBridge\Attributes\GenerateTranslator;

#[GenerateEnum]
#[GenerateTranslator]
enum Status: string
{
    case Active = 'active';
    case Inactive = 'inactive';
    case Pending = 'pending';
}

Or use hasTranslator option on #[GenerateEnum]:

use GaiaTools\TypeBridge\Attributes\GenerateEnum;

#[GenerateEnum(hasTranslator: true)]
enum Status: string { ... }

Translation Key Format

Translation keys follow this pattern: {EnumName}.{caseName}

In your lang files (e.g., lang/en/status.php):

<?php

return [
    'active' => 'Active',
    'inactive' => 'Inactive',
    'pending' => 'Pending',
];

Or nested:

return [
    'status' => [
        'active' => 'Active',
        'inactive' => 'Inactive',
    ],
];

Dry-Run Output

Use --dry to see eligible enums before generating:

Enum                          Prefix     In FE Set   Has Translations
App\Enums\Status              Status     Yes         Yes
App\Enums\OrderStatus         OrderStatus Yes        No

Only enums that are both in the frontend generation set AND have translations are eligible.