# 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 Rush](https://cloud.getrush.ai/run/add-i18n/filament/). Opens 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`

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

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

- [Email Customers When an Order Status Changes in a Filament Shop](https://getrush.ai/run/add-order-status-emails/filament/)
- [Add Password Reset to a Filament Admin Panel](https://getrush.ai/run/add-password-reset/filament/)
- [Add PDF Invoices to a Filament Admin Panel from a Linear Issue](https://getrush.ai/run/add-pdf-invoices/filament/)

## The same job on other stacks

- [Add i18n to a Flutter App](https://getrush.ai/run/add-i18n/flutter/)
- [Add i18n to a Gatsby Blog](https://getrush.ai/run/add-i18n/gatsby/)
- [Add i18n to a Hugo Site](https://getrush.ai/run/add-i18n/hugo/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
