Translating a Theme

// $vars is a replacement map with the braces INCLUDED: ['{count}' => 3].
// This is what the template function calls; use it from PHP for the same result.
public function lang(string $key, array $vars = []): string;

// Every form of a count key, all from ONE language. The key's own value is 'other':
// ['one' => '{n} service', 'other' => '{n} services'].
public function lang_forms(string $key): array;

// The form $n reads with, $vars applied. '{n}' is the number unless $vars sets it.
public function lang_plural(string $key, int|float $n, array $vars = []): string;

// Load a view's scope before rendering it. Called for you on the request path and by the
// context-free render; call it yourself only when you render a view by hand.
public function loadViewContent(string $view): void;

// Another theme's locale, without booting it as the active theme (the panel's theme list
// reads a theme's own name and description this way). Falls back to English.
public static function localeFor(string $themeName, string $lang = ''): array;

// '' when the name is not a usable scope. A scope is [a-zA-Z0-9/_-] and may not climb out.
public static function cleanScope(string $scope): string;

// Every editable scope of a theme: 'common' first, then the page scopes, sorted.
public static function contentScopes(string $themeName): array;

// The developer's defaults of one scope in one language (string values only).
public static function scopeDefaults(string $themeName, string $lang, string $scope): array;

// The operator's overrides of the same scope. Empty when nothing was changed.
public static function scopeOverrides(string $themeName, string $lang, string $scope): array;

// Persist them. An EMPTY set deletes the file, which is how "reset to default" is stored:
// an override is an exception, never a copy of the default.
public static function writeScopeOverrides(string $themeName, string $lang, string $scope, array $values): bool;

return [
    // Short keys: the FILE is the scope, so a page prefix would only repeat it.
    'title'        => 'Services',
    'lede'         => 'Everything running on your account, with its next renewal date.',
    'count'        => '{n} services',
    'count-one'    => '{n} service',
    'empty_title'  => 'No services yet',
    'empty_text'   => 'Your first order will show up here.',
    'renew_cta'    => 'Renew',
    'aria_list'    => 'Service list',
];

return [
    // Same keys, translated values. A renamed key here is a missing key in Turkish only.
    'title'        => 'Hizmetler',
    'lede'         => 'Hesabınızda çalışan her şey ve bir sonraki yenileme tarihi.',
    // Turkish reads the same for every number, so 'count' needs no sibling.
    'count'        => '{n} hizmet',
    'empty_title'  => 'Henüz hizmet yok',
    'empty_text'   => 'İlk siparişiniz burada görünecek.',
    'renew_cta'    => 'Yenile',
    'aria_list'    => 'Hizmet listesi',
];

<h1>{lang key='title'}</h1>
<p>{lang key='lede'}</p>

{if $services}
    {* plural= picks the form for this number and fills {n}; any other attribute fills its own placeholder. *}
    <p>{lang key='count' plural=$services|@count}</p>

    <ul aria-label="{lang key='aria_list'}">
        {foreach $services as $service}
        <li>
            {$service.name}
            <a href="{link route='service-detail' p1=$service.id}">{lang key='renew_cta'}</a>
        </li>
        {/foreach}
    </ul>
{else}
    {* Accessible names are strings too: nothing visible OR announced is hardcoded. *}
    <h2>{lang key='empty_title'}</h2>
    <p>{lang key='empty_text'}</p>
{/if}

{* A platform key, in its path form: the same wording every theme shares. *}
<a href="{link route='home'}" aria-label="{lang key='website/index/logo-alt'}">{$company_name}</a>