All jobs

Add Internationalisation to a Filament Admin Panel from a Linear Issue

Yes. An agent moves a Filament panel's hard-coded labels into Laravel lang files, adds the locales the issue names with a parity test, and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the issue and the panel before it touches a string. In an app like filamentphp/demo, composer.json requires PHP 8.1 or newer, filament/filament on the 5.0 line, laravel/framework 12 and three Spatie Filament plugins, with Pest 3, Larastan and Pint for development; the test script runs pest --parallel and then PHPStan. config/app.php reads locale and fallback_locale from APP_LOCALE and APP_FALLBACK_LOCALE, both defaulting to en. There is no lang/ directory and no resources/lang/, and a search of app/ finds no call to __() or trans(): every label the panel shows is a literal in PHP.

The literals are in three kinds of places. Resources and schemas: app/Filament/Resources/Shop/Orders/Schemas/OrderForm.php has Section::make('Order items'), labels such as 'Order date', 'Last modified at' and 'Email address', a reset action with 'Are you sure?' and 'All existing items will be removed from the order.', and a customer modal headed 'Create customer'; Tables/OrdersTable.php has 'Shipping cost', 'Order date', 'Shipping notes' and 'Ship & notify customer'; Pages/CreateOrder.php sends a database notification titled 'New order' with a body built from the customer name. Enums: app/Enums/OrderStatus.php implements HasLabel with a match returning 'New', 'Processing', 'Shipped', 'Delivered' and 'Cancelled', and the other enums under app/Enums do the same. Navigation: AdminPanelProvider lists the groups Shop, HR, Projects and Blog as strings, and each resource sets $navigationGroup to one of them. Filament's own chrome, from the pagination controls to the "Save changes" button, ships with translations for many locales already, so the work is the application's strings only.

The agent creates lang/en/ with one file per area, shop.php, blog.php, hr.php, enums.php, navigation.php and notifications.php, keyed by resource and field so a translator sees where a string lives, and replaces each literal with __('shop.orders.fields.order_date') and the like. Enum labels become __('enums.order_status.new'), which keeps HasLabel working everywhere the enum is rendered. Navigation groups become NavigationGroup::make()->label(fn () => __('navigation.shop')) so the group name is resolved per request rather than at boot, and each resource's getNavigationGroup() returns the same translated value. The notification title and body in CreateOrder use translation keys with replacement parameters for the customer name and item count. For every locale the issue names, the agent adds the matching files under lang/<locale>/ with translated values, and leaves APP_LOCALE as the switch, since the panel reads the application locale on every request.

Tests guard the change. tests/Filament/LocalesTest.php loads each lang/en/*.php file and asserts every other locale has the same file with exactly the same keys, so a string added later in one language cannot go missing in another. A second test sets the application locale to one of the new locales, opens ListOrders with Livewire as tests/Filament/Resources/Shop/Orders/Pages/ListOrdersTest.php already does, and asserts the translated column heading and status label are in the rendered page. The existing CreateOrderTest keeps passing because the locale stays en and the new en value of the notification title is still New order, which that test compares. The agent runs composer test:pest, composer test:phpstan and vendor/bin/pint --test in the sandbox, where the repository's tests.yml runs the Pest suite on PHP 8.4 with SQLite and phpstan.yml and format.yml run the other two, and pastes the summaries in the pull request that links the issue.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Make the admin panel translatable. Move every user-facing string in our resources, schemas, tables, pages, widgets, enums and navigation into lang files, add Spanish and German, and add a test that keeps the locales in sync.\" Read composer.json, config/app.php, phpunit.xml, tests/Pest.php, tests/TestCase.php, .github/workflows/tests.yml, app/Providers/Filament/AdminPanelProvider.php, every file under app/Enums, app/Filament/Resources/Shop/Orders and tests/Filament/Resources/Shop/Orders first, then the other resources under app/Filament. Create lang/en with one file per area keyed by resource and field, replace each literal label, heading, modal text, action name, notification title and enum label with __() calls, make navigation groups resolve their labels through NavigationGroup::make()->label(), and add lang/es and lang/de with the same files and keys. Leave Filament's own translations and the config locale defaults alone. Add tests/Filament/LocalesTest.php asserting every locale has every file and key of lang/en, and a ListOrders test that renders the page under one of the new locales and finds a translated heading and status label. Run composer test:pest, composer test:phpstan and vendor/bin/pint --test, paste the summaries, and open a pull request that links the issue. Do not change any form field name, table column name or database value.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that links the issue. The diff adds the lang/en, lang/es and lang/de trees and tests/Filament/LocalesTest.php, changes the resource, schema, table, page and widget classes under app/Filament, the enums under app/Enums and AdminPanelProvider, and extends ListOrdersTest. No migration, model or config file changes, and no form field or column name moves, because only the label calls around them did; a reviewer sees that from the diff, where every changed line swaps a quoted string for a __() call.

The description lists the lang files with the number of keys each holds, names the locales added, and pastes the Pest, PHPStan and Pint summaries from the sandbox. The run's full record at GET /o/{org}/sessions/{id}/messages keeps every test run, and GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff per file, which for this change is long but uniform.

Before merging, a reviewer samples a few translations in each locale, checks that keys are named by place rather than by English text so a reworded label does not orphan its key, confirms the navigation groups still order as before, and confirms PHPStan is still clean under Larastan's rules. Nothing is deployed, and the panel still shows English until APP_LOCALE changes.

Run it on every Linear issue labelled agent

Sign in to Linear once with POST /me/connections {"type": "app", "name": "linear"} and finish the authorize URL in the console. Then add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, naming the label in config.labels. The trigger adds the issue after the prompt and fills in no placeholder, so the agent reads the locales to add from the issue text. Each labelled issue starts its own run in its own sandbox and ends in its own pull request, up to the automation's max_runs_per_hour.

A later issue asking for one more language fits the same automation: the agent copies lang/en, translates it, and the parity test keeps it complete. From your own server instead, a handler that receives Linear's webhook sends POST /o/{org}/sessions with the repository and https://linear.app/<workspace>/issue/<ID> in resources, which puts the issue text in the prompt through your Linear connection, and a request_id that is a UUID v5 of the issue id so a redelivered webhook returns the run already started.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Internationalising a panel is wide rather than deep: hundreds of one-line edits across every resource, each one easy and the whole set tedious, with a mistake showing up only as an untranslated label somewhere a reviewer did not click. The agent makes the edits in its own sandbox, runs the whole Pest suite and PHPStan after them, and adds the parity test that keeps the locales honest from then on.

The pull request is reviewable because it is uniform: a string becomes a key, the key appears in three lang files, and the tests show the panel still renders. The trajectory keeps every test run, so the reviewer reads the record rather than re-running the suite.

Frequently asked questions

Do Filament's own buttons and messages need translating?

No. Filament ships translations for its own interface in many locales and picks them by the application locale, so the pagination, the "Create" and "Save changes" buttons and the notification chrome switch on their own. The pull request covers only the strings the application wrote itself.

How does a user switch language?

In this change the locale comes from APP_LOCALE, as config/app.php already reads it. A per-user switch needs a locale column on users, a middleware that calls app()->setLocale() from it and a menu item or profile field, which is a separate issue. Name it in the prompt and the agent adds the column, the middleware and a test together with the lang files.

Will enum values in the database change?

No. OrderStatus keeps its backing values new, processing, shipped, delivered and cancelled; only getLabel() changes to return a translated string. Filters, badges and the ToggleButtons on the order form keep working because they read the label through the HasLabel contract.

Who translates the strings?

The agent writes the Spanish and German values itself and says so in the pull request, so a native speaker on the team can review them in the diff like any other change. The parity test checks keys, not wording, so a reviewer can correct a translation without touching the test.

More Filament jobs

The same job on other stacks

Keep reading