feat(i18n): compile immutable user copy catalogs

go
codex 2 weeks ago
parent 884a606c2e
commit 68caff0048

@ -0,0 +1,251 @@
<?php
namespace App\Services\UserCopy;
use MessageFormatter;
/**
* Compiles source-owned entries and administrator-owned translations into one
* deterministic, immutable locale generation.
*/
final class UserCopyCatalogCompiler
{
public function __construct(private readonly UserCopySourceCatalog $source)
{
}
/**
* @param array<string,string|array<string,mixed>> $translations
*/
public function compile(
string $locale,
array $translations = []
): UserCopyCompiledCatalog {
$locale = $this->normalizeLocale($locale);
$entries = $this->source->entries();
foreach (array_keys($translations) as $key) {
if (!is_string($key) || !isset($entries[$key])) {
throw new UserCopyCatalogException(
'Translation references an unknown user copy key.'
);
}
}
$scopes = [];
foreach ($this->source->scopes() as $scope) {
$scopes[$scope] = [
'schema' => 1,
'locale' => $locale,
'scope' => $scope,
'messages' => [],
'metadata' => [],
];
}
foreach ($entries as $key => $entry) {
$this->validateMessage($key, $entry, $entry['source'], 'zh-CN');
[$message, $hidden, $translated] = $this->translationFor(
$key,
$entry,
$translations[$key] ?? null
);
if (!$hidden) {
$this->validateMessage($key, $entry, $message, $locale);
}
$scope = $entry['scope'];
$scopes[$scope]['messages'][$key] = $message;
$scopes[$scope]['metadata'][$key] = [
'kind' => $entry['kind'],
'criticality' => $entry['criticality'],
'severity' => $entry['severity'],
'format' => $entry['format'],
'required' => $entry['required'],
'allow_hide' => $entry['allow_hide'],
'hidden' => $hidden,
'translated' => $translated,
'parameters' => $entry['parameters'],
'source_hash' => $entry['source_hash'],
'placeholder_hash' => $entry['placeholder_hash'],
];
}
ksort($scopes, SORT_STRING);
foreach ($scopes as &$payload) {
ksort($payload['messages'], SORT_STRING);
ksort($payload['metadata'], SORT_STRING);
}
unset($payload);
$scopeManifest = [];
foreach ($scopes as $scope => $payload) {
$scopeManifest[$scope] = [
'php' => $locale . '/' . $scope . '.php',
'json' => $locale . '/' . $scope . '.json',
'payload_sha256' => hash(
'sha256',
UserCopySourceCatalog::canonicalJson($payload)
),
'entry_count' => count($payload['messages']),
];
}
$catalogHash = hash('sha256', UserCopySourceCatalog::canonicalJson(
array_map(
static fn (array $scope): string => $scope['payload_sha256'],
$scopeManifest
)
));
$manifest = [
'schema' => 1,
'locale' => $locale,
'catalog_sha256' => $catalogHash,
'source_manifest_sha256' => $this->source->sourceHash(),
'page_scopes' => $this->source->pageScopes(),
'scopes' => $scopeManifest,
];
$generation = 'g-' . hash(
'sha256',
UserCopySourceCatalog::canonicalJson($manifest)
);
$manifest['generation'] = $generation;
return new UserCopyCompiledCatalog(
$locale,
$generation,
$manifest,
$scopes
);
}
/**
* @param array<string,mixed> $entry
* @param string|array<string,mixed>|null $translation
* @return array{0:string,1:bool,2:bool}
*/
private function translationFor(
string $key,
array $entry,
string|array|null $translation
): array {
if ($translation === null) {
return [$entry['source'], false, false];
}
$hidden = false;
if (is_array($translation)) {
$hidden = ($translation['hidden'] ?? false) === true;
$translation = $translation['text']
?? $translation['translation']
?? null;
if ($hidden && $translation === null) {
$translation = '';
}
}
if (!is_string($translation)) {
throw new UserCopyCatalogException(
'Translation must contain text for ' . $key . '.'
);
}
if ($hidden) {
if (!$entry['allow_hide']
|| $entry['criticality'] !== 'normal'
|| $entry['required']) {
throw new UserCopyCatalogException(
'Required or safety copy cannot be hidden: ' . $key
);
}
return ['', true, true];
}
return [$translation, false, true];
}
/** @param array<string,mixed> $entry */
private function validateMessage(
string $key,
array $entry,
string $message,
string $locale
): void {
if (trim($message) === '') {
throw new UserCopyCatalogException(
'User copy text cannot be empty: ' . $key
);
}
if (mb_strlen($message) > $entry['max_length']) {
throw new UserCopyCatalogException(
'User copy text exceeds its length limit: ' . $key
);
}
if (preg_match(
'/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/u',
$message
) === 1 || preg_match(
'/[\x{061C}\x{200E}\x{200F}\x{202A}-\x{202E}\x{2066}-\x{2069}]/u',
$message
) === 1) {
throw new UserCopyCatalogException(
'User copy text contains forbidden control characters: ' . $key
);
}
if (preg_match('/<\s*\/?\s*[A-Za-z][^>]*>/u', $message) === 1) {
throw new UserCopyCatalogException(
'User copy text must not contain HTML: ' . $key
);
}
$used = $this->extractParameters($message);
$declared = $entry['parameters'];
sort($used, SORT_STRING);
sort($declared, SORT_STRING);
if ($used !== $declared) {
throw new UserCopyCatalogException(
'User copy placeholders do not match the manifest: ' . $key
);
}
if ($entry['format'] === 'icu') {
$formatter = MessageFormatter::create($locale, $message);
if (!$formatter instanceof MessageFormatter) {
throw new UserCopyCatalogException(
'Invalid ICU user copy pattern for ' . $key . ': '
. intl_get_error_message()
);
}
}
}
/** @return list<string> */
private function extractParameters(string $message): array
{
preg_match_all(
'/\{\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*(?:[,}])/u',
$message,
$matches
);
$parameters = array_values(array_unique($matches[1] ?? []));
sort($parameters, SORT_STRING);
return $parameters;
}
private function normalizeLocale(string $locale): string
{
$locale = str_replace('_', '-', trim($locale));
if (preg_match(
'/\A[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*\z/D',
$locale
) !== 1) {
throw new UserCopyCatalogException('Invalid user copy locale.');
}
$segments = explode('-', $locale);
$segments[0] = strtolower($segments[0]);
for ($index = 1; $index < count($segments); $index++) {
$segments[$index] = strlen($segments[$index]) === 2
? strtoupper($segments[$index])
: $segments[$index];
}
return implode('-', $segments);
}
}

@ -0,0 +1,7 @@
<?php
namespace App\Services\UserCopy;
final class UserCopyCatalogException extends \RuntimeException
{
}

@ -0,0 +1,19 @@
<?php
namespace App\Services\UserCopy;
/** Immutable compiler result consumed by the publication Adapter. */
final class UserCopyCompiledCatalog
{
/**
* @param array<string,mixed> $manifest
* @param array<string,array<string,mixed>> $scopes
*/
public function __construct(
public readonly string $locale,
public readonly string $generation,
public readonly array $manifest,
public readonly array $scopes
) {
}
}

@ -0,0 +1,357 @@
<?php
namespace App\Services\UserCopy;
/**
* Normalized, immutable view of the source-owned copy manifest.
*
* The catalog accepts either an iterable of entries or a future manifest
* object exposing entries() and pageScopes(). Runtime and publication code do
* not need to know which source-manifest implementation owns those entries.
*/
final class UserCopySourceCatalog
{
/** @var array<string,array<string,mixed>> */
private array $entries;
/** @var array<string,list<string>> */
private array $pageScopes;
/**
* @param iterable<int|string,array<string,mixed>>|object $manifest
*/
public function __construct(iterable|object $manifest)
{
[$entries, $pageScopes] = $this->readManifest($manifest);
$this->entries = $this->normalizeEntries($entries);
$this->pageScopes = $this->normalizePageScopes($pageScopes);
}
/** @return array<string,array<string,mixed>> */
public function entries(): array
{
return $this->entries;
}
/** @return array<string,list<string>> */
public function pageScopes(): array
{
return $this->pageScopes;
}
/** @return list<string> */
public function scopes(): array
{
$scopes = [];
foreach ($this->entries as $entry) {
$scopes[$entry['scope']] = true;
}
if (isset($this->pageScopes)) {
foreach ($this->pageScopes as $pageScopes) {
foreach ($pageScopes as $scope) {
$scopes[$scope] = true;
}
}
}
$result = array_keys($scopes);
sort($result, SORT_STRING);
return $result;
}
/** @return array<string,array<string,mixed>> */
public function entriesForScopes(array $scopes): array
{
$wanted = array_fill_keys($scopes, true);
return array_filter(
$this->entries,
static fn (array $entry): bool => isset($wanted[$entry['scope']])
);
}
public function sourceHash(): string
{
return hash('sha256', self::canonicalJson([
'entries' => $this->entries,
'page_scopes' => $this->pageScopes,
]));
}
/**
* @param iterable<int|string,array<string,mixed>>|object $manifest
* @return array{0:iterable<int|string,array<string,mixed>>,1:array<mixed>}
*/
private function readManifest(iterable|object $manifest): array
{
if (is_object($manifest) && method_exists($manifest, 'entries')) {
$entries = $manifest->entries();
if (!is_iterable($entries)) {
throw new UserCopyCatalogException(
'User copy manifest entries must be iterable.'
);
}
$pageScopes = method_exists($manifest, 'pageScopes')
? $manifest->pageScopes() : [];
if (!is_array($pageScopes)) {
throw new UserCopyCatalogException(
'User copy manifest page scopes must be an array.'
);
}
return [$entries, $pageScopes];
}
if (is_array($manifest)
&& isset($manifest['entries'])
&& is_array($manifest['entries'])) {
$pageScopes = [];
foreach (($manifest['pages'] ?? []) as $page => $definition) {
if (is_string($page) && is_array($definition)
&& is_array($definition['scopes'] ?? null)) {
$pageScopes[$page] = $definition['scopes'];
}
}
return [$manifest['entries'], $pageScopes];
}
if (is_iterable($manifest)) {
return [$manifest, []];
}
throw new UserCopyCatalogException(
'User copy manifest must be iterable or expose entries().'
);
}
/**
* @param iterable<int|string,array<string,mixed>> $entries
* @return array<string,array<string,mixed>>
*/
private function normalizeEntries(iterable $entries): array
{
$normalized = [];
foreach ($entries as $index => $entry) {
if (!is_array($entry)) {
throw new UserCopyCatalogException(
'Every user copy manifest entry must be an array.'
);
}
$key = $this->requiredString(
$entry,
['key', 'copy_key'],
is_string($index) ? $index : null
);
if (preg_match('/\A[a-z0-9][a-z0-9._-]{1,190}\z/D', $key) !== 1) {
throw new UserCopyCatalogException(
'Invalid user copy key: ' . $key
);
}
if (isset($normalized[$key])) {
throw new UserCopyCatalogException(
'Duplicate user copy key: ' . $key
);
}
$scope = $this->requiredString($entry, ['scope']);
if (preg_match('/\A[a-z0-9][a-z0-9._-]{0,63}\z/D', $scope) !== 1) {
throw new UserCopyCatalogException(
'Invalid user copy scope for ' . $key . '.'
);
}
$source = $this->requiredString(
$entry,
['source', 'source_text', 'default_zh']
);
$kind = $this->optionalString($entry, ['kind'], 'text');
$criticality = $this->optionalString(
$entry,
['criticality'],
'normal'
);
$format = $this->optionalString(
$entry,
['format'],
'plain_text'
);
if (!in_array($format, ['plain_text', 'icu'], true)) {
throw new UserCopyCatalogException(
'Unsupported user copy format: ' . $key
);
}
$declaredParameters = $entry['parameters']
?? $entry['placeholders']
?? $entry['placeholder_contract']
?? [];
if (is_array($declaredParameters)
&& !array_is_list($declaredParameters)) {
$declaredParameters = array_keys($declaredParameters);
}
if (!is_array($declaredParameters)) {
throw new UserCopyCatalogException(
'User copy placeholders must be an array: ' . $key
);
}
$parameters = [];
foreach ($declaredParameters as $parameter) {
if (!is_string($parameter)
|| preg_match(
'/\A[A-Za-z_][A-Za-z0-9_.-]*\z/D',
$parameter
) !== 1) {
throw new UserCopyCatalogException(
'Invalid user copy placeholder for ' . $key . '.'
);
}
$parameters[$parameter] = true;
}
$parameters = array_keys($parameters);
sort($parameters, SORT_STRING);
$maxLength = $entry['max_length'] ?? 4000;
if (!is_int($maxLength) || $maxLength < 1 || $maxLength > 20000) {
throw new UserCopyCatalogException(
'Invalid user copy maximum length for ' . $key . '.'
);
}
$severity = 'info';
if (is_string($entry['severity'] ?? null)
&& trim($entry['severity']) !== '') {
$severity = $entry['severity'];
} elseif (is_string($entry['toast_tone'] ?? null)
&& trim($entry['toast_tone']) !== '') {
$severity = $entry['toast_tone'];
}
$normalized[$key] = [
'key' => $key,
'scope' => $scope,
'source' => $source,
'kind' => $kind,
'criticality' => $criticality,
'severity' => $severity,
'format' => $format,
'required' => (bool) ($entry['required']
?? ($criticality !== 'normal')),
'allow_hide' => (bool) ($entry['allow_hide'] ?? false),
'max_length' => $maxLength,
'parameters' => $parameters,
'source_hash' => hash('sha256', $source),
'placeholder_hash' => hash(
'sha256',
self::canonicalJson($parameters)
),
];
}
ksort($normalized, SORT_STRING);
return $normalized;
}
/** @param array<mixed> $pageScopes @return array<string,list<string>> */
private function normalizePageScopes(array $pageScopes): array
{
$normalized = [];
foreach ($pageScopes as $page => $scopes) {
if (!is_string($page)
|| preg_match('/\A[a-z0-9][a-z0-9._-]{0,95}\z/D', $page) !== 1
|| !is_array($scopes)) {
throw new UserCopyCatalogException(
'Invalid user copy page scope declaration.'
);
}
$clean = [];
foreach ($scopes as $scope) {
if (!is_string($scope)
|| preg_match(
'/\A[a-z0-9][a-z0-9._-]{0,63}\z/D',
$scope
) !== 1) {
throw new UserCopyCatalogException(
'Invalid user copy scope on page ' . $page . '.'
);
}
$clean[$scope] = true;
}
$list = array_keys($clean);
sort($list, SORT_STRING);
$normalized[$page] = $list;
}
ksort($normalized, SORT_STRING);
return $normalized;
}
/** @param array<string,mixed> $entry @param list<string> $aliases */
private function requiredString(
array $entry,
array $aliases,
?string $fallback = null
): string {
foreach ($aliases as $alias) {
if (array_key_exists($alias, $entry)) {
$value = $entry[$alias];
if (is_string($value) && trim($value) !== '') {
return $value;
}
break;
}
}
if ($fallback !== null && trim($fallback) !== '') {
return $fallback;
}
throw new UserCopyCatalogException(
'User copy manifest is missing ' . implode('/', $aliases) . '.'
);
}
/** @param array<string,mixed> $entry @param list<string> $aliases */
private function optionalString(
array $entry,
array $aliases,
string $fallback
): string {
foreach ($aliases as $alias) {
if (array_key_exists($alias, $entry)) {
$value = $entry[$alias];
if (is_string($value) && trim($value) !== '') {
return $value;
}
throw new UserCopyCatalogException(
'User copy manifest field ' . $alias
. ' must be a non-empty string.'
);
}
}
return $fallback;
}
/** @param mixed $value */
public static function canonicalJson($value): string
{
$encoded = json_encode(
self::canonicalize($value),
JSON_UNESCAPED_SLASHES
| JSON_UNESCAPED_UNICODE
| JSON_THROW_ON_ERROR
);
return $encoded;
}
/** @param mixed $value @return mixed */
private static function canonicalize($value)
{
if (!is_array($value)) {
return $value;
}
if (array_is_list($value)) {
return array_map([self::class, 'canonicalize'], $value);
}
ksort($value, SORT_STRING);
foreach ($value as $key => $child) {
$value[$key] = self::canonicalize($child);
}
return $value;
}
}

@ -4,6 +4,7 @@ require dirname(__DIR__) . '/vendor/autoload.php';
use App\Services\UserCopy\UserCopyCoverageScanner;
use App\Services\UserCopy\UserCopyManifest;
use App\Services\UserCopy\UserCopySourceCatalog;
$assert = static function (bool $condition, string $message): void {
if (!$condition) {
@ -30,6 +31,14 @@ $assert(($manifest['version'] ?? null) === 1
'Source-language user-copy Manifest did not load its page and Toast contract.');
$assert(strlen(UserCopyManifest::digest($manifest)) === 64,
'User-copy Manifest digest is not a SHA-256 identity.');
$runtimeSource = new UserCopySourceCatalog($manifest);
$assert(isset($runtimeSource->entries()['common.toast.success.title'])
&& in_array(
'backups',
$runtimeSource->pageScopes()['cloud.backups'],
true
),
'Validated Manifest is incompatible with the runtime source catalog.');
$base = [
'version' => 1,
'pages' => [

Loading…
Cancel
Save