# Translation Manager

## Package docs status

This page is generated from public package documentation in `capell-4/packages` and the package manifest checked into the source repository.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/translation-manager` |
| Package slug | `translation-manager` |
| Product group | Capell Admin |
| Tier | premium |
| Bundle | `admin` |
| Runtime contexts | `admin` |
| Capell version | `^4.0` |
| Source repository | `capell-app/packages` |
| Source path | `packages/translation-manager` |
| Docs source | `packages/translation-manager/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/4.x/packages/translation-manager/capell.json) |

File-based Laravel translation management for Capell and Filament admin panels.

## At A Glance

- Package: `capell-app/translation-manager`
- Namespace: `Capell\TranslationManager\`
- Surfaces: Filament admin
- Service providers: `packages/translation-manager/src/Providers/AdminServiceProvider.php`, `packages/translation-manager/src/Providers/TranslationManagerServiceProvider.php`
- Capell dependencies: `capell-app/admin`, `capell-app/core`
- Third-party dependencies: `lorisleiva/laravel-actions`, `spatie/laravel-data`, `spatie/laravel-package-tools`

## Why It Helps Your Capell Workflow

- Provides a file-based Filament editor for Laravel language files with safe package override writes.
- Helps owners and admins adjust labels and copy without editing vendor package files directly.
- Gives developers a controlled translation workflow that respects package boundaries and override storage.

## Best Used With

- [Welcome Tour](../welcome-tour/README.md)
- [Diagnostics](../diagnostics/README.md)
- [Foundation Theme](../foundation-theme/README.md)

## What It Adds

- File-based Laravel translation management for Capell and Filament admin panels.
- Locale creation and duplication from the package admin page.
- Optional AI translation only when a host application binds a translator implementation.

## Code Map

| Area      | Path                                         | Purpose                                                             |
| --------- | -------------------------------------------- | ------------------------------------------------------------------- |
| Actions   | `packages/translation-manager/src/Actions`   | Domain operations. Test these directly where possible.              |
| Data      | `packages/translation-manager/src/Data`      | Structured payloads, form state, view models, and integration data. |
| Filament  | `packages/translation-manager/src/Filament`  | Admin resources, pages, widgets, and settings UI.                   |
| Providers | `packages/translation-manager/src/Providers` | Registration, extension hooks, routes, migrations, and resources.   |
| Resources | `packages/translation-manager/resources`     | Views, translations, assets, and package resources.                 |
| Config    | `packages/translation-manager/config`        | Package configuration and publishable config.                       |
| Tests     | `packages/translation-manager/tests`         | Package-level Pest coverage.                                        |

## Admin Surface

- Pages: `TranslationManagerPage` at `/admin/translation-manager`.
- Header actions: Create locale, Duplicate locale, Save translations.
- Optional header action: Translate selected, only when an AI translator binding is available.

## Data And Persistence

- Config: `packages/translation-manager/config/capell-translation-manager.php`.
- Data objects live in `src/Data/`; use them for payloads, form state, and view models.

## Extension Points

- Contracts: `TranslationAITranslator`, `TranslationFileStore`, `TranslationSourceResolver`.
- Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

## Install And Setup

- Install with `composer require capell-app/translation-manager` in the host Capell application.
- In this repository, verify package changes with `vendor/bin/pest`; do not use `php artisan`.
- For screenshots in a local package harness, set `capell-translation-manager.package_paths` to `[]` unless the pass is intentionally documenting package translation sources. This keeps uninstalled sibling package repositories out of the source selector.

## Docs

- [docs index](README.md)
- [overview.md](overview.md)
- [screenshots.json](screenshots.json)
- [sources-stores-and-ai.md](sources-stores-and-ai.md)

## Testing

Run package tests from the repository root:

```bash
vendor/bin/pest packages/translation-manager/tests --configuration=phpunit.xml
```

## Maintenance Notes

- Put behaviour changes in `src/Actions/`; UI classes, commands, and controllers should call actions instead of owning domain logic.
- Use package `Data` classes at boundaries instead of passing anonymous arrays between layers.