From 68caff0048cb905afcb9a00f8213953dd11c6d4e Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 7 Nov 2026 03:53:54 +0800 Subject: [PATCH] feat(i18n): compile immutable user copy catalogs --- .../UserCopy/UserCopyCatalogCompiler.php | 251 ++++++++++++ .../UserCopy/UserCopyCatalogException.php | 7 + .../UserCopy/UserCopyCompiledCatalog.php | 19 + .../UserCopy/UserCopySourceCatalog.php | 357 ++++++++++++++++++ web/tests/UserCopyManifestContractTest.php | 9 + 5 files changed, 643 insertions(+) create mode 100644 web/app/Services/UserCopy/UserCopyCatalogCompiler.php create mode 100644 web/app/Services/UserCopy/UserCopyCatalogException.php create mode 100644 web/app/Services/UserCopy/UserCopyCompiledCatalog.php create mode 100644 web/app/Services/UserCopy/UserCopySourceCatalog.php diff --git a/web/app/Services/UserCopy/UserCopyCatalogCompiler.php b/web/app/Services/UserCopy/UserCopyCatalogCompiler.php new file mode 100644 index 00000000..59e5a511 --- /dev/null +++ b/web/app/Services/UserCopy/UserCopyCatalogCompiler.php @@ -0,0 +1,251 @@ +> $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 $entry + * @param string|array|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 $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 */ + 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); + } +} diff --git a/web/app/Services/UserCopy/UserCopyCatalogException.php b/web/app/Services/UserCopy/UserCopyCatalogException.php new file mode 100644 index 00000000..0bdcb4c0 --- /dev/null +++ b/web/app/Services/UserCopy/UserCopyCatalogException.php @@ -0,0 +1,7 @@ + $manifest + * @param array> $scopes + */ + public function __construct( + public readonly string $locale, + public readonly string $generation, + public readonly array $manifest, + public readonly array $scopes + ) { + } +} diff --git a/web/app/Services/UserCopy/UserCopySourceCatalog.php b/web/app/Services/UserCopy/UserCopySourceCatalog.php new file mode 100644 index 00000000..a699e322 --- /dev/null +++ b/web/app/Services/UserCopy/UserCopySourceCatalog.php @@ -0,0 +1,357 @@ +> */ + private array $entries; + + /** @var array> */ + private array $pageScopes; + + /** + * @param iterable>|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> */ + public function entries(): array + { + return $this->entries; + } + + /** @return array> */ + public function pageScopes(): array + { + return $this->pageScopes; + } + + /** @return list */ + 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> */ + 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>|object $manifest + * @return array{0:iterable>,1:array} + */ + 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> $entries + * @return array> + */ + 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 $pageScopes @return array> */ + 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 $entry @param list $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 $entry @param list $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; + } +} diff --git a/web/tests/UserCopyManifestContractTest.php b/web/tests/UserCopyManifestContractTest.php index d36a4b6a..068ac859 100644 --- a/web/tests/UserCopyManifestContractTest.php +++ b/web/tests/UserCopyManifestContractTest.php @@ -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' => [