feat(i18n): compile immutable user copy catalogs
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;
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue