Translate your whole site into a new language, with Laravel

laravel new site-translate --pest --database=sqlite --no-node --no-boost --no-interaction
cd site-translate

composer config repositories.fetchski composer https://acme.example/api/v1/sdk/composer
composer config bearer.acme.example fsk_acme_…
composer require fetchski/attract-cms-laravel

composer require laravel/ai

php artisan attract:install

# OpenRouter: your key, and the model the agent runs on
OPENROUTER_API_KEY=sk-or-v1-…
SITE_TRANSLATE_MODEL=~anthropic/claude-sonnet-latest

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | The model
    |--------------------------------------------------------------------------
    |
    | Any OpenRouter model id works; a `~provider/family-latest` alias always
    | serves that family's newest model.
    |
    */

    'model' => env('SITE_TRANSLATE_MODEL', '~anthropic/claude-sonnet-latest'),

    /*
    |--------------------------------------------------------------------------
    | Limits
    |--------------------------------------------------------------------------
    |
    | A document gets one model call, plus one per round of fixes, up to
    | `attempts`. The run starts no new document once it has spent
    | `max_cost_per_run_usd`.
    |
    */

    'attempts' => 3,

    /*
    |--------------------------------------------------------------------------
    | Time limit
    |--------------------------------------------------------------------------
    |
    | How long one model call may take, in seconds: room for your longest page
    | on a slow model, so it only ends a call that hangs. A call that fails
    | (a timeout, an outage, a rate limit) uses up one of the attempts.
    |
    */

    'timeout_seconds' => 600,

    'max_cost_per_run_usd' => 10,

    /*
    |--------------------------------------------------------------------------
    | Glossary
    |--------------------------------------------------------------------------
    |
    | Names never translated: your business name, your services' and products'
    | names, place names you keep as they are.
    |
    */

    'glossary' => [
        'Acme',
        'Acme Outfitters',
        'Trailhead Tune-Up',
    ],

];

php artisan make:agent Translator --structured

<?php

namespace App\Ai\Agents;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;
use Stringable;

/**
 * Translates one document's words, given as JSON: the language, the glossary
 * and the texts under their keys. It answers every key, translated, in one
 * step. When the code found problems in its last answer, the prompt carries
 * them, and it answers again with every key.
 */
#[Provider(Lab::OpenRouter)]
#[MaxTokens(16000)]
class Translator implements Agent, HasStructuredOutput
{
    use Promptable;

    public function model(): string
    {
        return config('site-translate.model');
    }

    /**
     * Get the instructions that the agent should follow.
     */
    public function instructions(): Stringable|string
    {
        return <<<'TEXT'
            You translate a small business's website, one document at a time, for its own visitors.

            - You get the language, a glossary and the document's texts, each under a key. Answer
              every key, each with its text translated into the language.
            - Write as a native speaker would for this business: natural, warm, plain. Keep the
              meaning, the facts and the tone. Never add or drop information.
            - Keep every glossary name exactly as written, in any text.
            - Keep every word in braces, such as {year} or {business}, exactly as written: the
              site fills it in.
            - Rich text is HTML: translate the words between the tags, and keep every tag, attribute
              and link exactly as it is.
            - Leave a text as it is when it isn't words for a visitor (a code, a hashtag, a product
              name) or is already in the language.
            - When the prompt has `problems` with `yourLastAnswer`, fix each problem and answer with
              every key again.
            TEXT;
    }

    /**
     * Get the agent's structured output schema definition.
     */
    public function schema(JsonSchema $schema): array
    {
        $text = $schema->object(fn (JsonSchema $schema): array => [
            'key' => $schema->string()
                ->required(),
            'text' => $schema->string()
                ->required(),
        ]);

        return [
            'texts' => $schema->array()
                ->items($text)
                ->required(),
        ];
    }
}

<?php

namespace App\Services;

use Fetchski\AttractCmsLaravel\Exceptions\NotFound;
use Fetchski\AttractCmsLaravel\Facades\Attract;

/**
 * Any document on the site, by its type: read in a language, copied into one,
 * its wording written back. Pages, posts and FAQs relate to documents of any
 * type (images, authors, categories, forms), so this reaches each through the
 * site's REST routes with `request()`, the SDK's call for a route by name.
 *
 * A document is the array the site sends; a reference to one is
 * `['aposDocId' => …, 'type' => …, 'slug' => …, 'title' => …]`.
 */
class SiteDocuments
{
    /** Copied into the language so pages keep them, never translated. */
    private const MEDIA = ['@apostrophecms/image', '@apostrophecms/file', 'video'];

    /**
     * A page lives under the page routes; every other type under its own name.
     *
     * @param  array<string, mixed>  $doc
     */
    public static function isPage(array $doc): bool
    {
        return str_starts_with((string) ($doc['slug'] ?? ''), '/');
    }

    /** The path of a document's `_url` (`/about-us`), without the site's address. */
    public static function pathOf(mixed $url): ?string
    {
        $path = is_string($url) ? parse_url($url, PHP_URL_PATH) : null;

        return is_string($path) ? $path : null;
    }

    /** @param  array<string, mixed>  $doc */
    public static function isMedia(array $doc): bool
    {
        return in_array($doc['type'] ?? '', self::MEDIA, true);
    }

    /**
     * A copy is up to date when it was copied from the current original and written since: its
     * translation is saved. ISO dates compare as strings.
     *
     * @param  array<string, mixed>|null  $original
     * @param  array<string, mixed>|null  $copy
     */
    public static function isUpToDate(?array $original, ?array $copy): bool
    {
        $copiedAt = $copy['localizedAt'] ?? null;

        return $original !== null
            && $copy !== null
            && is_string($copiedAt)
            && $copiedAt >= (string) $original['updatedAt']
            && (string) $copy['updatedAt'] > $copiedAt;
    }

    /**
     * Every draft of a type in `$locale`, as stored (so with core's
     * `localizedAt`, which the SDK's own models leave out), a page at a time.
     *
     * @param  array<string, string|int>  $query
     * @return list<array<string, mixed>>
     */
    public function list(string $type, string $locale, array $query = []): array
    {
        $all = [];
        $pages = 1;

        for ($page = 1; $page <= $pages; $page++) {
            $answer = Attract::site()->request('GET', "/{$type}", query: [
                ...$query,
                'aposLocale' => $locale,
                'aposMode' => 'draft',
                'perPage' => 100,
                'page' => $page,
            ]);

            array_push($all, ...($answer['results'] ?? []));
            $pages = $answer['pages'] ?? 1;
        }

        return $all;
    }

    /**
     * The draft in `$locale`, with its related documents; null when the language has no copy yet.
     *
     * @param  array<string, mixed>  $doc
     * @return array<string, mixed>|null
     */
    public function get(array $doc, string $locale): ?array
    {
        try {
            return Attract::site()->request('GET', $this->route($doc), query: [
                'aposLocale' => $locale,
                'aposMode' => 'draft',
            ]);
        } catch (NotFound) {
            return null;
        }
    }

    /**
     * Copies the draft in `$from` into `$to`, as a draft there; `$update` overwrites a copy
     * already there.
     *
     * @param  array<string, mixed>  $doc
     */
    public function copy(array $doc, string $from, string $to, bool $update): void
    {
        Attract::site()->request('POST', "{$this->route($doc)}:{$from}:draft/localize", body: [
            'toLocale' => $to,
            'update' => $update,
        ]);
    }

    /**
     * Writes the translated wording to the draft in `$locale`, with `$links`
     * (the site settings' links pointed at the language's pages). Core's PATCH
     * takes `@<widget id>.<field>` keys, so only the words change.
     *
     * @param  array<string, mixed>  $doc
     * @param  list<array{key: string, text: string}>  $wording
     * @param  list<array{key: string, text: string}>  $links
     */
    public function write(array $doc, string $locale, array $wording, array $links = []): void
    {
        Attract::site()->request(
            'PATCH',
            $this->route($doc),
            query: ['aposLocale' => $locale, 'aposMode' => 'draft'],
            body: array_column([...$wording, ...$links], 'text', 'key'),
        );
    }

    /**
     * Puts the draft in `$locale` in the CMS's review queue (Submitted Drafts).
     *
     * @param  array<string, mixed>  $doc
     */
    public function submit(array $doc, string $locale): void
    {
        Attract::site()->request('POST', "{$this->route($doc)}:{$locale}:draft/submit");
    }

    /**
     * The documents `$doc` shows (images, authors, categories, forms…), once
     * each. Pages are left out: every page is in the run already.
     *
     * @param  array<string, mixed>  $doc
     * @return list<array<string, mixed>>
     */
    public static function related(array $doc): array
    {
        $found = [];

        $visit = function (mixed $value, bool $root) use (&$visit, &$found): void {
            if (! is_array($value)) {
                return;
            }

            // A related document comes projected: its `_id` (`<aposDocId>:<locale>:<mode>`),
            // not its aposDocId. One with no locale in its `_id` (a media folder) is the
            // same in every language: nothing to copy.
            if (! $root && ($value['metaType'] ?? null) === 'doc' && is_string($value['_id'] ?? null)) {
                $parts = explode(':', $value['_id']);
                $aposDocId = $parts[0];

                if (isset($parts[1]) && ! self::isPage($value)) {
                    $found[$aposDocId] = [
                        'aposDocId' => $aposDocId,
                        'type' => $value['type'] ?? '',
                        'slug' => $value['slug'] ?? null,
                        'title' => $value['title'] ?? null,
                    ];
                }

                return;
            }

            foreach ($value as $key => $child) {
                // A page's tree and its published twin are pages, not what it shows.
                if (! in_array($key, ['_ancestors', '_children', '_parent', '_publishedDoc'], true)) {
                    $visit($child, false);
                }
            }
        };

        $visit($doc, true);

        return array_values($found);
    }

    /** @param  array<string, mixed>  $doc */
    private function route(array $doc): string
    {
        $type = self::isPage($doc) ? '@apostrophecms/page' : $doc['type'];

        return "/{$type}/{$doc['aposDocId']}";
    }
}

<?php

namespace App\Support;

/**
 * The words a visitor reads in a document, under the keys core's PATCH writes
 * them back by, and the checks a translation of them must pass.
 */
final class Wording
{
    /** Keys that hold codes, addresses or settings, never words a visitor reads. */
    private const NOT_WORDING_KEYS = [
        'type', 'metaType', 'slug', 'path', 'aposDocId', 'aposLocale', 'aposMode',
        'visibility', 'titleSortified', 'highSearchText', 'lowSearchText', 'searchSummary',
        'parkedId', 'source', 'scopedArrayName',
        'submitted', // who sent it for review, and when
    ];

    private const NOT_WORDING_SUFFIX = '/(By|Url|Href|Color|ColorLight|Custom|Icon|IconFamily|Css|Slug|Email|Phone|Anchor|Code)$/';

    private const NOT_WORDS = [
        '#^(https?:|mailto:|tel:|/|\#|--)#', // addresses, colors, design tokens
        '/^[a-z0-9]+([-_.][a-z0-9]+)*$/', // choices, icon names, slugs
        '/^\S*[a-z][A-Z]\S*$/', // one camelCase token: a choice (belowHeadline)
        '#^[^\s<>]*[@/_{}=][^\s<>]*$#', // one token holding code characters (@apostrophecms/any-page-type)
        '/^\d{4}-\d\d-\d\d/', // dates
        '/^[^\p{L}]*$/u', // no letters at all
    ];

    /**
     * Titles, headings, text, rich text, button labels, SEO text. Codes,
     * colors, addresses and settings stay out, and so do related documents
     * (they are translated as documents of their own). `$fields` limits it to
     * those fields (the site settings' own words: the rest of their fields
     * are shared by every language).
     *
     * @param  array<string, mixed>  $doc
     * @param  list<string>|null  $fields
     * @return list<array{key: string, text: string}>
     */
    public static function of(array $doc, ?array $fields = null): array
    {
        $found = [];

        $visit = function (mixed $value, ?string $owner, string $path) use (&$visit, &$found): void {
            if (is_string($value)) {
                $text = trim($value);

                if ($text !== '' && ! self::isNotWords($text)) {
                    $found[] = ['key' => $owner ? "@{$owner}.{$path}" : $path, 'text' => $value];
                }

                return;
            }

            if (! is_array($value) || ($value['metaType'] ?? null) === 'doc') {
                return;
            }

            if (array_is_list($value)) {
                foreach ($value as $index => $item) {
                    // A widget or array row has an id: its fields are keyed by it.
                    if (is_array($item) && is_string($item['_id'] ?? null)) {
                        $visit($item, $item['_id'], '');
                    } else {
                        $visit($item, $owner, $path === '' ? (string) $index : "{$path}.{$index}");
                    }
                }

                return;
            }

            foreach ($value as $key => $child) {
                if (self::isWordingKey((string) $key)) {
                    $visit(self::unwrap($child), $owner, $path === '' ? (string) $key : "{$path}.{$key}");
                }
            }
        };

        foreach ($doc as $key => $value) {
            if (self::isWordingKey((string) $key) && ($fields === null || in_array($key, $fields, true))) {
                $visit(self::unwrap($value), null, (string) $key);
            }
        }

        return $found;
    }

    /**
     * The links in `$fields` of the site settings (a `url` in a list row,
     * `headerCtaUrl`…) that point at a page the language has, each written to
     * point at that page in the language instead, under the key core's PATCH
     * writes it back by. `$pointTo` maps a page's path to its path in the
     * language. A link's `?query` and `#anchor` are kept; a link to another
     * site is left alone.
     *
     * @param  array<string, mixed>  $doc
     * @param  list<string>  $fields
     * @param  array<string, string>  $pointTo
     * @return list<array{key: string, text: string}>
     */
    public static function linksTo(array $doc, array $fields, array $pointTo): array
    {
        $found = [];

        $visit = function (mixed $value, ?string $owner, string $key) use (&$visit, &$found, $pointTo): void {
            if (is_array($value) && array_is_list($value)) {
                foreach ($value as $row) {
                    foreach (is_array($row) ? $row : [] as $field => $child) {
                        $visit($child, is_string($row['_id'] ?? null) ? $row['_id'] : $owner, (string) $field);
                    }
                }

                return;
            }

            // A link on this site starts with one slash; another site's is left alone.
            if (! is_string($value) || preg_match('/(^url|Url)$/', $key) !== 1 || preg_match('#^/(?!/)#', $value) !== 1) {
                return;
            }

            $cut = strcspn($value, '?#');
            $to = $pointTo[substr($value, 0, $cut)] ?? null;
            $link = $to.substr($value, $cut);

            if ($to !== null && $link !== $value) {
                $found[] = ['key' => $owner ? "@{$owner}.{$key}" : $key, 'text' => $link];
            }
        };

        foreach ($fields as $field) {
            $visit($doc[$field] ?? null, null, $field);
        }

        return $found;
    }

    /**
     * Why a translation can't be saved: a key missing or invented, an HTML tag,
     * a link or a {placeholder} changed, a glossary name translated, a sentence
     * left untranslated. Empty when it can be.
     *
     * @param  list<array{key: string, text: string}>  $original
     * @param  list<array{key?: mixed, text?: mixed}>  $translated
     * @param  list<string>  $glossary
     * @return list<string>
     */
    public static function problems(array $original, array $translated, array $glossary): array
    {
        $problems = [];
        $given = [];

        foreach ($translated as $item) {
            $given[(string) ($item['key'] ?? '')] = (string) ($item['text'] ?? '');
        }

        foreach ($original as ['key' => $key, 'text' => $text]) {
            $translation = $given[$key] ?? '';

            if (trim($translation) === '') {
                $problems[] = "{$key}: missing. Translate every key you were given.";

                continue;
            }

            if (self::tags($translation) !== self::tags($text)) {
                $tags = self::tags($text) ?: 'none';
                $problems[] = "{$key}: the HTML tags changed. Keep exactly these, in order: {$tags}.";
            }

            if (self::links($translation) !== self::links($text)) {
                $problems[] = "{$key}: a link changed. Keep every href and src exactly as it was.";
            }

            if (self::placeholders($translation) !== self::placeholders($text)) {
                $kept = self::placeholders($text) ?: 'none';
                $problems[] = "{$key}: keep these exactly as written, the site fills them in: {$kept}.";
            }

            foreach ($glossary as $name) {
                if (str_contains($text, $name) && ! str_contains($translation, $name)) {
                    $problems[] = "{$key}: \"{$name}\" is in the glossary. Keep it exactly as written.";
                }
            }

            if (self::leftAsIs($text, $translation, $glossary)) {
                $problems[] = "{$key}: still in the original language. Translate it.";
            }
        }

        $known = array_column($original, 'key');

        foreach (array_keys($given) as $key) {
            if (! in_array($key, $known, true)) {
                $problems[] = "{$key}: not one of the keys you were given. Leave it out.";
            }
        }

        return $problems;
    }

    /**
     * A sentence sent back as it was: not translated. A sentence: four words or more, glossary
     * names aside, two of them lowercase (a name or an address alone never counts).
     *
     * @param  list<string>  $glossary
     */
    private static function leftAsIs(string $text, string $translation, array $glossary): bool
    {
        $plain = fn (string $value): string => trim(
            (string) preg_replace('/\s+/u', ' ', strip_tags($value)),
        );

        if ($plain($text) !== $plain($translation)) {
            return false;
        }

        preg_match_all('/\p{L}+/u', str_replace($glossary, ' ', $plain($text)), $words);

        $lowercase = array_filter(
            $words[0],
            fn (string $word) => preg_match('/^\p{Ll}/u', $word) === 1,
        );

        return count($words[0]) >= 4 && count($lowercase) >= 2;
    }

    private static function isWordingKey(string $key): bool
    {
        return ! str_starts_with($key, '_')
            && ! in_array($key, self::NOT_WORDING_KEYS, true)
            && preg_match(self::NOT_WORDING_SUFFIX, $key) !== 1;
    }

    private static function isNotWords(string $text): bool
    {
        foreach (self::NOT_WORDS as $pattern) {
            if (preg_match($pattern, $text) === 1) {
                return true;
            }
        }

        return false;
    }

    /** An area holds its widgets under `items`. */
    private static function unwrap(mixed $value): mixed
    {
        return is_array($value) && ($value['metaType'] ?? null) === 'area'
            ? ($value['items'] ?? [])
            : $value;
    }

    private static function tags(string $text): string
    {
        preg_match_all('/<\/?([a-z][a-z0-9]*)\b[^>]*>/i', $text, $matches, PREG_SET_ORDER);

        return implode(' ', array_map(
            fn (array $match): string => str_starts_with($match[0], '</') ? "/{$match[1]}" : $match[1],
            $matches,
        ));
    }

    /** The {year}-style words the site fills in, in any order (a language may move them). */
    private static function placeholders(string $text): string
    {
        preg_match_all('/\{[a-z]+\}/', $text, $matches);
        sort($matches[0]);

        return implode(' ', $matches[0]);
    }

    private static function links(string $text): string
    {
        preg_match_all('/\b(?:href|src)\s*=\s*"([^"]*)"/i', $text, $matches);

        return implode(' ', $matches[1]);
    }
}

<?php

namespace App\Support;

/** One document's outcome, for the report. */
final readonly class TranslatedDocument
{
    /**
     * @param  string  $kind  page, blog post, FAQ, site settings, or shown on them
     * @param  string|null  $previewUrl  The draft on the site, for anyone with the link, without
     *                                   signing in. Pages and posts only.
     * @param  string|null  $problem  Why it was skipped or failed; null once saved.
     */
    public function __construct(
        public string $title,
        public string $kind,
        public ?string $previewUrl,
        public ?string $problem,
    ) {}

    /** Left untranslated: counts against the run, and fails the command. */
    public function failed(): bool
    {
        return $this->problem !== null && $this->problem !== 'Nothing to translate.';
    }
}

<?php

namespace App\Support;

/** What one run did, and what it spent. */
final class TranslationReport
{
    /** @var list<TranslatedDocument> */
    public array $documents = [];

    public int $upToDate = 0;

    public int $inputTokens = 0;

    public int $outputTokens = 0;

    public float $costUsd = 0.0;

    public function __construct(
        public readonly bool $added,
        public readonly bool $published,
    ) {}

    /** How many documents were left untranslated. */
    public function failed(): int
    {
        return count(array_filter($this->documents, fn (TranslatedDocument $doc): bool => $doc->failed()));
    }
}

<?php

namespace App\Services;

use App\Ai\Agents\Translator;
use App\Support\TranslatedDocument;
use App\Support\TranslationReport;
use App\Support\Wording;
use Fetchski\AttractCmsLaravel\Data\SiteLanguagesLanguagesItem;
use Fetchski\AttractCmsLaravel\Facades\Attract;
use Laravel\Ai\Exceptions\FailoverableException;
use Laravel\Ai\Responses\AgentResponse;
use RuntimeException;

/**
 * Translates the site's pages, blog posts and FAQs (and what they show), and
 * its header, footer and cookie banner, into a language, adding the language
 * first if the site lacks it. Every translation is a draft; `$publish` makes
 * the language public, nothing else.
 */
class SiteTranslator
{
    /** What the run lists, by kind: the type, its list's query, and how to share one. */
    private const KINDS = [
        'page' => ['type' => '@apostrophecms/page', 'query' => ['all' => 1, 'flat' => 1], 'share' => 'pages'],
        'blog post' => ['type' => '@apostrophecms/blog', 'query' => [], 'share' => 'blogPosts'],
        'FAQ' => ['type' => 'faq-item', 'query' => [], 'share' => null],
    ];

    /** Site settings and Site design: one document per language. */
    private const SETTINGS = '@apostrophecms/global';

    public function __construct(private SiteDocuments $docs) {}

    public function translate(string $code, string $name, bool $publish = false): TranslationReport
    {
        $report = new TranslationReport(
            added: $this->ensureLanguage($code, $name, $publish),
            published: $publish,
        );
        $main = $this->mainLocale($code);

        // 1. What needs translating: never copied, or changed since its copy.
        [$all, $paths] = $this->listAll($main, $code);
        $jobs = [];

        foreach ($all as [$job, $upToDate]) {
            if ($upToDate) {
                $report->upToDate++;
            } else {
                $jobs[] = $job;
            }
        }

        // 2. Copy what any of them shows that needs its words (by the same rule, so a copy a
        //    stopped run left is translated by the next), then each one: a write keeps a related
        //    document only once it exists in the language. A key missing a scope stops here,
        //    before any copy is overwritten.
        $shown = [];
        $seen = [];

        $copyShown = function (array $doc) use (&$copyShown, &$shown, &$seen, $main, $code): void {
            foreach (SiteDocuments::related($this->docs->get($doc, $main) ?? []) as $related) {
                if (isset($seen[$related['aposDocId']])) {
                    continue;
                }

                $seen[$related['aposDocId']] = true;
                $copy = $this->docs->get($related, $code);

                // A copy is all an image or a file needs; anything else needs its words, unless up to date.
                if ($copy !== null && (SiteDocuments::isMedia($related)
                    || SiteDocuments::isUpToDate($this->docs->get($related, $main), $copy))) {
                    continue;
                }

                $this->docs->copy($related, $main, $code, update: $copy !== null);

                if (! SiteDocuments::isMedia($related)) {
                    $shown[] = [...$related, 'kind' => 'shown on them', 'share' => null];
                }

                $copyShown($related);
            }
        };

        foreach ($all as [$job]) {
            $copyShown($job);
        }

        foreach ($jobs as $index => $job) {
            $this->docs->copy($job, $main, $code, update: true);

            // The settings' links to pages point at the language's pages.
            if ($job['kind'] === 'site settings') {
                $jobs[$index]['links'] = Wording::linksTo($job['original'], $job['fields'], $this->pathsIn($code, $paths));
            }
        }

        // 3. Translate each copy and send it for review, within the run's budget.
        $budget = config('site-translate.max_cost_per_run_usd');

        foreach ([...$jobs, ...$shown] as $job) {
            $report->documents[] = $report->costUsd >= $budget
                ? $this->outcome($job, null, "Not translated: the run reached \${$budget}. Run it again to go on.")
                : $this->translateOne($job, $code, $name, $report);
        }

        return $report;
    }

    /** Adds the language, not public, when the site lacks it; `$publish` makes it public. */
    private function ensureLanguage(string $code, string $name, bool $publish): bool
    {
        $list = Attract::languages()->listSiteLanguages()->results->first()
            ?? throw new RuntimeException('The site has no language list: open Languages in the CMS once, then run this again.');

        $languages = $list->languages ?? collect();
        $known = $languages->firstWhere('code', $code);

        if ($known && (! $publish || $known->public)) {
            return false;
        }

        Attract::languages()->updateSiteLanguages(
            id: $list->id,
            languages: $known
                ? $languages->map(fn (SiteLanguagesLanguagesItem $language) => $language->code === $code
                    ? new SiteLanguagesLanguagesItem(name: $language->name, code: $code, id: $language->id, public: true)
                    : $language)
                : $languages->concat([new SiteLanguagesLanguagesItem(name: $name, code: $code, public: $publish)]),
        );

        return ! $known;
    }

    /** The site's main language: the one without an address prefix. Checks `$code` is one of its languages now. */
    private function mainLocale(string $code): string
    {
        $locales = Attract::internationalization()->getLocales();
        $main = collect($locales)->search(fn ($locale) => ! $locale->prefix);

        if (! is_string($main) || ! isset($locales[$code]) || $code === $main) {
            $codes = implode(', ', array_keys($locales));

            throw new RuntimeException("\"{$code}\" isn't one of the site's further languages: the site has {$codes}.");
        }

        return $main;
    }

    /**
     * Every page (parents first: a page is copied only under its parent), blog
     * post and FAQ, and the site settings, each with whether its translation is
     * up to date: copied from the current original, and written since the
     * copy. With each page's and post's path, by id.
     *
     * @return array{0: list<array{0: array<string, mixed>, 1: bool}>, 1: array<string, string>}
     */
    private function listAll(string $main, string $code): array
    {
        $out = [];
        $paths = [];

        foreach (self::KINDS as $kind => ['type' => $type, 'query' => $query, 'share' => $share]) {
            $copies = collect($this->docs->list($type, $code, $query))->keyBy('aposDocId');
            $originals = collect($this->docs->list($type, $main, $query))
                ->sortBy([['level', 'asc'], ['rank', 'asc']]);

            foreach ($originals as $original) {
                $path = SiteDocuments::pathOf($original['_url'] ?? null);

                if ($path !== null && $kind !== 'FAQ') {
                    $paths[$original['aposDocId']] = $path;
                }

                $copy = $copies->get($original['aposDocId']);

                // The page tree's list sends a child page's main fields only: read it whole.
                if ($copy && ! array_key_exists('localizedAt', $copy)) {
                    $copy = $this->docs->get($copy, $code);
                }

                $out[] = [
                    [
                        'aposDocId' => $original['aposDocId'],
                        'type' => $original['type'],
                        'slug' => $original['slug'] ?? null,
                        'title' => $original['title'] ?? null,
                        'kind' => $kind,
                        'share' => $share,
                    ],
                    SiteDocuments::isUpToDate($original, $copy),
                ];
            }
        }

        // The header, footer and cookie banner: the settings' fields the site says each language
        // translates.
        $settings = $this->docs->list(self::SETTINGS, $main)[0] ?? null;

        if ($settings !== null) {
            $upToDate = SiteDocuments::isUpToDate($settings, $this->docs->get($settings, $code));

            $out[] = [
                [
                    'aposDocId' => $settings['aposDocId'],
                    'type' => $settings['type'],
                    'slug' => $settings['slug'] ?? null,
                    'title' => 'Header, footer and cookie banner',
                    'kind' => 'site settings',
                    'share' => null,
                    'original' => $settings,
                    'fields' => $upToDate
                        ? []
                        : Attract::languages()->getGlobalTranslatedFields()->translated->all(),
                ],
                $upToDate,
            ];
        }

        return [$out, $paths];
    }

    /**
     * Each page's and post's path → its path in the language (`/about-us` → `/fr/about-us`).
     *
     * @param  array<string, string>  $paths
     * @return array<string, string>
     */
    private function pathsIn(string $code, array $paths): array
    {
        $pointTo = [];

        foreach (['page', 'blog post'] as $kind) {
            ['type' => $type, 'query' => $query] = self::KINDS[$kind];

            foreach ($this->docs->list($type, $code, $query) as $copy) {
                $from = $paths[$copy['aposDocId']] ?? null;
                $to = SiteDocuments::pathOf($copy['_url'] ?? null);

                if ($from !== null && $to !== null) {
                    $pointTo[$from] = $to;
                }
            }
        }

        return $pointTo;
    }

    /**
     * Has the agent translate one copy, saves it, and sends it for review.
     *
     * @param  array<string, mixed>  $job
     */
    private function translateOne(array $job, string $code, string $name, TranslationReport $report): TranslatedDocument
    {
        $copy = $this->docs->get($job, $code);
        $texts = $copy ? Wording::of($copy, $job['fields'] ?? null) : [];

        if (! $copy || $texts === []) {
            return $this->outcome($job, null, $copy ? 'Nothing to translate.' : "No copy in {$code}.");
        }

        $glossary = config('site-translate.glossary');
        $prompt = ['language' => "{$name} ({$code})", 'glossary' => $glossary, 'texts' => $texts];
        $problems = [];
        $failure = null;

        for ($attempt = 1; $attempt <= config('site-translate.attempts'); $attempt++) {
            try {
                $response = Translator::make()->prompt(
                    json_encode($prompt, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),
                    timeout: config('site-translate.timeout_seconds'),
                );
            } catch (FailoverableException $error) {
                // The model didn't answer: a timeout, an outage, a rate limit. Try again.
                $failure = rtrim($error->getMessage(), '.');

                continue;
            }

            $failure = null;
            $this->spend($response, $report);

            $translated = $response['texts'] ?? [];
            $problems = Wording::problems($texts, $translated, $glossary);

            if ($problems === []) {
                $this->docs->write($job, $code, $translated, $job['links'] ?? []);
                $this->docs->submit($job, $code);

                return $this->outcome($job, $this->previewUrl($job, $copy, $code), null);
            }

            $prompt = [...$prompt, 'yourLastAnswer' => $translated, 'problems' => $problems];
        }

        if ($failure !== null) {
            return $this->outcome($job, null, "Not translated: the model didn't answer ({$failure}). Run it again to go on.");
        }

        return $this->outcome($job, null, 'Not saved: '.implode(' ', array_slice($problems, 0, 3)));
    }

    /** Adds one call's tokens, and its cost as OpenRouter reports it in the raw answer. */
    private function spend(AgentResponse $response, TranslationReport $report): void
    {
        $report->inputTokens += $response->usage->inputTokens;
        $report->outputTokens += $response->usage->outputTokens;
        $report->costUsd += (float) ($response->raw?->json('usage.cost') ?? 0);
    }

    /**
     * The saved draft, for anyone with the link, without signing in. Pages and posts only.
     *
     * @param  array<string, mixed>  $job
     * @param  array<string, mixed>  $copy
     */
    private function previewUrl(array $job, array $copy, string $code): ?string
    {
        $id = "{$job['aposDocId']}:{$code}:draft";
        $url = $copy['_url'] ?? null;

        $shared = match ($job['share']) {
            'pages' => Attract::pages()->sharePage(id: $id, share: true),
            'blogPosts' => Attract::blogPosts()->shareBlog(id: $id, share: true),
            default => null,
        };

        if (! is_string($url) || ! $shared?->aposShareKey) {
            return null;
        }

        return $url.'?'.http_build_query(['aposShareKey' => $shared->aposShareKey, 'aposShareId' => $id]);
    }

    /** @param  array<string, mixed>  $job */
    private function outcome(array $job, ?string $previewUrl, ?string $problem): TranslatedDocument
    {
        return new TranslatedDocument(
            title: $job['title'] ?? $job['slug'] ?? $job['aposDocId'],
            kind: $job['kind'],
            previewUrl: $previewUrl,
            problem: $problem,
        );
    }
}

php artisan make:command SiteTranslate

<?php

namespace App\Console\Commands;

use App\Services\SiteTranslator;
use App\Support\TranslatedDocument;
use Fetchski\AttractCmsLaravel\Exceptions\AttractException;
use Illuminate\Console\Attributes\Description;
use Illuminate\Console\Attributes\Signature;
use Illuminate\Console\Command;
use RuntimeException;

#[Signature('site:translate
    {code : The language code, such as fr or pt-br}
    {name : The language as its speakers write it, such as "Français"}
    {--publish : Also make the language public, once its drafts are published}')]
#[Description('Translate the site’s pages, blog posts and FAQs into a language, as drafts for review')]
class SiteTranslate extends Command
{
    /**
     * Execute the console command.
     */
    public function handle(SiteTranslator $translator): int
    {
        $code = $this->argument('code');
        $name = $this->argument('name');

        if (preg_match('/^[a-z]{2,3}(-[a-z]{4})?(-([a-z]{2}|[0-9]{3}))?$/', $code) !== 1) {
            $this->components->error("\"{$code}\" isn't a language code: use lowercase, such as fr or pt-br");

            return self::FAILURE;
        }

        try {
            $report = $translator->translate($code, $name, $this->option('publish'));
        } catch (AttractException|RuntimeException $error) {
            // A missing scope or a refused language: the site's message names it. Nothing was overwritten.
            $this->components->error($error->getMessage());

            return self::FAILURE;
        }

        if ($report->added) {
            $this->components->info($report->published
                ? "Added {$name} ({$code}) to the site, public."
                : "Added {$name} ({$code}) to the site, not public yet.");
        }

        if ($report->documents !== []) {
            $this->table(['', 'Document', 'Preview'], array_map(fn (TranslatedDocument $doc): array => [
                $doc->kind,
                $doc->title,
                $doc->problem ?? $doc->previewUrl ?? 'Submitted Drafts in the CMS',
            ], $report->documents));
        }

        $failed = $report->failed();
        $translated = count($report->documents) - $failed;
        $cost = number_format($report->costUsd, 4);

        $this->components->info("{$translated} translated, {$failed} not, {$report->upToDate} already up to date.");
        $this->components->info("Tokens: {$report->inputTokens} in, {$report->outputTokens} out. Cost: \${$cost}.");

        if ($report->published) {
            $this->components->success("{$name} is public: visitors see each page you have published in it.");
        }

        return $failed > 0 ? self::FAILURE : self::SUCCESS;
    }
}

vendor/bin/pint

php artisan site:translate fr "Français"

   INFO  Added Français (fr) to the site, not public yet.

+---------------+----------------------------------+-----------------------------------------------------------------------------------------+
|               | Document                         | Preview                                                                                 |
+---------------+----------------------------------+-----------------------------------------------------------------------------------------+
| page          | Home                             | https://acme.example/fr/?aposShareKey=…&aposShareId=…                                   |
| page          | About us                         | https://acme.example/fr/about-us?aposShareKey=…&aposShareId=…                           |
| page          | Services                         | https://acme.example/fr/services?aposShareKey=…&aposShareId=…                           |
| page          | Contact us                       | https://acme.example/fr/contact-us?aposShareKey=…&aposShareId=…                         |
| blog post     | Now open on Saturday mornings    | https://acme.example/fr/blog/now-open-on-saturday-mornings?aposShareKey=…&aposShareId=… |
| FAQ           | When are you open?               | Submitted Drafts in the CMS                                                             |
| FAQ           | Do I need to book?               | Submitted Drafts in the CMS                                                             |
| site settings | Header, footer and cookie banner | Submitted Drafts in the CMS                                                             |
| shown on them | Contact form                     | Submitted Drafts in the CMS                                                             |
| shown on them | Jordan Lee                       | Submitted Drafts in the CMS                                                             |
| shown on them | News                             | Submitted Drafts in the CMS                                                             |
+---------------+----------------------------------+-----------------------------------------------------------------------------------------+

   INFO  11 translated, 0 not, 0 already up to date.

   INFO  Tokens: 45380 in, 10860 out. Cost: $0.3150.

php artisan site:translate fr "Français" --publish

   INFO  0 translated, 0 not, 11 already up to date.

   INFO  Tokens: 0 in, 0 out. Cost: $0.0000.

   SUCCESS  Français is public: visitors see each page you have published in it.

rm tests/Unit/ExampleTest.php tests/Feature/ExampleTest.php

<?php

namespace Tests;

use Fetchski\AttractCmsLaravel\Data\Blog;
use Fetchski\AttractCmsLaravel\Data\Page;
use Fetchski\AttractCmsLaravel\Data\SiteLanguages;
use Fetchski\AttractCmsLaravel\Facades\Attract;

/**
 * A fake site whose stored drafts live in memory, under `<aposDocId>:<locale>`
 * (`$stored` starts as the main language's): `request()` answers the routes
 * the translator calls (list, get, localize, PATCH, submit) from them, and the
 * SDK's methods answer as `Attract::fake()` does, from `$answers`, over a site
 * with English and a private French. `$log` lists each copy and write, in
 * order. Ids are 10 characters or more, as the site's are, which tells them
 * from a type's name.
 */
class FakeSite
{
    /** @var array<string, array<string, mixed>> */
    public array $docs = [];

    /** @var list<string> Each copy and write, in order: "copy <id> to fr", "write <id> in fr". */
    public array $log = [];

    /**
     * @param  list<array<string, mixed>>  $stored
     * @param  array<string, mixed>  $answers
     */
    public function __construct(array $stored, array $answers = [])
    {
        foreach ($stored as $doc) {
            $this->docs["{$doc['aposDocId']}:en"] = $doc;
        }

        Attract::fake([
            'languages.listSiteLanguages' => [
                'results' => [SiteLanguages::factory()->make(['id' => 'langs', 'languages' => []])],
                'pages' => 1,
                'currentPage' => 1,
            ],
            'internationalization.getLocales' => [
                'en' => ['label' => 'English'],
                'fr' => ['label' => 'Français', 'prefix' => '/fr', 'private' => true],
            ],
            'languages.getGlobalTranslatedFields' => ['translated' => ['tagline', 'headerNav', 'footerLinkGroups']],
            'pages.sharePage' => Page::factory()->make(['aposShareKey' => 'share-key']),
            'blogPosts.shareBlog' => Blog::factory()->make(['aposShareKey' => 'share-key']),
            ...$answers,
            'request' => fn (array $args) => $this->route(...$args),
        ]);
    }

    /** @param  array<string, mixed>  $query */
    private function route(string $method, string $path, array $query, mixed $body): mixed
    {
        preg_match('#^/(.+?)(?:/([a-z0-9]{10,})(?::[a-z-]+:draft)?)?(?:/(localize|submit))?$#', $path, $match);
        [, $type, $id, $action] = $match + [null, null, null, null];
        $locale = $query['aposLocale'] ?? '';

        if ($method === 'GET' && ! $id) {
            $results = array_values(array_filter(
                $this->docs,
                fn (array $doc, string $key): bool => str_ends_with($key, ":{$locale}") && $this->typeOf($doc) === $type,
                ARRAY_FILTER_USE_BOTH,
            ));

            return ['results' => $results, 'pages' => 1];
        }

        if ($method === 'GET') {
            return $this->docs["{$id}:{$locale}"] ?? Attract::notFound();
        }

        if ($action === 'localize') {
            $to = $body['toLocale'];

            if (isset($this->docs["{$id}:{$to}"]) && ! $body['update']) {
                return Attract::siteError(409);
            }

            $this->log[] = "copy {$id} to {$to}";
            $at = now()->toISOString();
            $original = $this->docs["{$id}:en"];
            $this->docs["{$id}:{$to}"] = [
                ...$original,
                ...(isset($original['_url']) ? ['_url' => str_replace('.example/', ".example/{$to}/", $original['_url'])] : []),
                '_id' => "{$id}:{$to}:draft",
                'updatedAt' => $at,
                'localizedAt' => $at,
            ];

            return [];
        }

        if ($method === 'PATCH') {
            $this->log[] = "write {$id} in {$locale}";
            $this->docs["{$id}:{$locale}"] = [
                ...$this->docs["{$id}:{$locale}"],
                ...$body,
                'updatedAt' => now()->addSecond()->toISOString(),
            ];

            return $this->docs["{$id}:{$locale}"];
        }

        return [];
    }

    /** @param  array<string, mixed>  $doc */
    private function typeOf(array $doc): string
    {
        return str_starts_with($doc['slug'] ?? '', '/') ? '@apostrophecms/page' : $doc['type'];
    }
}