From e9d7340a1fdfec511477cc764008e75e13824476 Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 7 Nov 2026 13:59:50 +0800 Subject: [PATCH] refactor(i18n): add copy authoring metadata --- .../Services/UserCopy/UserCopyManifest.php | 21 ++- web/resources/user-copy/entry.php | 68 ++++++++- web/resources/user-copy/manifest.php | 141 ++++++------------ web/tests/UserCopyAdminServiceTest.php | 5 + web/tests/UserCopyCatalogRuntimeTest.php | 5 + web/tests/UserCopyManifestContractTest.php | 62 ++++++++ web/tests/UserCopyPublicationStoreTest.php | 2 + web/tests/UserCopyUserRuntimeTest.php | 2 + 8 files changed, 204 insertions(+), 102 deletions(-) diff --git a/web/app/Services/UserCopy/UserCopyManifest.php b/web/app/Services/UserCopy/UserCopyManifest.php index 8194f51d..57af74a8 100644 --- a/web/app/Services/UserCopy/UserCopyManifest.php +++ b/web/app/Services/UserCopy/UserCopyManifest.php @@ -32,10 +32,14 @@ final class UserCopyManifest 'currency', 'bytes', 'boolean', ]; private const TOAST_TONES = ['success', 'info', 'warning', 'error']; + private const EDITOR_SURFACES = [ + 'page', 'dialog', 'feedback', 'task', 'accessibility', + ]; private const ENTRY_FIELDS = [ 'key', 'scope', 'page', 'kind', 'source', 'format', 'parameters', - 'criticality', 'allow_hide', 'toast_tone', + 'criticality', 'allow_hide', 'toast_tone', 'editor_surface', + 'editor_group', ]; public static function load(?string $path = null): array @@ -209,6 +213,19 @@ final class UserCopyManifest ); } + $editorSurface = (string) ($entry['editor_surface'] ?? ''); + if (!in_array($editorSurface, self::EDITOR_SURFACES, true)) { + throw new InvalidArgumentException( + '词条编辑表面无效:' . $copyKey + ); + } + $editorGroup = (string) ($entry['editor_group'] ?? ''); + if (preg_match(self::PAGE_PATTERN, $editorGroup) !== 1) { + throw new InvalidArgumentException( + '词条编辑分组无效:' . $copyKey + ); + } + $entries[$copyKey] = [ 'key' => $copyKey, 'scope' => $scope, @@ -220,6 +237,8 @@ final class UserCopyManifest 'criticality' => $criticality, 'allow_hide' => $allowHide, 'toast_tone' => $toastTone, + 'editor_surface' => $editorSurface, + 'editor_group' => $editorGroup, ]; } diff --git a/web/resources/user-copy/entry.php b/web/resources/user-copy/entry.php index 20a5c0f0..afa71a6b 100644 --- a/web/resources/user-copy/entry.php +++ b/web/resources/user-copy/entry.php @@ -6,6 +6,61 @@ * Fragments contain only stable keys, Chinese baselines and rendering * contracts. Administrator-owned target translations never belong here. */ +$surfaceFor = static function ( + string $key, + string $kind, + ?string $toastTone, + ?string $requested +): string { + if ($requested !== null) { + return $requested; + } + if (str_starts_with($key, 'common.tasks.') + || str_starts_with($key, 'common.drawer.tasks.')) { + return 'task'; + } + if (in_array($kind, ['aria_label', 'tooltip', 'placeholder'], true)) { + return 'accessibility'; + } + if ($kind === 'confirmation' + || str_contains($key, '.dialog.') + || str_contains($key, '.drawer.')) { + return 'dialog'; + } + if ($toastTone !== null + || str_starts_with($kind, 'toast_') + || in_array( + $kind, + ['warning', 'notice', 'empty_state', 'status'], + true + )) { + return 'feedback'; + } + return 'page'; +}; + +$groupFor = static function (string $key, string $page, ?string $requested): string { + if ($requested !== null) { + return $requested; + } + if (str_starts_with($key, 'common.tasks.') + || str_starts_with($key, 'common.drawer.tasks.')) { + return 'user.tasks'; + } + if (str_starts_with($key, 'common.announcements.') + || str_starts_with($key, 'common.drawer.announcements.')) { + return 'user.announcements'; + } + if (str_starts_with($key, 'common.account.') + || str_starts_with($key, 'common.drawer.account.')) { + return 'user.account'; + } + if (str_starts_with($key, 'common.promotion.')) { + return 'user.invite'; + } + return str_starts_with($key, 'common.') ? 'common.shared' : $page; +}; + return static function ( string $key, string $scope, @@ -15,8 +70,10 @@ return static function ( array $parameters = [], string $criticality = 'required', bool $allowHide = false, - ?string $toastTone = null -): array { + ?string $toastTone = null, + ?string $editorSurface = null, + ?string $editorGroup = null +) use ($surfaceFor, $groupFor): array { return [ 'key' => $key, 'scope' => $scope, @@ -28,5 +85,12 @@ return static function ( 'criticality' => $criticality, 'allow_hide' => $allowHide, 'toast_tone' => $toastTone, + 'editor_surface' => $surfaceFor( + $key, + $kind, + $toastTone, + $editorSurface + ), + 'editor_group' => $groupFor($key, $page, $editorGroup), ]; }; diff --git a/web/resources/user-copy/manifest.php b/web/resources/user-copy/manifest.php index 816f8938..ce12fa2f 100644 --- a/web/resources/user-copy/manifest.php +++ b/web/resources/user-copy/manifest.php @@ -7,23 +7,30 @@ * here. English and every other target-locale translation are maintained by * administrators and must never be committed to this source manifest. */ -$common = static function ( +$entry = require __DIR__ . '/entry.php'; +$manifestCommon = static function ( string $key, string $source, - string $kind = 'label' -): array { - return [ - 'key' => $key, - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => $kind, - 'source' => $source, - 'format' => 'plain_text', - 'parameters' => [], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => null, - ]; + string $kind = 'label', + array $parameters = [], + string $criticality = 'required', + ?string $toastTone = null, + ?string $editorSurface = null, + ?string $editorGroup = null +) use ($entry): array { + return $entry( + $key, + 'common', + 'cloud.instances', + $source, + $kind, + $parameters, + $criticality, + false, + $toastTone, + $editorSurface, + $editorGroup + ); }; $pageEntries = []; @@ -41,6 +48,11 @@ if (is_array($pageEntryFiles)) { } } +// Entry fragments share this file scope and may use a local $common helper. +// Restore the manifest helper after loading them so the shared shell entries +// below always use the same editor metadata policy as every other fragment. +$common = $manifestCommon; + return [ 'version' => 1, 'pages' => [ @@ -130,94 +142,25 @@ return [ '服务返回了无效数据,请稍后重试。', 'warning'), $common('common.error.login_expired', '登录已过期,请重新登录。', 'warning'), $common('common.error.invalid_input', '输入内容无效,请检查后重试。', 'warning'), - [ - 'key' => 'common.error.request', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'warning', - 'source' => '请求失败(状态码 {status}),请稍后重试。', - 'format' => 'icu', - 'parameters' => ['status' => 'integer'], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => null, - ], - [ - 'key' => 'common.error.unexpected_status', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'warning', - 'source' => '请求已送达,但服务返回了意外状态({status})。请勿重复提交,并联系管理员核查。', - 'format' => 'icu', - 'parameters' => ['status' => 'integer'], - 'criticality' => 'critical', - 'allow_hide' => false, - 'toast_tone' => null, - ], + $common('common.error.request', + '请求失败(状态码 {status}),请稍后重试。', + 'warning', ['status' => 'integer']), + $common('common.error.unexpected_status', + '请求已送达,但服务返回了意外状态({status})。请勿重复提交,并联系管理员核查。', + 'warning', ['status' => 'integer'], 'critical'), $common('common.error.task_receipt_invalid', '请求已送达,但任务回执协议无效。请勿重复提交,并联系管理员核查。', 'warning'), $common('common.copy.empty', '没有可复制的内容', 'notice'), $common('common.copy.failed', '复制失败,请手动复制', 'warning'), - [ - 'key' => 'common.toast.close.aria', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'aria_label', - 'source' => '关闭提示', - 'format' => 'plain_text', - 'parameters' => [], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => null, - ], - [ - 'key' => 'common.toast.error.title', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'toast_title', - 'source' => '操作失败', - 'format' => 'plain_text', - 'parameters' => [], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => 'error', - ], - [ - 'key' => 'common.toast.success.body', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'toast_body', - 'source' => '操作已完成。', - 'format' => 'plain_text', - 'parameters' => [], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => 'success', - ], - [ - 'key' => 'common.toast.success.title', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'toast_title', - 'source' => '操作完成', - 'format' => 'plain_text', - 'parameters' => [], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => 'success', - ], - [ - 'key' => 'common.toast.warning.title', - 'scope' => 'common', - 'page' => 'cloud.instances', - 'kind' => 'toast_title', - 'source' => '请注意', - 'format' => 'plain_text', - 'parameters' => [], - 'criticality' => 'required', - 'allow_hide' => false, - 'toast_tone' => 'warning', - ], + $common('common.toast.close.aria', '关闭提示', 'aria_label'), + $common('common.toast.error.title', '操作失败', 'toast_title', [], + 'required', 'error'), + $common('common.toast.success.body', '操作已完成。', 'toast_body', [], + 'required', 'success'), + $common('common.toast.success.title', '操作完成', 'toast_title', [], + 'required', 'success'), + $common('common.toast.warning.title', '请注意', 'toast_title', [], + 'required', 'warning'), ], $pageEntries), ]; diff --git a/web/tests/UserCopyAdminServiceTest.php b/web/tests/UserCopyAdminServiceTest.php index 6714526d..18050594 100644 --- a/web/tests/UserCopyAdminServiceTest.php +++ b/web/tests/UserCopyAdminServiceTest.php @@ -169,6 +169,7 @@ $manifest = [ 'format' => 'icu', 'parameters' => ['count' => 'integer'], 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'test.page', ], [ 'key' => 'test.help', 'scope' => 'test', @@ -176,6 +177,7 @@ $manifest = [ 'source' => '可选说明', 'format' => 'plain_text', 'parameters' => [], 'criticality' => 'normal', 'allow_hide' => true, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'test.page', ], [ 'key' => 'test.title', 'scope' => 'test', @@ -183,6 +185,7 @@ $manifest = [ 'source' => '中文标题', 'format' => 'plain_text', 'parameters' => [], 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'test.page', ], [ 'key' => 'test.warning', 'scope' => 'test', @@ -190,6 +193,7 @@ $manifest = [ 'source' => '高风险操作提醒', 'format' => 'plain_text', 'parameters' => [], 'criticality' => 'critical', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'feedback', 'editor_group' => 'test.page', ], ], ]; @@ -408,6 +412,7 @@ try { 'source' => '新状态', 'format' => 'plain_text', 'parameters' => [], 'criticality' => 'normal', 'allow_hide' => true, 'toast_tone' => null, + 'editor_surface' => 'feedback', 'editor_group' => 'test.page', ]; $changedSync = new UserCopyManifestSynchronizer($database, $changedManifest); $changed = $changedSync->synchronize((int) $super['user_id']); diff --git a/web/tests/UserCopyCatalogRuntimeTest.php b/web/tests/UserCopyCatalogRuntimeTest.php index dee05c3d..94bc17b9 100644 --- a/web/tests/UserCopyCatalogRuntimeTest.php +++ b/web/tests/UserCopyCatalogRuntimeTest.php @@ -66,6 +66,7 @@ $manifest = UserCopyManifest::validate([ 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => 'success', + 'editor_surface' => 'feedback', 'editor_group' => 'common.shared', ], [ 'key' => 'common.toast.success.body', @@ -78,6 +79,7 @@ $manifest = UserCopyManifest::validate([ 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => 'success', + 'editor_surface' => 'feedback', 'editor_group' => 'common.shared', ], [ 'key' => 'instances.title', @@ -90,6 +92,7 @@ $manifest = UserCopyManifest::validate([ 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'cloud.instances', ], [ 'key' => 'instances.count', @@ -102,6 +105,7 @@ $manifest = UserCopyManifest::validate([ 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'cloud.instances', ], [ 'key' => 'instances.optional_help', @@ -114,6 +118,7 @@ $manifest = UserCopyManifest::validate([ 'criticality' => 'normal', 'allow_hide' => true, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'cloud.instances', ], ], ]); diff --git a/web/tests/UserCopyManifestContractTest.php b/web/tests/UserCopyManifestContractTest.php index ab1dc4cb..44983fe0 100644 --- a/web/tests/UserCopyManifestContractTest.php +++ b/web/tests/UserCopyManifestContractTest.php @@ -3,6 +3,7 @@ require dirname(__DIR__) . '/vendor/autoload.php'; use App\Services\UserCopy\UserCopyCoverageScanner; +use App\Services\UserCopy\UserCopyCatalogCompiler; use App\Services\UserCopy\UserCopyManifest; use App\Services\UserCopy\UserCopySourceCatalog; @@ -29,6 +30,38 @@ $assert(($manifest['version'] ?? null) === 1 && isset($manifest['pages']['cloud.instances']) && isset($loadedEntries['common.toast.success.title']), 'Source-language user-copy Manifest did not load its page and Toast contract.'); +$assert(($loadedEntries['common.toast.success.title']['editor_surface'] ?? null) + === 'feedback' + && ($loadedEntries['common.tasks.status.running']['editor_surface'] ?? null) + === 'task' + && ($loadedEntries['common.tasks.status.running']['editor_group'] ?? null) + === 'user.tasks', + 'User-copy editor surfaces or task authoring groups are incomplete.'); +foreach ($loadedEntries as $copyKey => $entry) { + $assert(is_string($entry['editor_surface'] ?? null) + && is_string($entry['editor_group'] ?? null), + 'User-copy entry lacks editor metadata: ' . $copyKey); + if (str_starts_with($copyKey, 'common.tasks.')) { + $assert($entry['editor_surface'] === 'task', + 'Task-center copy is not isolated from page editing: ' . $copyKey); + } + if (str_starts_with((string) $entry['kind'], 'toast_')) { + $assert($entry['editor_surface'] === 'feedback', + 'Toast copy is not assigned to feedback editing: ' . $copyKey); + } + if (in_array($entry['kind'], ['aria_label', 'tooltip', 'placeholder'], true)) { + $assert(in_array( + $entry['editor_surface'], + ['accessibility', 'task'], + true + ), + 'Attribute copy is not assigned to accessibility editing: ' . $copyKey); + } + if ($entry['kind'] === 'confirmation') { + $assert($entry['editor_surface'] === 'dialog', + 'Confirmation copy is not assigned to dialog editing: ' . $copyKey); + } +} $hashedDetailKeys = array_filter( array_keys($loadedEntries), static fn (string $key): bool => str_contains($key, '.dynamic.h') @@ -59,6 +92,7 @@ $base = [ 'parameters' => ['name' => 'string'], 'criticality' => 'normal', 'allow_hide' => true, 'toast_tone' => null, + 'editor_surface' => 'page', 'editor_group' => 'test.page', ], ], ]; @@ -68,6 +102,26 @@ $validatedBaseEntries = array_column( ); $assert($validatedBaseEntries['test.greeting']['source'] === '您好,{name}', 'Valid ICU source entry was not retained.'); +$metadataOnly = $validatedBase; +$metadataOnly['entries'][0]['editor_surface'] = 'feedback'; +$metadataOnly['entries'][0]['editor_group'] = 'common.shared'; +$metadataOnly = UserCopyManifest::validate($metadataOnly); +$assert( + hash_equals( + (new UserCopySourceCatalog($validatedBase))->sourceHash(), + (new UserCopySourceCatalog($metadataOnly))->sourceHash() + ), + 'Editor-only metadata changed the runtime source catalog identity.' +); +$baseCompiled = (new UserCopyCatalogCompiler( + new UserCopySourceCatalog($validatedBase) +))->compile('en'); +$metadataCompiled = (new UserCopyCatalogCompiler( + new UserCopySourceCatalog($metadataOnly) +))->compile('en'); +$assert($baseCompiled->generation === $metadataCompiled->generation + && $baseCompiled->scopes === $metadataCompiled->scopes, + 'Editor-only metadata changed the compiled runtime generation.'); $duplicateKey = $base; $duplicateKey['entries'][] = $duplicateKey['entries'][0]; @@ -109,6 +163,14 @@ $toastWithoutTone = $base; $toastWithoutTone['entries'][0]['kind'] = 'toast_body'; $rejects($toastWithoutTone, 'Toast 词条必须声明有效 tone'); +$invalidEditorSurface = $base; +$invalidEditorSurface['entries'][0]['editor_surface'] = 'inline'; +$rejects($invalidEditorSurface, '编辑表面无效'); + +$invalidEditorGroup = $base; +$invalidEditorGroup['entries'][0]['editor_group'] = 'Invalid Group'; +$rejects($invalidEditorGroup, '编辑分组无效'); + $source = <<<'SOURCE' toast('任务已接收。', 'success'); window.confirm('确定删除?'); diff --git a/web/tests/UserCopyPublicationStoreTest.php b/web/tests/UserCopyPublicationStoreTest.php index f58e9da5..162f9b48 100644 --- a/web/tests/UserCopyPublicationStoreTest.php +++ b/web/tests/UserCopyPublicationStoreTest.php @@ -47,6 +47,8 @@ $manifest = UserCopyManifest::validate([ 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'page', + 'editor_group' => 'test.page', ]], ]); $compiler = new UserCopyCatalogCompiler(new UserCopySourceCatalog($manifest)); diff --git a/web/tests/UserCopyUserRuntimeTest.php b/web/tests/UserCopyUserRuntimeTest.php index ad85f7a7..7491b1d9 100644 --- a/web/tests/UserCopyUserRuntimeTest.php +++ b/web/tests/UserCopyUserRuntimeTest.php @@ -118,6 +118,8 @@ try { 'criticality' => 'required', 'allow_hide' => false, 'toast_tone' => null, + 'editor_surface' => 'feedback', + 'editor_group' => 'common.shared', ]; $changedSource = new UserCopySourceCatalog( UserCopyManifest::validate($changedManifest)