Overriding Text and Templates

// Root packages. $key is "{file}/{key}/{subkey}", one slash per array level.
// Returns false when any segment is missing. There is NO language fallback.
public static function g($key = '', $replaces = [], $slang = ''): array|string|int|bool;

// Controller packages under cm/. Same shape, one extra leading segment for the area.
public static function gc($name = '', $replaces = [], $slang = ''): array|string|int|bool;

// The active language code, for instance "en".
public static function selected(): string;

// Machine value to human label. $dictionary is the locale prefix the value is
// appended to ("admin/orders/status-"), '@toggle', or '@list:{prefix}'.
// An unknown value falls back to itself rather than to an empty string.
public static function enum_label($value = '', $dictionary = '', $slang = ''): string;

// Writes one package file. See the warning below: this REPLACES, it does not merge.
public static function save($key = '', $data = [], $lk = ''): int|bool;

<?php
return [
    // Plain. Read as Language::gc('admin/services/page-list').
    'page-list' => 'Services',

    // With placeholders. Two notations exist and both are literal search targets:
    // the replacement map's keys are matched as written, braces and colons included.
    'welcome'   => 'Hello {name}, you have {count} messages.',
    'meta-title' => 'Service detail - :name',

    // Declared form. g()/gc() return the 'content' string; 'variables' is metadata
    // for the translation tooling and never reaches the screen.
    'quota-warning' => [
        'content'   => 'Only {left} of {total} remaining.',
        'variables' => '{left},{total}',
    ],

    // A slash in a key is DEPTH, not part of the name. This is the only way to
    // make Language::gc('admin/services/labels/renew') resolve.
    'labels' => [
        'renew'   => 'Renew',
        'suspend' => 'Suspend',
    ],
];

// One string, with optional placeholder substitution.
public function lang(string $key, array $vars = []): string;

// The content editor's own surface, for a module that wants to read or write it.
public static function contentScopes(string $themeName): array;
public static function scopeDefaults(string $themeName, string $lang, string $scope): array;
public static function scopeOverrides(string $themeName, string $lang, string $scope): array;
public static function writeScopeOverrides(string $themeName, string $lang, string $scope, array $values): bool;

// Key => replacement, per language. A map lookup keeps the listener O(1); a
// str_replace over every string in the panel would not be acceptable here.
const ACME_WORDING = [
    'en' => [
        'admin/services/page-list'  => 'Subscriptions',
        'admin/services/page-title' => 'Subscription detail',
    ],
    'tr' => [
        'admin/services/page-list'  => 'Abonelikler',
        'admin/services/page-title' => 'Abonelik detayı',
    ],
];

Hook::add('filter:i18n.translation', 10, function (&$value, $key, $lang) {
    // Only controller-package strings arrive here, and only when they resolved
    // to a string: a missing key never fires this hook, so a gap cannot be
    // filled from here.
    $value = ACME_WORDING[$lang][$key] ?? $value;
});

Hook::add('filter:template.variables', 10, function ($template_path, $data) {
    // Normalise: the path arrives with the platform's directory separator.
    $path = str_replace('\\', '/', (string) $template_path);

    if (!str_ends_with($path, 'admin/services/detail.php')) return null;   // not ours

    // The return REPLACES $data entirely. Building on the incoming array is not
    // a style choice: dropping template_dir or ui_lang breaks the render.
    $data['acme_banner'] = Language::gc('admin/services/acme-banner');

    return $data;
});

// Markup, at a position the platform announces. The return value is printed
// as-is, so anything variable in it has to be escaped here.
Hook::add('ui:admin.head.css', 10, fn (): string
    => '<link rel="stylesheet" href="' . Utility::AppAdress() . '/resources/acme/panel.css">');

// The installed languages are a directory listing, never a hardcoded pair.
$langs = array_map('basename', glob(ROOT_DIR . 'coremio' . DS . 'locale' . DS . '*', GLOB_ONLYDIR) ?: []);

foreach ($langs as $lang) {
    // Resolve in that language explicitly: the third argument, not the second.
    $existing = Language::gc('admin/services/acme-banner', [], $lang);

    // false means the key is missing THERE, even if it resolves in English.
    if ($existing === false)
        echo 'missing in ' . $lang . PHP_EOL;
}

// Reading one key in one language, from the command line, is how you settle an
// argument about which accessor a package needs.
var_dump(Language::g('needs/untitled', [], 'tr'));    // string, root package
var_dump(Language::gc('needs/untitled', [], 'tr'));   // false, wrong accessor

<?php
// Overrides the matching keys of locale/en/home.php for this theme only.
// The panel writes this file; a module may write it through the theme API.
// An upgrade replaces locale/, never content/, so the override survives.
return [
    'hero-title'    => 'Hosting that stays out of your way',
    'hero-subtitle' => 'Deploy in a minute, scale when you need to.',
];

$theme = Theme::active()->getName();

// Read the shipped defaults and the operator's current overrides separately:
// they are two layers, and merging them before writing would freeze the defaults.
$defaults  = Theme::scopeDefaults($theme, 'en', 'home');
$overrides = Theme::scopeOverrides($theme, 'en', 'home');

$overrides['hero-title'] = 'Hosting that stays out of your way';

// An empty array removes the override file entirely, restoring the defaults.
Theme::writeScopeOverrides($theme, 'en', 'home', $overrides);