diff --git a/AGENTS.md b/AGENTS.md index b7eee94bfe..381a1db225 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,6 +107,12 @@ the application/web-server user for intentional Nextcloud runtime writes. Some tests can alter Nextcloud state, generated certificates, app data or runtime files. Prefer focused commands while diagnosing a small change. +## Translator context hints + +Follow the [LibreSign translation guide](https://docs.libresign.coop/developer_manual/translation.html) +for the code conventions and the maintained contributor examples. +The `npm run lint:translator-hints` check enforces the source structure. + ## Command discovery and testing map Use `make help` to discover the project's high-level development tasks. The diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2907c4c0b..f6c6e77df9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,6 +66,11 @@ AI-assisted contributions are welcome. You may use AI for any part of the contri When updating your branch with changes from `main`, rebasing is preferred when practical because it avoids unnecessary merge commits and keeps the pull request history easier to review. +### Translation + +For contributing translations and writing translator context hints in code, +see the [LibreSign translation guide](https://docs.libresign.coop/developer_manual/translation.html). + ### Front and backend development environment More information [here](https://docs.libresign.coop/developer_manual/getting-started/development-environment/setup), at the [official documentation](https://docs.libresign.coop/developer_manual/getting-started/development-environment/setup) diff --git a/lib/Handler/DocMdpHandler.php b/lib/Handler/DocMdpHandler.php index 8f6c254be9..2c72fb217a 100644 --- a/lib/Handler/DocMdpHandler.php +++ b/lib/Handler/DocMdpHandler.php @@ -55,7 +55,7 @@ public function extractDocMdpData($resource): array { if ($docmdpLevel->isCertifying() && $this->isOnlySingleDocMdpViolation($isoStatus)) { $result['docmdp_validation'] = [ 'valid' => false, - // TRANSLATORS: Validation message shown for a PDF with more than one DocMDP (document modification policy) certifying signature. Only the first certifying signature defines the document permission level. + // TRANSLATORS Validation message shown for a PDF with more than one DocMDP (document modification policy) certifying signature. Only the first certifying signature defines the document permission level. 'message' => $this->l10n->t('Multiple DocMDP signatures detected. The first certifying signature determines the document\'s permission level.'), ]; } @@ -284,7 +284,7 @@ private function detectModifications($pdfResource): array { */ private function validateModifications(DocMdpLevel $docmdpLevel, array $modificationInfo, $pdfResource): array { if (!$modificationInfo['modified']) { - // TRANSLATORS: Validation result for a signed PDF that was not changed after the signature was applied. + // TRANSLATORS Validation result for a signed PDF that was not changed after the signature was applied. return $this->buildValidationResult( true, File::MODIFICATION_UNMODIFIED, @@ -293,7 +293,7 @@ private function validateModifications(DocMdpLevel $docmdpLevel, array $modifica } if ($docmdpLevel === DocMdpLevel::NOT_CERTIFIED) { - // TRANSLATORS: Validation result for a signed PDF that was modified, but the document has no DocMDP certification restrictions. + // TRANSLATORS Validation result for a signed PDF that was modified, but the document has no DocMDP certification restrictions. return $this->buildValidationResult( true, File::MODIFICATION_ALLOWED, @@ -305,7 +305,7 @@ private function validateModifications(DocMdpLevel $docmdpLevel, array $modifica $allowedTypes = self::ALLOWED_MODIFICATIONS[$docmdpLevel->name] ?? null; if ($allowedTypes === null) { - // TRANSLATORS: Validation error for a signed PDF modified in a way that violates its DocMDP (document modification policy) certification rules. + // TRANSLATORS Validation error for a signed PDF modified in a way that violates its DocMDP (document modification policy) certification rules. return $this->buildValidationResult( false, File::MODIFICATION_VIOLATION, @@ -352,13 +352,13 @@ private function buildValidationResult(bool $valid, int $status, string $message */ private function getAllowedModificationMessage(DocMdpLevel $level): string { return match ($level) { - // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing. + // TRANSLATORS Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing. DocMdpLevel::CERTIFIED_NO_CHANGES_ALLOWED => $this->l10n->t('Invalid: Document was modified after signing (DocMDP violation - no changes allowed)'), - // TRANSLATORS: Validation result for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing. + // TRANSLATORS Validation result for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing. DocMdpLevel::CERTIFIED_FORM_FILLING => $this->l10n->t('Document form fields were modified (allowed by DocMDP P=2)'), - // TRANSLATORS: Validation result for a certified PDF with DocMDP level P=3. Form field completion and annotations are allowed after signing. + // TRANSLATORS Validation result for a certified PDF with DocMDP level P=3. Form field completion and annotations are allowed after signing. DocMdpLevel::CERTIFIED_FORM_FILLING_AND_ANNOTATIONS => $this->l10n->t('Document form fields or annotations were modified (allowed by DocMDP P=3)'), - // TRANSLATORS: Generic validation result for a signed PDF that was modified after signing. + // TRANSLATORS Generic validation result for a signed PDF that was modified after signing. default => $this->l10n->t('Document was modified after signing'), }; } @@ -371,13 +371,13 @@ private function getAllowedModificationMessage(DocMdpLevel $level): string { */ private function getViolationMessage(DocMdpLevel $level): string { return match ($level) { - // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing. + // TRANSLATORS Validation error for a certified PDF with DocMDP level P=1, which does not allow any change after signing. DocMdpLevel::CERTIFIED_NO_CHANGES_ALLOWED => $this->l10n->t('Invalid: Document was modified after signing (DocMDP violation - no changes allowed)'), - // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing. + // TRANSLATORS Validation error for a certified PDF with DocMDP level P=2. Only form field completion is allowed after signing. DocMdpLevel::CERTIFIED_FORM_FILLING => $this->l10n->t('Invalid: Document was modified after signing (DocMDP P=2 only allows form field changes)'), - // TRANSLATORS: Validation error for a certified PDF with DocMDP level P=3. Only form field completion and annotations are allowed after signing. + // TRANSLATORS Validation error for a certified PDF with DocMDP level P=3. Only form field completion and annotations are allowed after signing. DocMdpLevel::CERTIFIED_FORM_FILLING_AND_ANNOTATIONS => $this->l10n->t('Invalid: Document was modified after signing (DocMDP P=3 only allows form fields and annotations)'), - // TRANSLATORS: Generic validation error for a signed PDF modified in a way that violates DocMDP (document modification policy) certification rules. + // TRANSLATORS Generic validation error for a signed PDF modified in a way that violates DocMDP (document modification policy) certification rules. default => $this->l10n->t('Invalid: Document was modified after signing (DocMDP violation)'), }; } diff --git a/lib/Handler/SigningErrorHandler.php b/lib/Handler/SigningErrorHandler.php index 4df91109c8..083ea27b20 100644 --- a/lib/Handler/SigningErrorHandler.php +++ b/lib/Handler/SigningErrorHandler.php @@ -75,11 +75,11 @@ private function isKnownError(string $message): bool { private function translateKnownError(string $message): string { return match ($message) { - // TRANSLATORS: Error returned when the signing service rejects a request to a local/private host for security reasons. + // TRANSLATORS Error returned when the signing service rejects a request to a local/private host for security reasons. 'Host violates local access rules.' => $this->l10n->t('Host violates local access rules.'), - // TRANSLATORS: Error shown when the password provided to unlock the signing certificate is incorrect. + // TRANSLATORS Error shown when the password provided to unlock the signing certificate is incorrect. 'Certificate Password Invalid.' => $this->l10n->t('Certificate Password Invalid.'), - // TRANSLATORS: Error shown when no password was provided to unlock the signing certificate. + // TRANSLATORS Error shown when no password was provided to unlock the signing certificate. 'Certificate Password is Empty.' => $this->l10n->t('Certificate Password is Empty.'), default => $message, }; @@ -92,7 +92,7 @@ private function formatUnknownError(string $message, \Throwable $exception): arr $this->logger->error($message, ['exception' => $exception]); return [[ - // TRANSLATORS: Multi-line error shown when an unexpected server error happens during signing. %1$s is the client IP address, %2$s is the request ID, and %3$s is the technical error message. Keep the Markdown formatting and line breaks. + // TRANSLATORS Multi-line error shown when an unexpected server error happens during signing. %1$s is the client IP address, %2$s is the request ID, and %3$s is the technical error message. Keep the Markdown formatting and line breaks. 'message' => $this->l10n->t( "The server was unable to complete your request.\n" . "If this happens again, please send the technical details below to the server administrator.\n" diff --git a/lib/Middleware/InjectionMiddleware.php b/lib/Middleware/InjectionMiddleware.php index c3e249ef8e..606bfd5127 100644 --- a/lib/Middleware/InjectionMiddleware.php +++ b/lib/Middleware/InjectionMiddleware.php @@ -174,7 +174,7 @@ private function isValidationUrlPrivate(): bool { private function throwPrivateValidationRedirect(?string $redirectUrl): void { throw new LibresignException(json_encode([ 'action' => JSActions::ACTION_REDIRECT, - // TRANSLATORS: Error shown to anonymous users when a private validation URL requires authentication before continuing. + // TRANSLATORS Error shown to anonymous users when a private validation URL requires authentication before continuing. 'errors' => [$this->l10n->t('You are not logged in. Please log in.')], 'redirect' => $this->urlGenerator->linkToRoute('core.login.showLoginForm', [ 'redirect_url' => $redirectUrl, @@ -308,7 +308,7 @@ private function maintainSessionConsistencyWithUuid(?string $uuid): void { private function getLoggedIn(): void { $user = $this->userSession->getUser(); if (!$user instanceof IUser) { - // TRANSLATORS: Error shown when an anonymous user tries to create a signature request, an action allowed only for authenticated users with permission. + // TRANSLATORS Error shown when an anonymous user tries to create a signature request, an action allowed only for authenticated users with permission. throw new \Exception($this->l10n->t('You are not allowed to create signature requests'), Http::STATUS_UNPROCESSABLE_ENTITY); } $this->signingRequestValidator->canRequestSign($user); diff --git a/lib/Service/File/MessagesLoader.php b/lib/Service/File/MessagesLoader.php index 216a154f3c..b695ce167a 100644 --- a/lib/Service/File/MessagesLoader.php +++ b/lib/Service/File/MessagesLoader.php @@ -35,7 +35,7 @@ public function loadMessages( if (isset($fileData->settings['canSign']) && $fileData->settings['canSign']) { $messages[] = [ 'type' => 'info', - // TRANSLATORS: Informational message shown in the file details UI when the current user is one of the required signers and still needs to sign the document. + // TRANSLATORS Informational message shown in the file details UI when the current user is one of the required signers and still needs to sign the document. 'message' => $this->l10n->t('You need to sign this document') ]; } @@ -50,7 +50,7 @@ public function loadMessages( if (empty($fileData->signers)) { $messages[] = [ 'type' => 'info', - // TRANSLATORS: Informational message shown when the current user can request signatures in general, but no eligible signer can be added for this specific document. + // TRANSLATORS Informational message shown when the current user can request signatures in general, but no eligible signer can be added for this specific document. 'message' => $this->l10n->t('You cannot create a signature request for this document. Please contact your administrator.') ]; } diff --git a/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php b/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php index 8350d8e79b..5c0227e9bc 100644 --- a/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php +++ b/lib/Service/IdentifyMethod/RuntimeRequirementValidator.php @@ -117,7 +117,7 @@ private function summarizeVerificationState(array $methodsByName): array { */ public function validateRequiredFactorsCompleted(array $summary): void { if ($summary['identifiedRequiredFactors'] < $summary['requiredFactors']) { - // TRANSLATORS: Error shown when a signer tries to sign before completing every identification factor marked as required, such as email, password, or document validation. + // TRANSLATORS Error shown when a signer tries to sign before completing every identification factor marked as required, such as email, password, or document validation. throw new LibresignException($this->l10n->t('You need to complete all required identification factors before signing.')); } } @@ -131,7 +131,7 @@ public function validateRequiredFactorsCompleted(array $summary): void { public function validateMinimumFactorsCompleted(array $summary, int $minimumTotalVerifiedFactors): void { $requiredVerifiedFactors = max($summary['requiredFactors'], $minimumTotalVerifiedFactors); if ($summary['identifiedFactors'] < $requiredVerifiedFactors) { - // TRANSLATORS: Error shown when signing requires a minimum number of completed identification factors. %n is the required number of verified factors. + // TRANSLATORS Error shown when signing requires a minimum number of completed identification factors. %n is the required number of verified factors. throw new LibresignException( $this->l10n->n( 'You need to complete at least %n identification factor before signing.', diff --git a/package.json b/package.json index a471473106..f89b3fd0cd 100644 --- a/package.json +++ b/package.json @@ -7,8 +7,9 @@ "scripts": { "build": "vite build", "dev": "vite build --mode development", - "lint": "eslint", + "lint": "eslint && npm run lint:translator-hints", "lint:fix": "eslint --fix", + "lint:translator-hints": "node scripts/check-translator-hints.mjs", "serve": "vite dev", "stylelint": "stylelint src/**/*.scss src/**/*.vue", "stylelint:fix": "stylelint src/**/*.scss src/**/*.vue --fix", @@ -18,6 +19,7 @@ "test:e2e:report": "playwright show-report", "test:e2e:ui": "playwright test --ui --ui-host=0.0.0.0 --ui-port=9323", "test:mutation": "stryker run", + "test:translator-hints": "node --test scripts/tests/check-translator-hints.test.mjs", "test:watch": "vitest", "ts:check": "vue-tsc --noEmit", "typescript:generate": "npx openapi-typescript -t", diff --git a/scripts/check-translator-hints.mjs b/scripts/check-translator-hints.mjs new file mode 100644 index 0000000000..90f84c3c5d --- /dev/null +++ b/scripts/check-translator-hints.mjs @@ -0,0 +1,94 @@ +/** + * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + * + * Nextcloud associates each translator hint with only the first translation + * call on the next line. Guard against multiple calls on a source line. + */ +import { execFileSync } from 'node:child_process' +import process from 'node:process' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { fileURLToPath } from 'node:url' + +const translationCall = /(? 1) { + badLines.push(index + 1) + } + } + return badLines +} + +const translatorHint = /^\s*(?:\/\/|#|', + "{{ t('libresign', 'Review') }}", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(valid), []) + + const colon = ':' + const invalid = [ + '// TRANSLATORS' + colon + ' Label to confirm a saved document.', + "const save = t('libresign', 'Save')", + '', + "{{ t('libresign', 'Review') }}", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(invalid), [ + { line: 1, message: 'Use TRANSLATORS without a colon.' }, + { line: 3, message: 'Use TRANSLATORS without a colon.' }, + ]) +}) + +test('blocks triplicated translator hints above one translation', () => { + const source = [ + '', + '', + '', + "{{ t('libresign', 'Approved') }}", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(source), [ + { line: 2, message: 'Use only one TRANSLATORS hint for a translation.' }, + { line: 3, message: 'Use only one TRANSLATORS hint for a translation.' }, + ]) +}) + +test('blocks two consecutive hints even if their text differs', () => { + const source = [ + '// TRANSLATORS Describes a document state.', + '// TRANSLATORS Describes an approval state.', + "return t('libresign', 'Pending')", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(source), [ + { line: 2, message: 'Use only one TRANSLATORS hint for a translation.' }, + ]) +}) + +test('permits repeated context only for distinct translation calls', () => { + const source = [ + '// TRANSLATORS Label on the approval button.', + "return t('libresign', 'Approve')", + '// TRANSLATORS Label on the approval button.', + "return t('libresign', 'Approve')", + ].join('\n') + assert.deepEqual(findTranslatorHintProblems(source), []) +}) + +test('blocks a one-line conditional with two translation calls', () => { + const source = [ + '// TRANSLATORS Only the first translation receives the hint on this source line.', + "const label = approved ? t('libresign', 'Approved') : t('libresign', 'Pending')", + ].join('\n') + assert.deepEqual(findAmbiguousTranslatorLines(source), [2]) +}) + +test('blocks nested translations on a single source line', () => { + const source = [ + "return t('libresign', 'Status: {status}', { status: t('libresign', 'Unknown') })", + ].join('\n') + assert.deepEqual(findAmbiguousTranslatorLines(source), [1]) +}) + +test('does not count commented-out examples as runtime translations', () => { + const source = [ + "// return [t('libresign', 'Save'), t('libresign', 'Cancel')]", + '', + "{{ t('libresign', 'Ready') }}", + ].join('\n') + assert.deepEqual(findAmbiguousTranslatorLines(source), []) +}) diff --git a/src/components/LeftSidebar/LeftSidebar.vue b/src/components/LeftSidebar/LeftSidebar.vue index c1fa28f173..f5d09da339 100644 --- a/src/components/LeftSidebar/LeftSidebar.vue +++ b/src/components/LeftSidebar/LeftSidebar.vue @@ -23,7 +23,7 @@ - + - {{ selectedCount > 0 ? t('libresign', '{count} selected', { count: selectedCount }) : t('libresign', 'Select all') }} + {{ selectionLabel }} [ }, ]) const selectedCount = computed(() => selectedFiles.value.length) +const selectionLabel = computed(() => { + if (selectedCount.value > 0) { + // TRANSLATORS {count} is the number of selected PDF files in an envelope. + return t('libresign', '{count} selected', { count: selectedCount.value }) + } + // TRANSLATORS Action to select all PDF files in an envelope. + return t('libresign', 'Select all') +}) const allSelected = computed(() => files.value.length > 0 && selectedFiles.value.length === files.value.length) watch(() => props.open, (newVal) => { diff --git a/src/components/RightSidebar/RequestSignatureTab.vue b/src/components/RightSidebar/RequestSignatureTab.vue index 8bcd9b802d..645211128b 100644 --- a/src/components/RightSidebar/RequestSignatureTab.vue +++ b/src/components/RightSidebar/RequestSignatureTab.vue @@ -746,12 +746,12 @@ function notificationIssueFromStatus(status: NotificationStatus | null): Notific return { type: allFailed ? 'error' : 'warning', message: allFailed - // TRANSLATORS: Every delivery method failed or was canceled. + // TRANSLATORS Every delivery method failed or was canceled. ? t('libresign', 'Could not send the notification. Check the request before trying again.') : status?.status === 'attention_required' - // TRANSLATORS: At least one delivery method has an uncertain or failed result. Retrying may cause duplicates. + // TRANSLATORS At least one delivery method has an uncertain or failed result. Retrying may cause duplicates. ? t('libresign', 'Some notifications may not have been sent. Check with the signer before trying again.') - // TRANSLATORS: The result of the sending request is unknown. Retrying may send a duplicate. + // TRANSLATORS The result of the sending request is unknown. Retrying may send a duplicate. : t('libresign', 'Could not check whether the notification was sent. Ask the signer before trying again.'), channels, } @@ -1724,7 +1724,7 @@ async function sendNotify(signer: EditableRequestSigner): Promise { // Keep actionable validation errors from the server; no duplicate status card. showRequestError(result.error, t('libresign', 'Could not send the notification')) } else if (result.kind === 'accepted') { - // TRANSLATORS: A delivery service accepted the message, but the recipient's receipt is not known. + // TRANSLATORS A delivery service accepted the message, but the recipient's receipt is not known. showSuccess(t('libresign', 'Notification sent for delivery')) } else { notificationIssues.value[signerId] = notificationIssueFromStatus(latestStatus) diff --git a/src/components/validation/CertificateChain.vue b/src/components/validation/CertificateChain.vue index ab5a1a42bd..81c34e4d50 100644 --- a/src/components/validation/CertificateChain.vue +++ b/src/components/validation/CertificateChain.vue @@ -11,7 +11,7 @@ :aria-expanded="chainOpen ? 'true' : 'false'" @click="chainOpen = !chainOpen"> - +
{{ cert.subject?.CN || cert.name || cert.displayName }}
- +
{{ t('libresign', 'Issued by:') }}
{{ cert.issuer.CN }}
- +
{{ t('libresign', 'Serial Number:') }}
{{ cert.serialNumber }} @@ -55,12 +55,12 @@
- +
{{ t('libresign', 'Certificate valid from:') }}
{{ formatTimestamp(cert.validFrom_time_t) }}
- +
{{ t('libresign', 'Certificate valid until:') }}
{{ formatTimestamp(cert.validTo_time_t) }}
diff --git a/src/components/validation/EnvelopeValidation.vue b/src/components/validation/EnvelopeValidation.vue index 3a136bc720..f09001ced3 100644 --- a/src/components/validation/EnvelopeValidation.vue +++ b/src/components/validation/EnvelopeValidation.vue @@ -79,7 +79,7 @@ - +

- + {{ t('libresign', 'The certificate expiry date is not the document expiry date. Expiration after signing does not, by itself, invalidate the signature.') }}

@@ -112,7 +112,7 @@